Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- pfw:template [2023-02-06 20:25] – created uho
+++ pfw:template [2023-09-04 19:18] (aktuell) – ↷ Seite von en:pfw:template nach pfw:template verschoben uho
@@ Zeile 1: / Zeile 1: @@
-This is the default
+===== Template - A new Idea =====
+So - you want to describe a new idea? Great.
+We give some guidelines how to do it. Below we describe the idea of a **DUMP** utility with parts that we find useful. This text is written in [[wiki:syntax|Wiki syntax]]. You are invited to make experiments in the [[playground:playground|playground]].
+Just edit this text and adapt it to your idea. If in doubt you can always save a draft and come back later.
+Thanks for your contribution,
+The Project Forth Works Team
+----
+===== DUMP memory algorithm: display content of main memory =====
+==== DUMP idea ====
+A DUMP utility is a software tool that allows to inspect main memory and display it in a user readable form.
+Typically output is composed of several lines that have the structure:
+Display bytes starting in memory at a given address in hex (or other radix). Behind them is the ASCII representation of these bytes.
+The DUMP utility is normally called ''DUMP'' and is invoked with parameters which specify what memory to inspect, often start address and length.
+==== DUMP Implementation ====
+One way to implement DUMP is to iterate in a loop line by line through memory. Say you want to display 16 bytes in each line, then this loop will start
+at the start address and increment the address by 16 in each loop iteration. (If you want a different number of bytes in each line, adjust accordingly).
+When you display memory in a single line you first output the current address and then have two loops that run one after the other iterating both from 0 to 15.
+The first loop outputs bytes with two hexadecimal digits (or in decimal, or whatever you intend) and the second loop outputs the individual bytes as ASCII characters.
+As some characters might control the output in a special way (so called control character such as 07 bell, 0A linefeed, 0C formfeed) it is wise to just output a period
+instead of the actual character, in order to get a well formatted display.
+==== Pseudo code for the DUMP implementation ====
+//What [[en:pfw:pseudocode|Pseudo code]] is.//
+<code>
+Function: dump-line ( address -- )
+  output address (possibly right aligned)
+  output ":" and some space
+  LOOP i from 0 to 15:
+     output byte in memory at (address+i) as two hexadecimal digits (or in another radix if desired)
+     output some space
+  LOOP i from 0 to 15:
+     output byte in memory at (address+i) as an ASCII character, "." if that character is a control character (byte<32)
+Function: dump ( address length -- )
+   WHILE length is positive:
+        dump-line at address
+        increase address by 16
+        decrease length by 16
+</code>
+==== Minimal Forth implementation of DUMP: ====
+You can find a [[https://github.com/Project-Forth-Works/Project-Forth-Works.github.io/blob/main/minimalforth.md|Minimal Forth]] implementation of DUMP in [[en:pfw:dump-minimal_forth.fs|dump-Minimal_Forth.fs]].
+You can use it as follows:
+<code forth>
+  ok
+Create x 100 allot  ok
+x 100 dump
+D694: 05 61 6C 6C 6F 74 08 00 DF 14 00 00 C1 00 08 00   .allot..?...?...
+D6A4: 1F 18 00 00 C1 00 08 00 6F 10 00 00 C1 00 08 00   ....?...o...?...
+D6B4: 4F 10 00 00 C2 00 08 00 1F 13 00 00 C2 00 08 00   O...?.......?...
+D6C4: 8F 30 00 00 C2 00 08 00 DF 14 00 00 C2 00 08 00   ?0..?...?...?...
+D6D4: 1F 18 00 00 C2 00 08 00 6F 10 00 00 C2 00 08 00   ....?...o...?...
+D6E4: 4F 10 00 00 C3 00 08 00 8F 30 00 00 C3 00 08 00   O...?...?0..?...
+D6F4: 5F 13 00 00                                       _... ok
+</code>
+As the original Minimal Forth has no output facility other than ''emit'' and ''.s'' (specifically no number formatting and no ''.'' or ''.r'')
+this implementation seems to be over complicated.
+We extended Minimal Forth to [[https://github.com/Project-Forth-Works/Project-Forth-Works.github.io/blob/main/minimalforth.md|GenericForth]] to get a
+more useful small Forth.
+A DUMP utility in **GenericForth** can be found in [[en:pfw:dump-genericforth.f|dump-GenericForth.f]]
+This example is factored using the pseudo code description. The character output has been factored into the useful word PEMIT ( char -- ) too.
+==== Various DUMP Implementations ====
+Other DUMP implementations can be found at the end of this description.
+Your system might lack right justified number output or even BASE for printing numbers in other radix systems. The sample implementation in [[en:pfw:twomoredumps.f|twomoredumps.f]] show how to circumvent this.
+==== Background information ====
+More about the DUMP utility can found at the [[https://en.wikipedia.org/wiki/Hex_dump|Wikipedia page for hexdump]]
+Some Forth DUMP implementations display a fixed amount of bytes and leave the updated address on the stack so that
+you can invoke DUMP repeatedly to display successive regions of memory.
+==== Possible pitfalls with DUMP ====
+Some systems have hardware memory protection that is triggered if you access memory outside the reserved area.
+The dump utility can do so by trying to show this forbidden memory. Triggered memory protect might stop the current process and
+terminate your session. If necessary a suitable test for the validity of used addresses might be reasonable on such systems so that
+dump can issue a normal error message (or display dummy data) in theses cases and leave the system / session otherwise intact.
+==== Contributions ====
+<html><h2 style="background-color:yellow">Alternative Implementations</h2></html>
+You have another approach to DUMP?
+Please add it at the end of this document.
+~~DISCUSSION~~