Learning Forth. Developer Technical Support DTS. for Macintosh Open Firmware (Part II) 2/1/01 version 0.9 1

Transcription

1 Learning Forth for Macintosh Open Firmware (Part II) Developer Technical Support DTS 2/1/01 version 0.9 1

2 Introduction This document is the second in a series of documents intended for hardware designers and device driver programmers that would like to learn and use Forth to examine, access and control hardware from low level in Open Firmware. This document expands upon the basics covered in the first document in the series of Forth for Open Firmware. It provides definition of Forth comment and notation styles, memory management and manipulation, simple printing and text editing and basic flow control and looping functions. This document was originally created as a "PowerPoint" presentation and intended to be a tutorial for Forth in Open Firmware. Slides are in a sequential order, where later (higher numbered) slides build on and assume familiarity with earlier (lower numbered) slides. This documents is intended to cover enough of basic concepts and information about the Forth language and Open Firmware for developers to use some of the features in the Open Firmware environment. Detailed and complete information about Forth and Open Firmware is left to the documents listed under Reference Material in the this document. 2/1/01 version 0.9 2

3 Stack Notation Stack Diagram The Stack Diagram (or Stack Effect Comment) is a programmer s notational convention used to show the effect of a Forth word on the Data Stack. The Syntax is as follows: ( stack item(s) before operation -- stack item(s) after operation ) * note that the parentheses are treated as "comment" characters in Forth, allowing stack effects to be part of the source code. 2/1/01 version 0.9 3

4 Stack Notation (example) Note that the Stack Comment only identifies the Stack effects before and after the function and not the function itself. White Space White Space Separator Before + ( nexecution n -- n ) After Execution Forth Word Comment Start 2nd Item from the Top of the Stack 1st Item from the Top of the Stack Result (on the top of the stack) Comment End 2/1/01 version 0.9 4

5 Stack Notation (Data Types) C: = Compile-time behavior R: = Return stack effect Symbol Data Type Stack Size a-addr A byte address that is cell-aligned 1 cell addr Address. 1 cell b A byte 1 cell c or char An ASCII character 1 cell c-addr A byte address that is character-aligned 1 cell d A double-precision, signed, t wo's complement int eger 2 cells dest Control-flow dest ination. Implement a tion dependent echar Extended character 1 cell flag A single-precision, Boolean t rut h flag 1 cell i*x, j*x, et c. Zero or more cells of unspecified data type Varies ior Result of an I/ 0 operation 1 cell len Leng th of a, string 1 cell loop-sys Loop-cont rol. parameters Implementation dependent nest -sys Implement a tion-dependent info. for procedure calls. Implement a tion dependent n A signed, single-precision, t wo's complement number 1 cell +n A single-precision number that may not be negative 1 cell orig Cont rol-flow origin. Implement a tion dependent u An unsigned, single-precision int ege 1 cell ud An unsigned, double-precision integer 2 cells x A cell (single stack item), ot herwise unspecified. 1 cell xt Execut ion token 1 cell 2/1/01 version 0.9 5

6 Memory Memory Manipulation Words Allocating and Freeing Memory Storing and Fetching Memory 2/1/01 version 0.9 6

7 Memory Manipulation Words alloc-mem (len -- a-addr) allocates len bytes of memory free-mem (a-addr len -- ) frees a portion of memory at addr of len bytes allocated by alloc-mem! (x a-addr -- ) store item x to the cell at a-addr (a-addr -- x ) fetch item x from the cell at a-addr READ dump (addr +n -- ) display len bytes of memory starting at addr off (a-addr -- ) store FALSE to the cell at a-addr on (a-addr --) store TRUE to the cell at dump off on ( Address = ff9cf0d0 Data = ) ff9cf0d0! ok ok 1 > ok ff9cf0d0 4 dump ff9cf0d0: :.4Vx: ok ff9cf0d0 off ok ok 1 >. 0 ok ff9cf0d0 on ok ok 1 >. ffffffff ok 2/1/01 version 0.9 7

