colorForthRay.info How_to:  with Ray St. Marie  

Considering the future: OLPC

Hello World!, and welcome back to colorForthRay.info. My name is Ray St. Marie, and I'm a colorCoder. I'm gathering information about colorForth to share with the world. It's a minor obsession. A hobby. 

I'm dealing with several illnesses, and in an effort to distract myself, I have re-dedicated my life to installing colorForth on the OneLaptopPerChild OLPC project. The machine uses OpenFirmware Forth BIOS and I believe that colorForth can not help but be the one operating system in the world capable of being totally open and at the same time the most quickly understandable by children.

If you believe that the OLPC will be the most distributed machine in the entire history of machines, if you believe that forth is capable of doing the entire job, just simpler and more understandable, if you've noticed that colorForth is remarkably easy to understand, if you realize that this is possibly a once in a life time chance to make computing easier for the entire world in one project...

Why don't you join me in my effort. We could educate enough children that the only thing stopping us from using operating systems that arn't either or both expensive and enourmous is that computer parts manufactures do not sell you the interface or manual with the part, making you dependant on things like Windows and Unix...

Okay, okay, putting the soap box away, but just this:

If you knew as much about the way the few parts in your machine work as you do about running Windows XP, you could be your own opertating system. You can know what every bit of software on your machine does. colorForth can do the job. E-mail me and help me proceed.  Raystm2@colorForthRay.info

Name Lossage: My own fault.

Yes, I have lost the name Colorforth.info to a registration robot and an untimely illness mixed with a move out of state. Hence the name change. It's a bonehead mistake and I'm sorry for any linking inconvenience.

Back at it: Going the miles that I promised you years ago.

I'm making changes to this site again. Updating and adding things you might like to know. The editor is next. Then a study of Karig commentary, filled in where info is sparce. All the while bouncing back and forth between versions, Intel bibles, listings, MASM help, NASM help, and websites from around the world that have defined the parts we are interested in.

Here is the link to Chuck Moore's colorForth.com web site. As we proceed , we will visit this site over and again to get the clues we need to reverse engineer the entire system.

Fastest known way to get a native running: If it doesn't work on your current machine, find a generic Pentium II, Cpu, monitor, keyboard, and floppy is all you need at first. Check the garage. The neighbors garage. Test images found on the internet. If the machine boots colorForth and you can afford it ...

colorForth is an invention of Chuck Moore. It is very easy for anyone to learn well. It is a very simple yet powerful version of the Forth programming language. colorForth is the latest incarnation. It uses color to say what a particular word would or could do. Forth is about words. Words that are easy for humans to use and understand. Each word is defined by, and may contain, other words or actual machine code. Rather then using functions provided by an outer operating system, such as Windows or any of the UNIX or Linux, colorForth native software uses Pentium chip operational codes to build a complete and powerful machine Forth system. colorForth is as high, or low-level a language as you desire. colorForth tends to obscure the boundaries between machine, operating system, programming language, application, and interface.

Oooh the colors:

YELLOW WHITE RED GREEN DARKYELLOW DARKGREEN MAGENTA CYAN

These colors are the current choices. Each one has a purpose. In the colorForth environment, you are either writing code in the provided editor, or running an application that has been previously written. When you are editing code, you can select from the above colors to control how the system acts on a word. YELLOW words are noteworthy. They are executed immediately after hitting the spacebar (spacebar executes the word accept in many cases) when you are running an application, and are also executed immediately when loading (compiling) a block of previously edited code, when YELLOW words are part of that code.

Introducing the Windows version by Roman Pavlyuk.

When colorForth boots, the first application that it starts is called logo.

logo displays black, blue, red, and green boxes, the words colorForth in red and green, and a yellow keyboard in the lower right corner that looks like:

This image is taken from a screen shot of colorForth For Windows, by Roman Pavlyuk, and can be found here: http://www.geocities.com/eleks_76/ This is a colorForth emulation that runs in Windows. This does not act exactly like a native. There are differences between all of the colorForth in existence, after all, programmers and the hardware that they use, are different.

