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

Transcription

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

2 Introduction This document is the first 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 covers the basics of Forth for Open Firmware. It provides definitions of Forth Terms, an outline of the Open Firmware structure, Basic I/O and basic Units and arithmetic operations of the Forth language. 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 second document of this series. 2/1/01 version 0.9 (part I) 2

3 What is Forth? Programming Language Interactive & Extensible User Interface Developed by Charles Moore 1970 National Radio Astronomy Observatory 2/1/01 version 0.9 (part I) 3

4 What is Forth at Apple? Programming Language for IEEE 1275 IEEE Standard for Boot (Initialization Configuration) Firmware The Open Firmware specification Used for booting Mac OS Used by PCI devices FCode drivers Plug and play Built In Self Test (BIST) Used by engineers to debug devices Used for hardware bringup Test and Initialization of New Hardware 2/1/01 version 0.9 (part I) 4

5 Course Material Definition of certain basis terms Forth System Dictionary Interpreter User interface Fundamentals 2/1/01 version 0.9 (part I) 5

6 Forth Terms Word Address Unit Name Dictionary Data stack Return stack Cell User Interface Interpreter FCode 2/1/01 version 0.9 (part I) 6

7 Definition of terms Word: The name of a Forth definition. In the text interpreter, word can also refer to a sequence of non-space characters to be processed. A Forth procedure or definition that does something (subroutine, command, etc.) A Word refers to a Forth definition as opposed to size or unit of data. 2/1/01 version 0.9 (part I) 7

8 Definition of terms Address Unit : The units, in Forth, which express the length of a region of memory. These units are usually bytes 2/1/01 version 0.9 (part I) 8

9 Definition of terms Name: What we call a Definition A Definition is a Forth execution procedure compiled into the dictionary. 2/1/01 version 0.9 (part I) 9

10 Definition of terms Dictionary: An extensible structure containing definitions and associated data space. Where we store words and do so in a top down manner The area in host memory where all Forth words are stored 2/1/01 version 0.9 (part I) 10

11 Definition of terms Data stack: An area of memory containing a last-in, first-out list of items that may be used for passing parameters between procedures. Used to pass arguments to words Forth uses the stack for memory and variables Note that the use of the term stack usually refers to the Data stack. 2/1/01 version 0.9 (part I) 11

12 Definition of terms Return stack: An area of memory containing a last-in, first-out list of items that may be used for program execution, temporary storage, and other purposes. Used to pass control between words & for looping The return stack is a second stack used for system purposes. It may also be used as a temporary stack by the Forth programmer; however, there are strong restrictions on such usage as specified by ANSI X3.2l /1/01 version 0.9 (part I) 12

13 Definition of terms Cell: The primary unit of information storage in the architecture of a Forth system. A unit of information in Forth system The word length of a processor is always referred to as a cell. This is also the size of an address, and is the size of a single item on Forth s stacks. 2/1/01 version 0.9 (part I) 13

14 Definition of terms User Interface: A command interpreter for humans to use. That portion of a Forth system that processes human commands 2/1/01 version 0.9 (part I) 14

15 Definition of terms Interpreter: An essentially closed executive routine which translates a stored pseudocode program into machine language and performs the desired and specific operations. An algorithm that processes and acts upon a string of commands When Forth Words are entered, they are both Processed & Run! 2/1/01 version 0.9 (part I) 15

16 Definition of terms FCode: A computer language defined by the IEEE 1394 standard, which is semantically similar to Forth, but is encoded as a sequence of binary byte codes representing a defined set of Forth definitions. FCode = Forth in "byte" form! 2/1/01 version 0.9 (part I) 16

17 Open Firmware (Forth) System Environment Three Interfaces User Interface Between Open Firmware and the human programmer Client Interface Between Open Firmware and the OS that is being "booted". i.e. Mac OS Device Interface Between Open Firmware and the developer s device. Used during probing 2/1/01 version 0.9 (part I) 17

18 User Interface Three Components of User Interface Basic I/O Dictionary Interpreter 2/1/01 version 0.9 (part I) 18

19 Basic I/O Input Command Line, "User" interface Cursor The cursor consists of 2 components. A numeric value indicating the depth of the data stack A Prompt (>) Indicating the data entry point Carriage Return A carriage return (<cr>) enters data onto the Stack # of Cells on the Stack 3 > 1234 Data{ 2/1/01 version 0.9 (part I) 19

20 Basic I/O Output Feedback Forth responds with after the carriage return. If input is recognized When data is entered, Forth "pushes the data on the stack and increments the stack depth. If input is NOT recognized An error message is displayed and the stack is emptied. 0 > 1234 <cr> 1 > Stack depth Incremented Forth Response 3 > qyz <cr> qyz, unknown word 0 > Empty Stack Error Message{ 2/1/01 version 0.9 (part I) 20