8 ( Address = ff9cf0d0 Data = ) Memory Manipulation Words move (src-addr dest-addr len -- ) copy len bytes from src-addr to dest-addr fill (addr len byte -- ) set len bytes beginning at addr to the value byte blank (addr len -- ) set len bytes beginning at addr to the value 0x20 erase (addr len -- ) set len bytes, beginning at addr to zero pad ( -- addr ) return addr of temp storage area (84 char min.) tib ( -- addr ) return addr of the text input buffer move fill blank erase pad tib ff9cf0d0 ff9dd7e0 4 move ok ok 1 >. ffffffff ok ff9cf0d0 4 aa fill ok ok 1 >. aaaaaaaa ok ff9cf0d0 4 blank ok ok 1 > ok ff9cf0d0 4 erase ok ok 1 >. 0 ok pad ok 1 >. ff801e00 ok tib ok 1 >.s ff801c00 ok 1 > 6 dump ff801c00: d 70 :6 dump: ok 2/1/01 version 0.9 8

9 Allocating and Freeing Memory alloc-mem (len -- a-addr) alloc-mem takes the len value entered, off the stack and attempts to allocate that many bytes. If successful, alloc-mem places the starting address of these bytes on the stack. You must save this address in a variable! Allocated memory is contiguous. Multiple (back to back) allocations are not generally contiguous. 8 ok 1 > alloc-mem ok 1 >.s ff9cf0d0 ok 2/1/01 version 0.9 9

10 Alocating and Freeing Memory free-mem (a-addr len -- ) free-mem takes the length and address values entered, off the stack and frees that portion of memory. Always use alloc-mem and free-mem in pairs so as not to have memory leaks or worse! alloc-mem without free-mem will results in memory leaks! free-mem without alloc-mem will result in arbitrary behavior! ( i.e. crash and burn!!) ff9cf0d0 ok 1 > 8 ok 2 > free-mem ok 2/1/01 version

11 Storing and Fetching Memory! Forms of Store 2! (x1 x2 a-addr -- ) store item x1 & x2 to aaddr c! (byte addr -- ) store byte to addr w! (w waddr -- ) store (2 byte) word w to waddr l! (quad qaddr -- ) store (4 byte) long word quad to Forms of Fetch 2@ (a-addr -- x1 x2) fetch item x1 & x2 from a-addr c@ (addr -- byte) fetch byte from addr w@ (waddr -- w) fetch (2 byte) word w from waddr l@ (qaddr -- quad) fetch (4 byte) long word quad from qaddr 2/1/01 version

12 Storing and Fetching Memory ( Address = ff9cf0d0 Data = ) 2! c! w! l! abcdef ff9cf0d0 2! ok ff9cf0d0 2@ ok 2 >.s abcdef ok 2 > 12 ff9cf0d0 c! ok ff9cf0d0 c@ ok 1 >.s 12 ok 1 > 1234 ff9cf0d0 w! ok ff9cf0d0 w@ ok 1 >.s 1234 ok 1 > ff9cf0d0 l! ok ff9cf0d0 l@ ok 1 >.s ok 1 > 2@ c@ w@ l@ 2/1/01 version

13 Text (I/O) Text Input Comments ( ( [text< ) >] -- ) Ignore immediately following text until ) \ ( [rest-of-line< cr >] -- ) Ignore immediately following text for the rest of the line 2/1/01 version

14 Console (I/O) Input key? ( -- pressed?) return true if key is pressed key ( -- char) read char from input device expect (addr len -- ) get an edited input line of length len and store it at addr accept (addr len1 -- len2 ) get an edited input line of length len and store it at addr Output." ([text< >] -- ) display the following text until.( ([text< ) >] -- ) display the following text until ) emit ( char -- ) display the ASII char on the stack type (text-str text-len -- ) display the text-len starting at address text-str Formatting cr ( -- ) start a new line on the display space ( -- ) display a space spaces ( cnt -- ) display cnt number of spaces 2/1/01 version

15 Console (I/O) Input key? ( Address = ff9cf0d0 Data = ) key? \ Meant for programming. Will execute on <cr> ok 1 >. 0 ok \ Note the stack counter after <cr>. key expect accept key \ Pressing the "2" key. ok 1 >. 32 ok \ 32 is ASCII for "2". ff9cf0d0 8 expect ok ff9cf0d0 8 dump ff9cf0d0: : : ok ff9cf0d0 8 accept ok 1 >. 8 ok ff9cf0d0 8 dump ff9cf0d0: : : ok 2/1/01 version