See those yellow letters in the bottom right corner of the display? That is representative of the keys that interface colorForth. The letters aoeu are the letters of the left hand home row. But we are getting a little ahead of our selves.

Read what Chuck says:

There are things you should know before learning this! You should have read Chuck Moore's colorForth.com by now. There is a lot to know at Chuck's finely factored site, and the information is dense. You may not even be able to understand what Mr. Moore is talking about, at first. I didn't, to be sure. It is knowable. It is worth knowing. Take one piece at a time. We'll eventually cover everything there.

Uh, simple! Yeah, right!

So, how can I say that this system is simple, yet it's taking so much to describe? The environment that this system leaves you with after booting and starting properly is by far the simplest software envronment I've ever  used. With the kind help of many knowledgeable people, lots of referance, lost sleep... I have been able to piece together a BIG PICTURE of this remarkable programming language/operating system. If I were to give you a machine with colorForth running, and show you how the system works, it would not take you very long to learn everything there is to know. You don't really need to know much to use this system. It is very different then what a programmer is used to.

If you are using a native version, you should be able to put the image on a floppy disk. A disk is not necessary with the Windows version. We will cover moving binaries and  colorForth codes from media to machine.

The approach here will be to first discuss what happens just after boot. Then we discuss the editor, to edit and run some code. After we've used the system to get our bearings, we discuss the boot sequence, the interpreter, the compiler, the macros, the variables, the well... everything!

It may seem like a lot to learn, and maybe it is, but I say it is learnable. Certainly it is less to know then the complex set of puzzles needed to be navigated through while using a, currently considered modern, computer operating system. You can put an entire working system on a machine, and know what all of the software does. Assuming you have a running colorForth... and we'll cover that as well.

Hardware issues?!?

There are hardware issues. colorForth at Chuck's site does not run on all machines. It is not supposed to run on all machines, as colorForth is so close to the hardware. It must be customized to fit the machine.

We collect information about hardware and hardware issues, to help others. We report about the hardware and software combinations and configurations that have worked for others.

... back to assuming you have a running colorForth on your machine... I will be using colorForth For Windows on occasion, because it should be runable by the greatest number of people. Concepts will map easily between all the versions of colorForth, including natives. If you are using a unix/linux you have available to you Mark Slickers xcolorForth. We've located a version and have it here for you to download and try. Please note that Mark may not be maintaining that software any longer. Of all of the versions of colorForth that are available, my experiance with that one, and the BOCHS version that is at SourceForge, is currently limited. I'm catching up to these as fast as possible. Not to worry, much of the system will be the same and all of the differences will be related to hardware or virtual hardware in the case of BOCHS.  

Name Dropping: and other tidbits...

I have ported Terry Loveall's version of Chuck Moore's colorForth, to run on a Compaq/HP Pentium 4 that happened to come with all of the controllers ( things you typically need cards for like sound and display ) on the motherboard. That info will be available here. I tend to use the Windows version to test assumptions, then I try it on several colorForths including:

Those found at Tim Neitz's Archive http://www.dnd.utwente.nl/~tim/colorforth/ ( my favorite for several reasons ) In the mtcf folder there is the multi-tasking colorForth by Tim Neitz, using an adapted version of Peter Appelman's NASM compiled re-write of Chuck Moore's original ( which was written in source less programming techniques). In contrast, the Windows version is MASM compiled. As you can see, it may become necessary to know and, therefore, note the genealogy of each version. I will tend to list the developers chain when I know it. If you are a developer, and I have not recognized your work properly, (or have not met you yet) please do make me aware of such errors or omissions.

Sharing Code

At Tim's Archive, please notice that there is a folder called Raystm2. http://www.dnd.utwente.nl/~tim/colorforth/Raystm2/ In that folder there is a file called colorForth.css, and another called mv050314.html, and a third called mv050314.img. This is how we colorCoders tend to share our code. We also share our color coded blocks of programs in files named "AnAppropriateFileName.blk" ending in ".blk". The difference between .blk and .img is that a .img file includes a fully running native that you can put on a floppy and boot a machine. The .blk files are just the colorForth byte code portion of an image, and need to be properly added to a runable image. How to do so will be discussed.

