I would like to place ppforth in the Public Domain to make it freely available to anyone for any purpose.
Please skip ahead for new information if you are only interested in new release.
ppforth is a Forth system which run on Palm OS. It is based on eForth, and essentially is a sibling of lpforth. It can now metacompile itself inside a Palm pilot, and you can save your expanded system as you add on more words.
History --
Once I have lpforth running, to make it run on Palm OS becomes not so daunting. The basic procedure is the same. I first made a executable image in Win32For. The image was then uploaded to my Palm IIIc. Once it is running in Palm, I can then further expand it to have more functions in Palm itself. Forth is small and efficient, so it is not so bad as a developing environment in Palm. As I expanded it further, I included some utilities that I like in a Forth system. Among them are a primitive "see" utility, a source code debugger, the "words" with substring ability, and a "fsave" that can produce a new system. When it became a comfortable developing environment, I ported my ugly but intuitive (at least to me) metacompiler so it can regenerate itself inside Palm. Once this is done, I felt the system is complete in a sense it can sustain its own development -- not in the sense that it has all the common functions.
While the basic procedure is the same for writing lpforth and ppforth, a few things need to be done differently and worth a mention. First of all, the low level words need to be in 68000 assembly. When I did lpforth, I have the luxury to just use the same code I used in Windows version of Forth, since it is the same CPU. To make ppforth I had to learn a new assembly, which is not a fun part for me. I managed to learn just enough to make the ppforth engine run. It means there should be a lot of room for improvement in this department. For people who are good at 68000, you are greatly appreciated to give comments and suggestions.
Palm OS prevents application from writing to the memory area other than the heap. To make my porting easier, I decided to make ppforth move itself into heap area before it starts running. In this case, the dictionary structure can be kept the same without separating them into old words and new words. Variable words and value words need not to separated into different section just because the values may change at run time. Once this decision was made, the porting became straight forward. The move from regular area to heap is quite efficient. I don't feel it is slow to start the system at all.
When I did lpforth, I didn't do memory alignment at all. However, 68000 is very picky if you try to read or write from an odd address, which 80x86 family didn't complain at all. This problem costs me a lot of debugging time.
To do list --
There are still a lot to be done. I will do it when I feel it is fun
to do it. However, you are very welcome to add your improvement and
share
with others if you want. Below is a list of interesting things I can
think
of. If any of this interests you and you want to implement it and
share,
you are very welcome.
Remember that it is just a hobby project. I will not be responsible for any damage to your machine and any data loss due to the usage of ppforth. You should hotsync to backup your data before trying it. However, I have been using ppforth in my Palm IIIc for several months without any problem. Be aware and enjoying it.
Unzip the files into a directory. In Linux, I will go to the directory and do "pilot-xfer *". You can do equivalent with whatever the program you are using. In Windows, use "Install" in Palm Desktop and find the directory you unzip the file. Select all the files in the directory and do a hotsync.
After installation, you will see "ppforth", "metaforth", and "playchess" in the launcher. "ppforth" is the system. "metaforth" is a metacompiled bare bone Forth system. You can use it to build the full system if you didn't change "palmeta.f" file. "playchess" is a application for you to play Chinese Chess with another person. Included just to show you can use ppforth to program an application.
When you launch ppforth, it will show you greetings, and the familiar "ok". Here you go! You can use substring capable "words", "see" and "dump" to explore the system as well as define a new word. A fast version of "words" -- "qwords" is also included. If you define words in a file, you can use "include <file-name>" (or "fload" as I normally use) to load the program. I chose Doc file format as it is a smoother transition form lpforth. However, you will need a Doc file editor to write your program. I use "Qed", which is an shareware. If someone knows an good freeware Doc file editor, I will like to learn about it. An source code debugger is included. Use "debug <word>" to step through your word of interest.
To metacompile an new system, you will do "fload palmeta.f". ppforth will try to make a bare bone system. It will take several minutes. Be patient! After it is done and you can see "ok" when you type (or should I say write?) CR, you should use "main <new-system-name>" to save the new bare bone system. Launch the new metacompiled system, you can then use "fload kernel.f" to load the whole system. After several minutes, you can run "fsave <new-name>" to produce your shining new system. When you choose the name for your new system, pay attention to avoid having the first 4 characters to be the same as any of your existing programs. I use the first 4 characters as "Creator name".
playchess is just an application example. You need to know chinese chess rule to enjoy it. To use it, you tap on the piece you want to move first, then tap on the position you want to move to. Up and Down key can be used to move backward and forward of the played sequence.
That's about it. Hope you enjoy it and I can hear from you.
Jih-tung Pai
Updated 05/07/2001
Log 05/14/2001
A few people told me that ppforth is not working in some old Palm model, such as Palm Professional, Palm IIIe with 2 meg memory running Palm OS 3.0. I know it works in Palm IIIc, Palm Vx running Palm OS 3.5.
Release for ppforth-08102001
**Warning: Please hotsync backup before trying it. I will not be responsible for any damage to your machine and any data loss due to the usage of ppforth.
Follow the instruction in previous release note to install.
I decide to have a new release of ppforth. It is a continuous work to improve ppforth and there are still a lot can be done to improve it. However, I think it is time to let more people look at it and summit their comments. Judging from the experience of last release, I expect there will be plenty of constructive suggestions.
My hope is to have some people know ppforth well enough to make modifications in system level. So far, I believe I am the only one who is doing that. To this end, I encourage everyone who is interested in ppforth to summit their opinions, suggestions, as well as questions in the discussion forum (http://206.171.116.227/cgi-bin/ikonboard/ikonboard.cgi) so it will become a knowledge database. I don't have the motivation to write a complete documentation, but I am very willing to answer specific questions.
There are several things that I want to do and some are suggested by others. Here is what's new:
1. Include the view facility. It is a very important tool for me when I am exploring Win32For, and I think it will be also important for all the people who are interested in ppforth to quickly look up the definition of certain word. I usually use "qwords <substring>" to find the potential words that I may use in my application, then use " ll <word>" (or "view <word> if you want) to look them up to see which one is the one I need. In order for view words to work better, I have reformat all the source code so it will fit well to Palm screen. Although documentation for ppforth is not complete, the easy lookup to the source should help the situation a lot..
2. It is disappointing to find ppforth won't work in your Palm Pilot, isn't it? I found out I use a Palm OS system call (WinDrawChar) that is not compatible to some earlier versions of Palm OSes. I have fixed it, so it should work in Palm IIIx. Thank to David for offering me the ROM image to test. Please let me know which Palm works, and which one not.
3. I have included two Hello World examples that I modify from Steven Donahue' s tutorial for Quartus Forth to show how you can write a application and save it as a standalone program. At this stage, a simple Hello World program has to be saved with system image, hence it is 51k in size. It is kind of ridiculous. That's why the next thing I want to do is to port my target compiler in lpforth to ppforth. It will pack only the words that has been used into the final stand alone program. This will significantly reduce the size of final program. Although, a Hello World program is big, the size won't increase much while you add more complexity to your application. The 'chessview' program does much more stuffs and it is only 62k. The biggest ppforth can handle is 64k at the current stage. Keep in mind it is a decision I made to include as many tools as possible to make the development phase easiest possible. Once the target compiler is in place, all the unnecessary words will be gone. The example B has been changed a little bit to show ppforth can handle popup keyboard, although you won't be able to use it in interpret mode.
4. The system is now saved with resources (fload <name>), which will show nice icons in Palm launcher. The resource file ppforth use is 'ppforthrsrc'. You can change it to your liking. For your resource file that is associated with your application, you can refer to Hello World example. In this case, you should use 'rsave <name>' to save stand alone application.
5. I added a way to do Palm OS system call besides the original 'nsystrap'. Please look up 'strap' to see how it works and look at the source to see how it is used. The format is as following:
<#-of-16bit-word> <trap#> <return> strap <name>
<#-of-16bit-word> is the numbers of 16-bit words that will be cleared from stack after the call. 32-bit parameter should be counted as 2 16-bit words. For example, the absolute address is 32-bit, and should be count as 2.
<trap#> is the number to indicate which system call you want to make. I normally find the system call to use in 'Palm OS Companion' and 'Palm OS Reference' (downloadable from Palm inc. website), and then use 'coretraps.h' file (included) to look up the systrap number. This way, any system call can be added to ppforth.
<return> indicates what the output of the system call will be. Palm OS put the return value of a system all either in a0 or d0 register. Depending on the size of return value, it could be 32-bit as the register, or 16-bit, which will only occupy the lower 16 bits of the register. If the return is number, it normally uses d0. If it is a address, it uses a0 to store. Sometimes, I have to look at both values to see which one is intended return.
<name> is just the name you want to give to this system call in ppforth vocabulary. I try to use exactly the same name as indicated in Palm OS Reference book, unless it is too long that will occupy the space wider than the screen. You can choose whatever you want. It is your freedom.
6. There is a 'chessview' program I wrote with ppforth to follow some chinese chess games played by expert players. You can install and run it if you know chinese chess. The source codes are also available. If you want to compile it again by yourself, do 'fload chess.f' and 'rsave <name>' to the name you like. Just remember the first four characters have to be different from all the programs produced by ppforth. Twenty games are included in this release. I wrote a program in lpforth to convert games from a chinese chess database website. If you are interested in that, let me know.
To do:
1. I still don't have a good idea for the file words. It is not that straightforward to map records well with file.
2. I am hoping to work on target compiler next. Hope it will work out.
I don't think I can write a documentation complete enough. I think the best way is for you to find out what is not clear and ask questions in the discussion forum. This way, I know what is not clear to the people other than me. And remember the single most important feature of ppforth comparing to other Palm forth systems is that all the source codes are available. Look at them and change them to your liking. Share them will be even better.
Like always, please don't hesitate to give me your opinions, suggestions, and comments.
Jih-tung Pai
08/10/2001