Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- pfw:template [2023-02-06 20:31] – uho
+++ pfw:template [2023-09-04 19:18] (aktuell) – ↷ Seite von en:pfw:template nach pfw:template verschoben uho
@@ Zeile 1: / Zeile 1: @@
-===== Template for a new idea called «name» =====
+===== Template - A new Idea =====
-==== «name» idea ====
+So - you want to describe a new idea? Great.
-Explain in a few words what the idea of this description is.
+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]].
-The reader should understand what this is about so that s/he can decide whether or not it is worthwhile to continue reading.
-What is the problem. How is the problem solved?
+Just edit this text and adapt it to your idea. If in doubt you can always save a draft and come back later.
-Continue also to explain background information and the idea proper. Is there a trick?
+Thanks for your contribution,
-==== Implementation ====
+The Project Forth Works Team
-Discuss a typical (possibly naïve) implementation that best allows to understand the implementation.
+----
-More sophisticated/optimized implementations can be presented later. Most system specific implementations will be optimized.
-==== Implementation in pseudo code ====
+===== DUMP memory algorithm: display content of main memory =====
-//Use pseudo code following this style://
+==== DUMP idea ====
-''Function: «name» ( input parameters -- results )
+A DUMP utility is a software tool that allows to inspect main memory and display it in a user readable form.
-  «prose text descripting operations in this function»
+Typically output is composed of several lines that have the structure:
-  Set «variable» to «description of value»
+Display bytes starting in memory at a given address in hex (or other radix). Behind them is the ASCII representation of these bytes.
-  «imperative subject object ...»
+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
-  IF: «condition»:
+  LOOP i from 0 to 15:
-     ...
+     output byte in memory at (address+i) as two hexadecimal digits (or in another radix if desired)
-  ELSE:
+     output some space
-     ...
-  WHILE: «condition»:
+  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 ====
-//For defining words use://
+Other DUMP implementations can be found at the end of this description.
-''Function:
+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.
-	Define: ( u -- )
-		Reserve RAM space
-		allocate ROM space
-	Action: ( -- a )
-		Leave start address of this
-''
-==== Generic Forth implementation: ====
-Try to implement the pseudo code using the words in [Generic Forth](https://github.com/project-forth-works/project-forth-works.github.io/blob/main/minimalforth.md) and the words listed in the file [well-known-words](https://github.com/project-forth-works/project-forth-works.github.io/blob/main/well-known-words.txt),
+==== Background information ====
-mentioning and explaining all other additional words that your implementation requires.
-Hardware details may come to the surface, but minimise them!
-//Also show how your implementation is used by giving some examples.//
+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.
-==== Various other Implementations ====
+==== Possible pitfalls with DUMP ====
-Present additional (possibly more sophisticated) implementations, e.g for a specific microcontroller board, a specific Forth system or in Standard Forth.
+Some systems have hardware memory protection that is triggered if you access memory outside the reserved area.
-Try to state precisely what implementations you present and what requirements they have. No need to be portable here: *Embrace the difference*
+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.
-==== Background information and possible Pitfalls ====
+==== Contributions ====
-Please give references to data sheets, background articles or articles for follow up reading.
+<html><h2 style="background-color:yellow">Alternative Implementations</h2></html>
-Also describe any problems that may arise in connection with the idea you are describing.
-What were stumbling blocks, what things are important for others to know?
----
+You have another approach to DUMP?
-For a simple example idea have a look at [The DUMP utility](https://github.com/project-forth-works/project-forth-works/tree/main/Programming-Tools/dump).
+Please add it at the end of this document.
+~~DISCUSSION~~