16 Console (I/O) Output." ( Address = ff9cf0d0 )." This is a Test" This is a Test ok \ same as.(.( emit type.( This is also a Test) This is also a Test ok \ same as." 32 emit 2 ok \ Since 32 is "2" in ASCII ff9cf0d fill ok ff9cf0d0 l! ok ff9cf0d4 l! ok ff9cf0d8 l! ok 7354 ff9cf0dc w! ok ff9cf0d0 e dump ff9cf0d0: :This is a TesT: ok ff9cf0d0 e type This is a TesT ok 2/1/01 version

17 Console (I/O) Formatting cr cr." This is a test" cr This is a test ok space." This" space." is" space." a"." test" This is atest ok spaces." This is" 3 spaces." a test" This is a test ok 2/1/01 version

18 Flow Control if ( do-next? -- ) ( C: -- orig-sys ) When flag is TRUE, execute the following code. else ( -- ) ( C: orig-sys1 -- orig-sys2 ) When if flag is FALSE, execute the following code. then ( -- ) ( C: orig-sys-- ) Terminate an if construct case ( sel -- sel ) ( C: -- case-sys ) Begin a case (multiple selection) statement of ( sel of-val -- sel <nothing> ) ( C: case-sys1 -- case-sys2 of-sys ) Begin of clause; execute through endof if params match. endof ( -- ) ( C: case-sys1 of-sys -- case-sys2 ) Mark end of clause; jump to end of case if match. endcase ( sel <nothing> -- ) ( C: case-sys -- ) Mark end of case statement. 2/1/01 version

19 Flow Control (if, then, else example) if : xxx a = if." decimal 10" else." Not Ten!" then ; else True Clause (executed if True) Begin IF statement False Clause (executed if False) End IF statement then : xxx a = if." decimal 10" else." Not Ten!" then ; ok 10 xxx Not Ten! ok a xxx decimal 10 ok 2/1/01 version

20 Flow Control ( CASE example) case a of cr. you typed a endof b of cr. you typed b endof c of cr. you typed c endof cr. what you typed wasn t a, b, or c endcase 2/1/01 version

21 Flow Control ( CASE example dissected) case case Begin CASE statement of endof a of cr." you typed 'a' " endof ok Test Clause Case True Clause (executed if this case is True) b of cr." you typed 'b' " endof ok Begin CASE Clause End CASE Clause endcase c of cr." you typed 'c' " Test Clause Default Case Clause (executed if NO case is True) endof ok End CASE statement cr." what you typed wasn't 'a, b, or c' " endcase 2/1/01 version

22 Flow Control ( CASE example) case of endof endcase : yyy case ok 1 ] a of cr." you typed 'a' " endof ok 2 ] b of cr." you typed 'b' " endof ok 3 ] c of cr." you typed 'c' " endof ok 4 ] cr." what you typed wasn't 'a, b, or c' " endcase ; ok a yyy you typed 'a' ok b yyy you typed 'b' ok c yyy you typed 'c' ok 12 yyy what you typed wasn't 'a, b, or c' ok 2/1/01 version

23 Loops Conditional Infinite These continue to loop forever. Indefinite These loop until a specified condition is met. Counted These loop for a specified number of iterations. An induction variable is maintained and may be read from within the loop. 2/1/01 version

24 Conditional Loops (loop words) begin ( -- ) ( C: -- dest-sys ) begin a conditional loop until ( done? -- ) ( C: dest-sys -- ) end a begin until loop again ( -- ) ( C: dest-sys -- ) end a begin again loop while ( continue? -- ) ( C: dest-sys -- orig-sys dest-sys ) conditional test within a begin while repeat loop repeat ( -- ) ( C: orig-sys dest-sys -- ) end a begin while repeat loop 2/1/01 version

25 Conditional Loops (loop form) Infinite Loops example begin e. again \ display the e character infinitely use control - z to get out of this kind of loop begin words again repeated, loop, actions beginning loop word loop delimiter 2/1/01 version

26 Infinite Loop Example Objective: Create an infinite loop to emit * at the display The loop below won t work! begin * emit again This is because * is not a word or number To solve this problem, the ASCII value of * is needed. 2/1/01 version