21 Basic I/O Output Data Stack Contents.s.s Displays the entire stack contents, unchanged. Contents are displayed in bottom to top order. (0 n) 0 > <cr> 3 >.s > Contents Stack{ Top of Stack (Last Entry) The Data Stack Bottom of Stack (First Entry) 2/1/01 version 0.9 (part I) 21

22 Dictionary The area in host memory where all Forth words are stored Stored as a linked list Stored in a top down fashion Last in first used (given duplicate Words)! ANSI X Forth words are the base set Built into the system User extensible words can be entered into the dictionary 2/1/01 version 0.9 (part I) 22

23 A word A word is separated by white space!!!!!! White space is: A new line, a tab, a space, a return or an enter character. ANSI words are built into a Forth system User words are defined using a colon definition A colon definition has the form: : name word_1 word_n ; White Space 2/1/01 version 0.9 (part I) 23

24 A Note About White Space In general, White Space, between data elements, is treated the same as entering a new cell on the stack. 0 > 1 1 > 2 2 > 3 3 > 4 4 >.s vs. 0 > >.s Where is White Space. 2/1/01 version 0.9 (part I) 24

25 A word example Using a colon definition, define a word that displays your name when you enter xyz at the user interface. A colon (:)( starts the definition and a semicolon (;) ends the definition. The Word definition's name = xyz. Dot quote (."(.") is a word that starts a display string that ends with quote ("). 0 > : xyz." hello it s me, Daffy Duck " ; Definition Start Name Quotation Start (Dot Quote) String Quotation End Definition End 2/1/01 version 0.9 (part I) 25

26 A word example (continued) hello it s me, Daffy Duck was the string A new word is entered into the Forth dictionary using the colon definition. : name word_1 word_n ; A word is executed by entering the name and a carriage return. xyz <cr> You can use the word "see" to display your word. see takes its argument from the next word in the input stream 2/1/01 version 0.9 (part I) 26

27 Interpreter Operation BEGIN Get a Word Search Dictionary Execute the Word Yes Word Found? No Attemp to convert Text to a Number Stack Underflow? Yes No Successful? No Issue Error Message Reset Stack & Interpreter Yes Push the Number onto the Stack ABORT! AGAIN go to BEGIN 2/1/01 version 0.9 (part I) 27

28 User Interface To enter the Open Firmware user interface start your Macintosh with the apple-option-o-f keys depressed (a.k.a. command, option, O, F keys) 2/1/01 version 0.9 (part I) 28

29 Fundamentals Stack Duplication dup Duplicate the top item on the stack 2dup Duplicate the top 2 items on the stack 3dup Duplicate the top 3 items on the stack?dup Duplicate the top item on the stack if it is nonzero dup 0> > dup 5>.s dup 0> > 2dup 6>.s dup 0> > 3dup 7>.s ?dup 0> >?dup 5>.s > >?dup 4>.s /1/01 version 0.9 (part I) 29

30 Fundamentals Stack Duplication over Copy 2nd stack item to the top of the stack 2over Copy 2nd pair of stack items to the top of the stack pick Copy N th stack item to the top of the stack 4 pick (copy 4th item) tuck Copy top stack item underneath the 2nd stack item over 0> > over 5>.s over 0> > 2over 6>.s pick 0> > 2 pick 5>.s tuck 0> > tuck 5>.s /1/01 version 0.9 (part I) 30

31 Fundamentals Stack Removal clear Empty the stack drop Remove the top item from the stack 2drop Remove the top 2 items from the stack clear 0> > clear 0>.s Empty drop 0> > drop 3>.s drop 0> > 2drop 2>.s 1 2 2/1/01 version 0.9 (part I) 31

32 Fundamentals Stack Removal 3drop nip Remove the top 3 items from the stack Remove the 2nd second stack item 3drop nip 0> > 3drop 1>.s 1 0> > nip 3>.s /1/01 version 0.9 (part I) 32

33 Fundamentals Stack Rearrangement roll Rotate n +1 stack items 1 roll (a b - - b a) 1 roll is same as swap rot Rotate the top 3 stack items (left) rot (a b c - - b c a) -rot Rotate the top 3 stack items (right) -rot (a b c - - c a b) 2rot Rotate the top 3 pairs of stack items (left) 2rot (a b c d e f - - c d e f a b) roll 0> > 2 roll 4>.s rot 0> > rot 4>.s rot 0> > -rot 4>.s rot 0> > 2rot 8>.s /1/01 version 0.9 (part I) 33

34 Fundamentals Stack Rearrangement swap Exchange the top 2 stack items 2swap swap (a b - - b a) Exchange the top 2 pairs of stack items depth 2swap (a b c d - - c d a b) Return the count of items on the stack swap 0> > swap 4>.s swap 0> > 2swap 4>.s depth 0> > depth 5>.s /1/01 version 0.9 (part I) 34

35 Fundamentals Return Stack >r r> Move the top data stack item to the return stack Move the top return stack item to the data stack Copy top return stack item to the data stack 2/1/01 version 0.9 (part I) 35

36 Fundamentals Arithmetic: Radix Single Precision Operators Bitwise Logical Operators Address Arithmetic 2/1/01 version 0.9 (part I) 36

37 Arithmetic Words that set or change the numeric conversion radix octal Sets the numeric conversion radix to eight Sets the radix to base 8 decimal e.g Sets the numeric conversion radix to ten Sets the radix to base 10 hex (hexadecimal) e.g Sets the numeric conversion radix to sixteen Sets the radix to base 16 * Default * e.g a b c d e f 10 2/1/01 version 0.9 (part I) 37

38 Arithmetic (Integer) Single Precision Operators + Add the 2nd and 1st numbers on the top of the stack, decrement the stack and replace the top of the stack with the sum - Subtract the 1st from the 2nd number on the top of the stack, decrement the stack and replace the top of the stack with the difference * Multiply the 2nd and 1st numbers on the top of the stack, decrement the stack and replace the top of the stack with the product / Divide the 1st by the 2nd number on the top of the stack, decrement the stack and replace the top of the stack with the quotient mod Divide the 1st by the 2nd number on the top of the stack, decrement the stack and replace the top of the stack with the remainder + - * / mod 0 > > + 3 >.s > > - 3 >.s > > * 3 >.s > > / 3 >.s > > mod 3 >.s /1/01 version 0.9 (part I) 38

39 Arithmetic (Integer) Single Precision Operators Increment the number on the top of the stack by 1 Decrement the number on the top of the stack by 1 Increment the number on the top of the stack by 2 Decrement the number on the top of the stack by > > 1+ 3 >.s > > 1-3 >.s > > 2+ 3 >.s > > 2-3 >.s /1/01 version 0.9 (part I) 39

40 Arithmetic Single Precision Operators (continued) abs Replace the number on the top of the stack with the absolute value of that number negate Negate value of the number on the top of the stack abs negate 0 > > abs 4 >.s ffffffff fffffffe fffffffd 4 0 > > negate 4 >.s fffffffc max Determine the maximum value of the 2nd and 1st numbers on the top of the stack, decrement the stack and replace the top of the stack with this value. max 0 > > max 3 >.s /1/01 version 0.9 (part I) 40

41 Arithmetic Single Precision Operators (continued) min Determine the minimum value of the 2nd and 1st numbers on the top of the stack, decrement the stack and replace the top of the stack with this value. even Replace the number on the top of the stack with the nearest even value that is greater than or equal to that number min even 0 > > min 3 >.s > > even 4 >.s bounds Prepare for a do or?do loop, where the top of the stack is the index and the 2nd from the top is the limit. (a looping parameter) (n cnt -- n+cnt n) bounds 0 > > bounds 2 >.s 3 1 Do 2 loops and stop at 1 2/1/01 version 0.9 (part I) 41

42 Arithmetic Bitwise Logical Operators lshift or << Shift the 2nd number on the top of the stack Left by the 1st number on the top of the stack (fill with 0), decrement the stack and replace the top of the stack with this value. rshift or >> Shift the 2nd number on the top of the stack Right by the 1st number on the top of the stack (fill with 0), decrement the stack and replace the top of the stack with this value. 2* Shift the number on the top of the stack Left by one bit (fill with 0), decrement the stack and replace the top of the stack with this value. 2/ Shift the number on the top of the stack Right by one bit, decrement the stack and replace the top of the stack with this value. lshift or << (shift 2 left, 1 time) rshift or >> 2* 2/ (shift 4 right, 2 times) (< 0100 = 1000) (>0100 = 0010) 0 > > lshift 3 >.s > > >> 3 >.s > > 2* 4 >.s > > 2/ 4 >.s /1/01 version 0.9 (part I) 42

43 Arithmetic Bitwise Logical Operators and Bitwise AND the 2nd number from the top of the stack with the1st number on the top of the stack, decrement the stack and replace the top of the stack with this value. or Bitwise OR the 2nd number from the top of the stack with the1st number on the top of the stack, decrement the stack and replace the top of the stack with this value. xor Bitwise Exclusive OR the 2nd number from the top of the stack with the1st number on the top of the stack, decrement the stack and replace the top of the stack with this value. invert or not Bitwise invert the number on the top of the stack replace it with this value. and or xor (0101 & 0110 = 0100) ( = 0111) (0101 ^ 0110 = 0011) invert or not (~ 0011 = 1100) 0 > > and 3 >.s > > or 3 >.s > > xor 3 >.s > > not 3 >.s 1 2 fffffffc 2/1/01 version 0.9 (part I) 43

44 Arithmetic Address Arithmetic /c Put the number of address units to a byte Value = 1 /w Put the number of address units to a doublet (doublet = A unit of data consisting of 16 bits) Value may vary between versions of systems. Typically 2 /l Put the number of address units to a quadlet (quadlet = A unit of data consisting of 32 bits) Value may vary between versions of systems. Typically 4 /c /w /l 0 > /c 1 >.s 1 0 > /w 1 >.s 2 0 > /l 1 >.s 4 2/1/01 version 0.9 (part I) 44

45 Arithmetic Address Arithmetic /n Put the number of address units to a cell. Value may vary between versions of systems. cells Multiply the number on the top of the stack by the value of /n and replace the top of the stack with this value. cell+ Increment the number on the top of the stack by the value of /n and replace the top of the stack with this value. /n cells cell+ 0 > /n 1 >.s 4 0 > > cells 1 >.s > > cells 1 >.s /1/01 version 0.9 (part I) 45