Welcome to Holon 11 

Now that host and target communicate, load code into the target and have some fun.

Setup ROM and RAM space according to your target board

The first words in the browser set up the memory spaces: SetROM and SetRAM in system module Basis. Adapt the values to the memory spaces of your target board: 

Press Ctrl+Home to move to the start of the program. Go to the word SetROM, if you are not already there, and press F2=Edit. Change the memory values in SetROM. Press Ctrl+PgDn and change the memory values in SetRAM. Press <Esc> to exit the Text window.  

Load the program

Press Ctrl+F2=InitCode, then press Ctrl+F3=LoadAll. Holon11 clears the code space and sets up the internal pointers, then it loads the program sequentially starting with the first word in the browser. Watch the progress in the browser: Holon11 marks the currently loaded group. 

Test a word

Test the simple word dup.    -- If dup works, the whole system works. --   Use the direct access method to go to dup: press the space bar and type  d u p . This brings you to the word.

You need a number on the stack as an argument for dup. Type a number, say: 77. The first digit opens the stack entry field. Press <Enter> to finish the entry. 

Now execute dup: Press F4=Run. If all is well, you see your number duplicated on the stack. -- The number was sent to the target, the word was executed, and the target stack was again sent to the host. 

Testing a simple word builds confidence. You see immediately in the stack window, whether the word - and the system - works. The stack shows the result. 

If there is a problem, you might like to look into the code and watch its action step by step? Let's do it.

Step through dup

Press Alt+F4=Debug. Holon11 shows the current values of the CPU registers and marks the first step in the definition. If the stack window has base=10 (decimal), press Alt+B and change to  hexadecimal. 

Press F4 to execute the first step. Check the X register and see the action of PULX, the first instruction in dup. Press F4 again and watch the stack. Continue until the end. 

Note that you stay in the comfort of the browser even while debugging. I like immediate access to my application program in all details, and that's what Holon provides me. 

Have a look at the code

If the debugger points out a problem, a look at the generated binary code in memory might help.

Press F6=Code and look into the program code. If the code window is marked "DATA", press F6 once more for "PROG". 

If the code lines start with F, you are watching the memory image in the code file. Press T to see the code in the target memory. If the memory content is displayed normally (white on blue), the code in the target is equal to the code in the file. Code that is marked (yellow on magenta) differs between file and target. 

Check the code of dup. The code is framed in yellow brackets {}. You should recognize the opcodes in the definition of dup.

If the code in the target is incorrect, try and load the program again. If all code is wrong, there is a memory addressing problem. This can happen with the 68HC11F1, if your board uses unconventional chip selects. See the application note Holon 11 monitors. 

Test a high-level word

Go to the word m*  ('m-star') and read about its function. Enter two numbers on the stack and execute the word. 

The result is a 32 bit double number. The stack window displays the double number as separate high and low 16 bit values. 

Have a good look at the definition of m*: Enter the editor (press F2 or <Enter>), put the cursor on "2dup" and press F7=GoLook. Holon takes you to the definition of 2dup. Go back with F8 and look up other words in the definition. In this particular case all words in m* are code words, however, the words in the definition can be any type. You see here the principle of Forth: All existing words can be used to create new "high-level" words. I call them colon words, since high-level Forth words are defined with an initial ':' .

Step trough m*

Let's have a very close look at the action of m* and explore the debugger a little more..

From the previous test there should still be two numbers on the stack, otherwise please supply two nice values for the test. Press Alt+F4=Debug and check the stack window. Since you are now testing a colon word, the CPU registers are replaced by the contents of the return stack, which is of more interest here. 

The word is called by the Forth machine (the "inner interpreter"). The Forth machine first stores the current instruction pointer on the return stack, and then passes control to the colon word. The final ; (semicolon) in the word retrieves the instruction pointer from the return stack and returns control. 

See the instruction pointer of the calling word on the return stack. Step and observe the action. 

Step to the word swap, press F3=GoSub and have a look at the definition of swap. The browser jumps to the word swap and lets you continue execution through its code. The CPU registers are displayed, because swap is a code word. 

Step to the end of swap and see Holon return to the calling word m*. Press F6=run and let the execution continue until the end of the word. 

You can follow the execution of the program step-by-step through all subwords, even down through the Forth machine, the word next. Holon gives you control of every detail of your programs. You can understand every byte in the target, and remember: A fully understood program has no bugs!

If everything worked as intended, you should now have a good feeling for the browser and for the ways that you can handle and test your program. There are a couple more features to explore. The online manual (F1=Help) has all the information. 

 

How about a little action in the target? Let's assume that you have a LED connected to pin PA6 (portA, bit 6). 

Now write a program to have the LED emit the morse signal "SOS". You need words to turn the LED on, to turn the LED off, and to delay the execution.

Create a module for the test program

Go the last module, press Alt+F2=New, type the name of the module, say: "Testing", press <Enter>.

Create a group for the LED words

Go to the empty group window. Press F2=New, enter the name of the group, say: "LED driver".

Create a group for the action

Press Alt+F2=New, enter "The Action". 

Write the LED driver

Go back to the group LED driver, then go to the Word window. Press F2=New and define the word, which turns the LED on. You only want to change bit 6.

: LED-on       PORTA  c@  $40  or  PORTA c!   ;

Press F3=Load to exit the editor and load the word in one step. Then press F4=Run to test the word. The LED should light. There is not much that can go wrong. See the action of your word step by step in the debugger. Note what is written into PORTA. Check the hardware on your board.

Now create a word that turns the LED off. Define and test:

: LED-off       PORTA  c@  $BF and   PORTA c!   ;

This ends the "LED driver". 

Note: Although it is very simple, the example shows the essence of writing drivers for hardware in Forth. You build words that "move" the hardware, and test the words immediately. This hands-on action keeps you in the real world. You immediately learn if you know the hardware well enough. 

Write the action

Go to the group The Action and create the action words.

We create the delay with a simple loop:

: delay   ( n -- )    0 do loop  ;

: pulse      LED-on  delay  LED-off  ;         \ Loops n times

: short   5000 pulse  ;

: long   15000 pulse  ;

: pause  5000 0 do loop  ;

Test the words. If ok, define the morse signals "S" and "O".

: S    short pause short pause short pause  ;

: O    long pause long pause long pause  ;

And create the final word, your application.

: SOS      S O S  ;

Note

The LED driver is written in high-level Forth words, because this is the simple way most of the time. If execution speed is important, substitute the words with assembler code. Replace the previous definitions by:

Code LED-on      LDX # PORTA   BSET 0 ,x $40   NEXT
Code LED-off      LDX # PORTA   BCLR 0 ,x $40   NEXT

When you load the new words, Holon creates new code and exchanges the code in the target memory. The old code is replaced, and the new code is immediately active. You don't have to reload all the application words, the application words use the new code already. -- Try it. Look up the memory and check the code.

 

If you are familiar with Forth you will feel at home rapidly. You can import your existing Forth programs into Holon. Look up the details in chapter Edit, section Export/Import.   If you are new to Forth, Holon makes it easy to adapt. Study the program and the system modules. Try the Forth words. Every detail of the target system is clearly defined and commented. Nothing is hidden in HolonForth.