27 Infinite Loop Example (Continued) How to determine ASCII value of a keystroke * \ ASCII * (asterisk) character The first line puts the "*" character on the stack as a string 2 >.s address_xyz length 2 > dump The.s word displays the address and length returned on the stack where the "*" string is stored The dump word dumps the length memory contents at address address_xyz: 2a :*: ok \ ASCII for *, is 2a Having obtained the ASCII value of "*", the solution for the example is below begin 2a emit again \ control z to exit 2/1/01 version

28 Infinite Loop Example (Result) How to determine ASCII value of a keystroke * \ ASCII * (asterisk) character 2 >.s ff \ ff = address, 1 = length 2 > dump ff810110: 2a :*: ok \ ASCII for *, is 2a begin 2a emit again \ control z to exit Now this loop will continually fill the display with * characters until the control - z keys are pressed. 2/1/01 version

29 Conditional Loops (loop form) Indefinite Loops Example (loop until encountering 4 on the stack) Begin Loop Loop Action Loop Test End Loop begin 4 = until Beginning loop word Put this value on the stack Compare the top 2 items on the stack Ending loop word a b c d e f ok f > begin 4 = until ok 3 >.s ok 2/1/01 version

30 Conditional Loops (loop form) Indefinite Loops Example (loop while encountering 4 on the stack) Begin Loop Loop Action Loop Test Conditional True Test True Action End Loop begin 4 = while cr." it's 4 repeat Beginning loop word Put this value on the stack Compare the top 2 items on the stack Pass through if True Display message while True Ending loop word (loop back if True ) ok 6 > begin 4 = while cr." it's 4 " repeat it's 4 it's 4 it's 4 ok 2 >.s 1 2 ok 2/1/01 version

31 Counted Loops (loop words) do ( limit start -- ) ( R: -- sys ) ( C: -- dotest ) begin a counted loop?do ( limit start -- ) ( R: -- sys ) ( C: -- dotest ) begin a counted loop if start = limit loop ( -- ) ( R: sys1 -- <nothing> sys2 ) ( C: dotest -- ) add 1 to index, loopback to do or exit +loop ( -- ) ( R: sys1 -- <nothing> sys2 ) ( C: dotest -- ) add delta to index, loop back to do or exit i or j ( -- index ) ( R: sys -- sys ) return i current loop counter or return j next loop counter leave ( -- ) ( R: sys -- ) exit the do or do? loop?leave ( exit? -- ) ( R: sys -- ) exit the do or do? loop if exit? is true unloop ( -- ) ( R: sys -- ) discard loop control parameters 2/1/01 version

32 Loops (Counted loop form) Finite Loops limit start do ( do something) loop limit start do ( do something) n +loop 2/1/01 version

33 Finite Loop Example Example: Begin colon definition Index Index Begin Limit Start Loop Index Loop Action End Loop End colon definition : x 3 0 do i cr." inner = ". loop ; Define a word x Put 3 and then 0 on the stack Start a do loop i is the index Print inner = and then the index value of i Repeat the loop and increment i. : x 3 0 do i cr." inner = ". loop ; ok x inner = 0 inner = 1 inner = 2 ok 2/1/01 version

34 Nested Loop Example Examples: Inner Loop : x 3 0 do i." inner =. loop ; Outer Loop Inner Loop : z 5 0 do i." outer =. cr x loop ; z calls x, the loop previously defined : x 3 0 do i." inner = ". loop ; ok : z 5 0 do i." outer = ". cr x loop ; ok z outer = 0 inner = 0 inner = 1 inner = 2 outer = 1 inner = 0 inner = 1 inner = 2 outer = 2 inner = 0 inner = 1 inner = 2 outer = 3 inner = 0 inner = 1 inner = 2 outer = 4 inner = 0 inner = 1 inner = 2 ok 2/1/01 version

35 Forth in Apple Open Firmware Further reading concerning Forth as it applies to Apple's Open Firmware: Apple Developer Technote: 1061 Apple Developer of Open Firmware, Part I: The User Interface Apple Developer Technote: 1062 Apple Developer of Open Firmware, Part II: The Device Tree Apple Technical Info Library Article ID: Apple Network Server 500,700: Open Firmware Read Me 2/1/01 version

36 Reference Material ANSI Forth IEEE IEEE Standard for Boot (Initialization Configuration) Firmware: Core requirements and Practices Starting Forth by Brodie (out of print) Forth Programmer s Handbook by Conklin & Rather 2/1/01 version