The colorForth.css file is a cascading style sheet for rendering the colorForth code into html for web distribution. Using this style sheet and the program cf2html.exe, you can translate your colorForth byte code into html to share as I have done at Tim's archive. This particular image called mv050314.img is a copy of one of Tim's Multi-tasking colorForth ( aka MTCF) images and includes the Multipurpose blockViewer that I cobled together while studying Howerd Oakfords colorForth editor in his cfdos version 4, and Mark Slicker's editor found already included in Tim's multi-tasker file, left there when included with Petter Appelman's collection of code. This MultiViewer is the beginning to creating an editor for colorForth written in colorForth. If you click on the mv050314.html in a browser, you see the entire image of the mv050314.img file after it was run through the cf2html.exe program. The reason for mentioning all this is so to discuss the output of these html-er programs.

Hey, that's garbage on the page, right? I'm right... right?

Open this link in another window. http://www.dnd.utwente.nl/~tim/colorforth/Raystm2/mv050314.html.

The first thing we see is that the cf2html.exe has output the prompts and commands used to create the html page. Then we see in black bold print on white: "Block 0". The background color changes to black and we see in white:

 NOC YW ... ( this is where it appears to be garbage, but it's not.)

This block 0 is the first block of the image file. The output in this block 0 is the result of the cf2html.exe program trying to decode machine code that has not been stored as colorForth bytecode. The html-converter program only works on the bytecode portion of the image. Several of the first blocks of an "html-ized" colorForth source will appear as garbage for this reason. We usually just edit it out of the html page we will publish and leave the relevant blocks in the htmled page.

Subdivisions:

This division of colorForth code demonstrates the two portions of most colorForth versions. In versions that are closely related to Chuck Moore's original this division of kernel machine code and bytecode happens at block 18.

Forth stores words in dictionaries. In Tim's version of the multi-tasker, he needed more room for things, so he has moved block 18 to block 60 and used the new space from blocks 18 to 23 for his extension to the dictionaries. We will eventually see what is "under the hood" in these first blocks.

Scrolling down to Block 24 we begin to see the colorForth bytecode stored on the disk image as it was translated by cf2html.exe. We will see this code when we fire up the colorForth editor and look at Block 24, with the exception that the editor will also display the keyboard and the data stack as well. We will come back to the code on blocks 24, 26, and 28 later. We will also discuss the data and return stacks.

Scrolling to Block 30 we happen upon the RED word logo near the bottom of the block. 

logo show black screen 800 710 blue box 600 50 at 1024 620 red box 200 100 at 700 500 green box cf keyboard ;

Forth stores the words you define in dictionaries, as we have said. The macro dictionary is for defining machine code, Pentium ops, or other neat things that we will see ahead. The forth dictionary is for defining words, such as logo. RED words are the new definitions being entered into one of the two dictionaries. To change which dictionary the RED words go into, use either macro or forth.

RED words are defined by GREEN words (or other colored words as we will see). During a block load, when the interpreter reads a RED word, it compiles the GREEN words that define it. The GREEN words are either previously defined as RED words or provided to the system in the first 18 blocks as Pentium operations coded in assembled machine code.

In this definition of logo the word show is a word provided within the first 18 blocks area, and therefore you will not find its RED definition in the byte code area after block 18. There will be several words and services provided in the first 18 block section.

Notice that the definition just below logo, empty, contains the GREEN word logo.

empty empt logo ;

The word empt is defined in the first 18 blocks and empties the dictionaries, so you can start over with fresh ones. When empt finishes, then logo displays. The semi-colon ; ends a definition.

Scrolling on to block 60... (Note that you will see this block as block 18 in most every colorForth other than this one) As we scroll on to block 60 note the names, in WHITE, of the blocks that you pass.

Arriving at block 60 (this will be block 18 most of the time, remember!) we come to the block that is started first by the code stored in the first 18 blocks 0-17. During the boot process, the machine determines that the floppy disk contains a bootable image. The floppy is read into memory and the memory image is executed. After setting up the display and colorForth dictionaries, and other dependant code, this block 60 ( or 18 in many cases ) is loaded. This is how the front end starts and connects to the bytecoded portion. This block 60 or 18 or where ever it appears in the block chain, it could be anywhere so long as the front section is aimed to load it on boot, I will call the BLOB or the Block Loaded On Boot.

The BLOB block is the connection from the earlier machine coded support blocks, and the colorForth bytecoded applications blocks. Every colorForth needs a BLOB. Here is the BLOB from Tim's Multi-tasker with my MultiViewer image.

:Start code ( from Tim Neitz's MTCF with MV: block 60)

colorforth Jul31 Chuck Moore Public Domain 24 load 26 load 28 load 30 load

dump 32 load ;

icons 34 load ;

print 38 load ;

file 44 load ;

north 46 load ;

colors 56 load ;

mv 72 load ;

mtcf

l 170 load ; mark empty

;end code

WHITE words are comments and are ignored by the compiler during a load. In this block we first have the title of the application "colorforth" and the date ( with out year?) Jul31 and the original author, and the fact that Chuck has offered this up to the Public Domain for all to use freely.

Above we said that YELLOW words are executed immediately on loading of a block of code. The front 18 blocks load this BLOB then the code 24 load 26 load 28 load 30 load loads those blocks immediately, one block after another. The first three blocks (24 26 28) load extensions to the macro dictionaries. The last two (28 30) the forth dictionaries written in colorForth.

This block continues by adding the RED words:

dump icons print file north colors mv mtcf and l (Note: RED words also start a new line known as a carriage return. Words extending to the right margin wrap. That is the extent of the formating. We will come to font shortly.) Each of these RED words on block 60 are defined as a block number and a load command. This BLOB, when viewed in the editor, can serve as a menu of applications. These RED words are the names of and the block number of applications with those names. You could (don't just yet but good luck if you do and welcome back) type 60 edit and be looking at this very block in the editor.

Notice that mtcf "falls into" the definition for l. Typing either one will load block 170 and start Tim's multi-tasker. Typing any of the other RED words found on this block on the colorForth interpreter command line in YELLOW will load that application. In most cases, dump will require a number on the data stack. Example: 32 block dump

At the end of the BLOB block we have the YELLOW words: mark which sets the address point in the dictionary that an empt will empty the dictionaries to, and... empty which you now know will empt the dictionaries to the mark and call logo to display. All words defined before mark need to be bullet proof code to keep the system running. load commands are safe, but sometimes code they load are not.

Fortunately, colorForth is a Forth. It benefits from incremental tests of code during development. You can start with a running program, like logo, and test every change that you add to the program as you change it. While developing code, you can add the "block load word" definition to the BLOB “menu” (example dump which loads the block that contains the dump application) for your code after the mark so that you can empt the dictionaries and make changes. When your application is finished and won't crash, you can add the block load word above the mark.

Before you can competently use the editor, you need to know how it works. This is where most new users have problems. Well, at least, this is where I had my first problems with colorForth. Having been exposed to as many as 18 programming languages and their programming environments, I thought I knew what to expect with the colorForth editor. I was wrong and I was confused. I am glad that I remain persistent learning colorForth. It has been the most remarkable environment that I have coded with, thus far.

I did not appreciate what was happening here. In order for Chuck to create a language that would produce forth code at its simplest and most efficient with respect to the machine it was written on, Chuck endeavored to create an editor with unusual complexity. Chuck has stated that the simplicity of the language is at a compromise with the complexity of the system. Don’t let the idea of a complex editor scare you away from using colorForth. Because, while the editor is relatively complex, the usage of it is very simple.

The colorForth editor is a service provided in the first 18 block section. Before you can start the editor, you have to know how to use the interpreter command line, to interpret the commands that start the editor. In order to interpret commands, you need to know how to type them into the interpreter.

Interpreter keyboards

colorForth has a custom keyboard interface. This interface is very much like something you might find in a computer game. The keys can be reassigned very easily and you can customize your interface to fit your application. Recall the definition for logo:

logo show black screen 800 710 blue box 600 50 at 1024 620 red box 200 100 at 700 500 green box cf keyboard ;

logo is defined by the word show. show is provided in the kernel section, you will recall we stated earlier. show acts on the words that follow show. The words following show are the words that define the display. The last word in logo is keyboard. The keyboard word displays the alpha-keyboard in a show word.

Several keyboards that come with the editor are closely based on a Dvorak layout, while staying with-in the three-key-per finger idea. This I will call Chvorak, as it is slightly different to actual Dvorak. The Chvorak keyboard packs the letters you type into 32 bit words (with extensions if needed) in an encoding I will call Chuffman (combining Chuck with Huffman, which is the name of the type of encoding Chuck is using to pack the words, not exactly Huffman). Taking the Alpha-keyboard below as the example:

27 keys on your keyboard are relevant to colorForth. (One of the keys is not shown on the "clear" alpha-keyboard and it relates to the actual 'n' key on your keyboard.)

: Alpha-keyboard (thumb 1)

; ( most of the letters, more on the graphic-keyboard)

The fingers of the left hand are over aoeu, and the keys above and below them are for the left hand fingers. The fingers of the right hand are over the letters htns, and the keys above and below are for the fingers of the right hand. The right thumb also has 3 keys to access. The right thumb actuates the spacebar ( represented as 9 on the alpha-keyboard display, the little x character, to the right of the 9, swaps to graphic-keyboard is the right-alt button, and the actual 'n' key ( not shown on the alpha-keyboard when the word-pack-stack is clear).

The actual 'n' key will delete the word you are currently typing, when using the alpha-keyboard. If you type a letter, say e, you would see the thumb keys change and the letter e would appear to the right of the keyboard display.

: Alpha-keyboard with a letter typed thumbkeys changed (thumb 2)

; (Here, all 27 key options are shown along with the word-pack-stack displaying e and the data stack displaying 4. (We will discuss in detail the packing of words.) The thumb keys have changed to: X . x (the first X is the actual 'n' key and deletes the currently packing word, the dot . in the middle of the x's is the spacebar and executes the currently packing word, in this case starting the editor as e is the shortcut to do so, and the little multiply x is the way to swap the keys to the graphic-keyboard. The 4 you see to the left of the display is the value of the currently packing word as it appears on the data stack.

Use your right thumb and hit the actual n key represented by the big X to clear the e and you are back to the Alpha-keyboard "clear" to go on with this tutorial. Hitting e . ( dot is spacebar) starts the editor. Editor keyboards and color usage is described in detail below. To close the editor to continue, first hit the spacebar to get the Alpha-keyboard then type empty . to empt any running code and return to displaying logo.

Back to the Alpha-keyboard, lets see the rest of the available characters for names in the Graphic-keyboard by hitting the right-alt button represented by the little multiply x. (Windows colorForth users will want to use the ENTER button instead of right-alt, as Windows considers right-alt as active, right along with colorForth).

: Graphic-keyboard (thumb 1)

;This shows the thumb option ‘a’ in the graphic-keyboard “clear”, to swap back to the alpha-keyboard. Note what is on the graphic keyboard. First the colon, used in Forth languages as the word to define, now replaced by RED. The semicolon (ends a definition, you will recall) followed by the exclamation (!)(forth: “store” a value at address where value and address are provided on the data stack) and the AT (@)(forth: “fetch” a value from address where the address is provided on the data stack.) Notice z and j are here instead of the alpha-keyboard due to lack of room for them. They are followed by the period (.) or dot character. It can be used to clear one item off the top of the data stack and it can be used to display a number on the screen. The comma (,) is used to store to the current point in the dictionary pointed to by the forth word “here”. Then we have the four math operators (x), (/), and (+). The minus sign (-) here is one’s compliment and not minus. For the right hand, we have the graphic version of the numbers. Rather then being real numbers, these numbers are appropriate for use in the names of words or variables. These numerals are characters rather then literal numbers. The (?) is the last character.

Hit a character with this keyboard displayed, and you change the thumb keys. Now you have the option to clear or execute a word on the word-pack-stack, like in the alpha-keyboard, or you can swap back to the alpha-keyboard to continue composing your word on the word-pack-stack. Back to the alpha-keyboard by hitting the ‘a’ in the graphic-keyboard, we continue. ;

Hit the spacebar 9 and you get the...

: Number-keyboard

; (Notice the 0 at the left of the screen. This is the data stack display. System is based in decimal when this keyboard is showing; displays will display numbers in decimal on the data stack. Hit the right-alt (in Windows colorforth you want to use the ENTER key instead of the right-alt key as the right-alt key is still active in Windows) key and you get the...

: Hex-keyboard

; ( system is now in hexadecimal, stack will display numbers in hexadecimal.) The thing to know about the numbers keyboards is that now the actual ‘n’ key, when hit before a number, sets the number sign to negative. This is how you subtract. You add a negative number to another number.

(Hint: type the yellow words below using the keys on your keyboard that relate to the ones on the screen. After each yellow word, hit the spacebar to call the word. If you make an error hit the (actual) n key on the keyboard to clear the word from the display just left of the keys display.)

(By the way, none of the following works in the Windows version as it is not necessary, or may not even be possible in some cases, with the exceptioin of empty.)

A successfully booting native colorForth will end the boot process by displaying the colorForth logo logo. This means that the display works. A second test for a native colorForth is to try to boot. A save will copy the image to the floppy and return you to colorForth when it is done. Do not touch the keyboard while saveing, as you could interrupt the process. When the floppy light goes out, try warm booting the running image. Then try boot again. I like to do an empty, followed by a warm, before save, to ensure the image is not running some code that I’m working on, while trying to update the disk. This is the precise method for testing for a bootable, saveable, colorForth.

 If all that works, you are ready to edit colorForth code.

Using the provided Editor

colorForth boots, and logo displays. logo is what we can expect a basic colorForth program to look like. A basic colorForth program will use the display for output and the keyboard for input. The keyboard will also be represented in the display. The control of our program will come from the interaction with the keyboard, and it is convenient to change what keys do in specific situations. Therefore, it is handy to have a place on the screen for showing whats available on the keyboard at any given time. It is not necessary, just convenient. Earlier we mentioned that keyboards are easy to create on your own.

Turning on the editor we get the editor's keyboard:

e .  alpha-keyboard e spacebar executes:

There are a few more RED words defined here. There is a MAGENTAVARIABLE and it is set to jblk 236 (most likely 'jump to block" number variable). Two of the new words fetch from the variable and load or edit that block. qq most likely quickquick for quickloading that aplication block and qe for quick editing the same block. ee edits block 32 specifically. We recognise mark empty. What's different here is the keyboard display.

SCt  wrg*

        ludr

       -mc+

    X . i

This is in reality three keyboards in one.

Block Navigation

              *

       -     +

* swaps from code tippically kept on even block numbers to documentation usually found on odd  block numbers.

-  and + move thru the blocks by twos, even or odd depending on *.

Cursor Control  

        ludr

    X   i

l left u up ( left 8 * ) d down ( right 8 * ) r right.

The X cuts the word to the left of the cursor and stores it in a buffer. The i returns the items sent to the buffer in last in first out order, just like a stack. 

Color Editor Keyboards   

SCt  wrg

        mc

     .

Each of these letters on the editor keyboard take you to another keyboard. Each of those keyboards are the alpha-keyboard, graphic-keyboard, decimal-keyboard, hexidecimal-keyboard, in the color specifide by the color name of the key. SCt are all white comment type words. They are ignored by the compiler. The dot . spacebar returns out of the editor to the interpreter's alpha-keyboard without changing the display, so that you can load this current block and test your code incrementally.  

S STRING CAPS TEXT

C Caps Text

t text

w (an error should have been y for) yellow execute words.

r red definition words

g green previously defined to be compiled words

m magenta variables that are stored in source in the block where you create them, changing in source in real time, in plain view, making them very easy to debug. ( note that the block must be loaded for you to change the variable from its original value on creation of 0 ).

c cyan inlining machine coded macro words

Start slow.