The Datafile PD-CD 5

home *** CD-ROM | disk | FTP | other *** search

/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / f / forthmac / !Forthmacs / docs / html / arm_hardw < prev next >

Wrap

Text File | 1997-05-01 | 16.0 KB | 336 lines

<html> <head> <title>Hardware Diagnostics in Forth</title> </head> <body> <h1>Hardware Diagnostics in Forth</h1> <hr> <h2>fine tools ...</h2> Forth has been long used for large numbers of hardware projects, both commercial and private. RISC OS Forthmacs is exceptionally stable and needs only very few resources on the computer. Here's how you can write Forth programs to diagnose your hardware. The programs can range from very simple things like reading a register to very complicated things like performing communications protocols. Each higher level of tests can build on the lower levels. At any time, you can interactively execute any part of the test, without having to build a command interpreter into your program. This document describes how to do very simple things interactively. It is also possible to save your work in a file and to make sequences of tests run automatically. <h2>Warning</h2> The examples in the rest of this document assume that you are running on a stand-alone system, and that there really are I/O devices located at the addresses mentioned. If you are running RISC OS Forthmacs under RISC OS or Unix, both won't allow you to access device registers, so the examples in this paper will cause a core dump of the Forth process. In fact, most of these examples assume that you are trying to debug a board whose registers begin at virtual address (hex) 3340000. In RISC OS computers this would be a Simple Exp. card with fast access, this might not be right for your system, so please pick an address for your system where you know there is some device or memory. <h2>Getting started</h2> The way to get Forth running on your machine is system-dependent, so we won't go into that topic here. We assume that you have already figured out how to get Forth going, and that it is prompting you with ok . <h2>Poking at registers</h2> The first hurdle to cross when debugging a new board is usually reading and writing the device registers. With most programming environments or monitors, if the register doesn't work, you are stuck. Not so with Forth. Suppose that you have a 32-bit register at address (hex) 3340000. You can read it with: <pre> 3340000 @ .</pre> @ says to read a 32-bit word from the preceding address. . says to print the result. @ is pronounced "fetch". In general, the @ symbol is pronounced fetch in Forth terminology. There must be one or more spaces separating symbols! Note: The Forth parser is really simple; it just grabs the next sequence of non-blank characters (called a word in the jargon) from the terminal and looks up that word in its internal dictionary. If it finds the word, it executes some associated code. If it doesn't find the word, it tries to parse the word as a number. If that fails, it complains. Note: @ accesses a 32-bit location, the address must be long-aligned. If your device is 8 bits wide, use <code><A href="_smal_BE#16C">c@</A></code> in this and future examples; also use <code><A href="_smal_BB#169">c!</A></code> instead of ! . There is a problem with 16-bit registers in ARM based computers, ARM cpus don't support word-wide 16-bit data access. You can use W@ and W! but both instructions use two byte-wide memory accesses, so this might not be what you wanted. Or you use 32-bit normal accesses and mask-off the other The most likely result of trying this exercise on a prototype peripheral board is that the board won't respond to the cycle, so the CPU will get a bus error, print a message, and abort back to Forth. On a working device, instead of getting an error, Forth will display the contents of the register you accessed. <h2>Scope Loops</h2> No, you don't have to get out your assembly language reference manual and try to figure out how to poke in a tiny loop. Here's how to make a loop: <pre> 3340000 constant reg-addr : test begin reg-addr @ drop key? until ; </pre> This creates a loop which will repeatedly read a register at location 3340000. <code><A href="_smal_AF#155">begin</A></code> ... <code><A href="_smal_BS#23A">key?</A></code> <code><A href="_smal_BC#31A">until</A></code> means to keep doing everything between the <code><A href="_smal_AF#155">begin</A></code> and the <code><A href="_smal_BS#23A">key?</A></code> until a key is typed on the keyboard. The <code><A href="_smal_BG#1CE">drop</A></code> is needed to get rid of the value that was read from the register, which is left on a stack. That stack would eventually overflow if not for the <code><A href="_smal_BG#1CE">drop</A>.</code> The loop is called test , and it is a new command which you have just created, you could have called it anything you wanted, instead of test . Remember that there will be an address exception if the physical address hasn't been accepted by the MMU. Now you can try the loop. <pre> test</pre> In general, the way to execute a Forth command is by typing its name. So now the machine is sitting there banging away at your register. You can try to find a scope that still has some probes attached and figure out why your register isn't responding. It wasn't actually necessary to have given the loop a name. You could have just typed: <pre> begin reg-addr @ drop again</pre> This is different from almost all Forth dialects, RISC OS Forthmacs knows about temporary compilation and forgets about the compiled code afterwards. However, by giving the command a name, you save it away so you can use it later, just by typing the name. It's not saved on disk, just in memory, so if you reboot, the new command will be lost. It would be nice if you could save your work on disk, but in a lot of stand-alone debugging cases there is no disk on the machine. To learn how you can save your work, read the "Creating Stand-Alone Forths" chapter <h2>Writing to registers</h2> Now that you can read your register, no doubt you want to write to it too. <pre> 1234 reg-addr !</pre> writes the 32-bit word 1234 (hex) to the address left by the word reg-addr (which we defined earlier). If you want to write a byte instead of a 32-bit word, use <code><A href="_smal_BB#169">c!</A>.</code> <pre> reg-addr @ .</pre> reads back the register and prints the value, so you can verify that the write actually worked. <h2>Do Loops</h2> An obvious thing to do now is to write a bunch of different values to the register and see if they all work. <pre> : test-loop ffff 0 do i reg-addr ! ( write a value to the register ) reg-addr @ ( read it back ) ( register value on stack ) i <> ( see if the value read back is different from the one written ) if ." Error - wrote " i . ." read " reg-addr @ . cr then loop ; </pre> The indentation is optional. If you were writing this test on-the-fly while sitting in the lab, you would probably not bother with indentation. Similarly, everything inside parentheses is a comment and may be omitted. When you are writing Forth programs to save (presumably using a Unix editor), please don't omit the comments or the indentation, because that would make your work hard to understand later. How does this test-loop work? Let's go over it line-by-line. ffff 0 are the arguments to the <code><A href="_smal_AP#1BF">do</A></code> ... <code><A href="_smal_AW#256">loop</A></code> construct. The loop starts at 0 and ends when the loop index reaches (hex) ffff. The last time through the loop, the index has the value (hex) fffe. The firs thing inside the loop is i reg-addr ! . Previously we used the literal number 1234 as the value to store into location reg-addr. This time we use the loop index i . The loop index is always called i . If you use nested loops, the index of the next outer loop is called j . The next thing we do inside the loop is read back the register. Previously we printed the value as soon as we read it; this time we will let the program look at and decide if it's okay. But where is the value kept? It's on the stack, just like on an HP calculator. In fact almost every operator in Forth takes its operands from the stack and leaves its results on the same stack. I will assume that this concept is familiar to you; if it isn't, let me know and I will either explain it to you or loan you a book which does so. Anyway, the register value is now sitting on the stack. The next thing we do is compare that value to the loop index i . The operator <code><A href="_smal_BI#110"><></A></code> (not-equal) compares the top two things on the stack and leaves true if they are not equal or false if they are equal. If the numbers are equal, all is well. If they are different, we need to print an error message. That is where the <code><A href="_smal_AW#226">if</A></code> ... <code><A href="_smal_BK#2F2">then</A></code> construct comes in. Here is the strange part: The stuff you want to do if the condition is true goes <code><A href="_smal_AH#157">between</A></code> <code><A href="_smal_AW#226">if</A></code> and <code><A href="_smal_BK#2F2">then</A>,</code> not after <code><A href="_smal_BK#2F2">then</A></code> as one would expect. This is unfortunate, but it is not the end of the world. The condition that is tested comes BEFORE the <code><A href="_smal_AW#226">if</A>;</code> in this case the condition is the true/false value left on the stack by the <code><A href="_smal_BI#110"><></A></code> operator. If this seems strange to you, consider that it is very simple, yet completely general. It is also possible to specify an <code><A href="_smal_BP#1D7">else</A></code> clause (details later). The only thing remaining for this test-loop is to describe how the error message is printed. The construct ." ... " , pronounced "dot-quote, prints whatever is inside the quotes. The first space after the first quote is mandatory and is not printed. Any subsequent spaces before the next quote are part of the string and are printed. Next we print the loop index with i . . As you have probably guessed, . just means print whatever number is on the stack. Next we print another string, followed by the value read back from the register. Finally, <code><A href="_smal_AV#195">cr</A></code> prints a carriage-return and linefeed. <h2>Extensibility</h2> Earlier we saw how to make a word called test which could then be executed by typing its name. Once you have made a word, you can then use it as part of another word, thus building on top of your previous work. For example, suppose that there is a dma address register on your board, and that its address is (hex) 3340804. You can define a word to store a value into that register as follows: <pre> : dma! 3340804 ! ;</pre> This defines a new word called dma! which takes an argument and stores it into the prescribed location. This word can be used as: <pre> f00000 dma!</pre> which will store f00000 into the dma register. Now, suppose that as part of a test, you need to automatically set the dma register. You can use your word dma! as part of another word. <pre> : init-dma f00000 dma! ;</pre> This is a trivial example, but it serves to illustrate the style of building up your application in small incremental steps. Don't hesitate to build words which only have a few components; the overhead of calling a word from one at higher level is quite small, and the advantages of small words are many (readability, ease of debugging, possibility of reuse). <h2>Variables</h2> Define a variable with <pre> variable foo</pre> The new variable foo has space for a 32-bit word. Put a number in the variable with: <pre> 129876 foo !</pre> and get it back with <pre> foo @</pre> The number to be stored is taken from the stack, and the number fetched is left on the stack. When you typed the 129876, that number was actually left on the stack, and foo ! picked it up and put in the variable foo. foo @ retrieved it from the variable and returned it to the stack. <h2>Constants</h2> A constant is a symbolic name for a number. In other words, when you type the name of a constant, it just leaves its number on the stack. One way of making a constant is the obvious: <pre> : mem-base 100000 ;</pre> Now the word mem-base is equivalent to the number 100000. A slightly more efficient form of this is: <pre> 100000 constant mem-base</pre> A word defined with <code><A href="_smal_AP#18F">constant</A></code> will execute somewhat faster than one defined the other way (but you would probably never notice the difference). <h2>C Language Analogies</h2> <pre> C Forth while( condition ) { BEGIN condition WHILE loop-body loop-body } REPEAT do { BEGIN loop-body loop-body until ( condition ) condition UNTIL for( i=start_value; end_value i<end_value; start_value i += increment ) { DO loop-body loop-body } increment +LOOP for( i=start value; end value i<end value; start value i++ ) { DO loop-body loop-body } LOOP if ( condition ) { condition true_clause IF true_clause } else { ELSE false_clause false_clause THEN } if ( condition ) { condition true_clause IF true_clause } THEN </pre> Forth Notes: "condition" is any sequence of Forth words that has the effect of leaving a number on the stack. If the number the stack is 0, the condition value is false, otherwise it is true. Within a do loop, the word i will put the loop index on the stack. <h2>One More Thing ...</h2> You may want to do a scope loop which can be easily interrupted. You can always abort back to RISC OS Forthmacs with Shift-Ctrl-F12. A nicer way, however, is the following: <pre> : scope-loop begin 1234 reg-addr ! key? until ;</pre> This word will continuously write 1234 to location reg-addr until you type any key. The word <code><A href="_smal_BS#23A">key?</A></code> returns true (which happens to be equal to -1) if a key has been depressed, and false (0) if not. <h2>Other Wonderful Features</h2> Forth includes, among other things, a resident assembler, so you can write little bits of assembly code if you need to. It has a built-in visual line editor, so you can edit command lines as you type them. There are packages for defining structures and bit fields, similar to C. A built-in decompiler allows you to interactively decompile any Forth word that you have previously defined. Try typing <code><A href="_smal_BR#2C9">see</A></code> followed by the name of any Forth command, or any Forth word you have already defined. <h2>Line Editing</h2> While you are typing a Forth command line, you can move around in the line and edit it. Have a look at the chapter Typing Forth Command Lines . </body> </html>