pfth revisited -- TRY pfth072 Easy to install, easy use // Forth on the Propeller

LoopyByteloose · 2013-06-16 08:55

Hi all, I have revised this first page... again...
Please read entries #6 and #7 as there is one value that makes the .spin binary image 14 bytes over the limit. It is an easy fix, but necessary.

Install from the pfth072.zip file to a Propeller Demo Board, and have fun

See below for answers to these obvious questions.

Exactly how many of the .spin files are required for a basic configuration?
Is more than ONE configuration provided for? It looks like it presumes an SDcard might be present.
What is the right baud rate? I do get a serial interface, but with garbage characters.

It certainly would be nice to know all the configurations this version might entail if there is more than one, and how to do each.

Regards,
da Loop

Dave Hein · 2013-06-16 09:17

Loopy, the latest version that I posted was pfth072. You can get it from the pfth thread and I also attached it here. Look at the readme file for a description of how it works. There are two versions -- pfth.spin is a stand-alone version that doesn't require an SD card, and sdpfth.spin that can load Forth files from an SD card. The stand-alone version runs an ANS Forth chess program that I ported from another website. I think there may be a problem with that version, and there's another thread where I posted the ANS Forth chess code that works correctly.

The SD version is configured for the C3 board, but you can change the SD pin numbers at the beginning of the Spin for other boards. Forth files are loaded using the INCLUDE word.

Forth files can be include at bootup by using the FILE directive in the Spin source code. Look at the end of pfth.spin or sdpfth.spin to see how I did this. On bootup, the Forth interpreter reads console input from the files that are included in the Spin source. It then switches to normal console input after bootup is completed. During bootup the compiles Forth code overwrites the original Forth source code in memory, so the source code needs to be placed at the end of memory. That's why I have "long 0[1200] just before the FILE directives.

LoopyByteloose · 2013-06-16 09:22

Thanks. I just located the pfth072 in the thread referred to and see that there are indeed TWO version of pfth included = a stand alone, and an SDcard version.

Can you tell me about the console interface and Baud rate? Meanwhile I'll see if that is in the Readme.txt

Or have I just wrongly presumed that this provided for a serial console interface?

Dave Hein · 2013-06-16 09:28

The console interface uses pins 30 and 31, and runs at 115,200 baud.

LoopyByteloose · 2013-06-16 09:35

Using pfth.spin in BST, I am getting a compile error that there are 14 Longs too many. Not sure what to do.

It seems obvious that the binary is rejected. I end up with the previous image of PropForth booting.

LoopyByteloose · 2013-06-16 09:44

I got the pfth067.spin image loaded and a prompt. Not sure why I am getting the binary is 14 bytes too long for pfth072.spin.

I will try to reload 072, but I have enought to study and explore with 067 for now.

Cheers.

Dave Hein · 2013-06-16 09:50

In pfth.spin, change "long 0[1200]" to "long 0[1100]" toward the end of the file. pfth.spin is a modified version of sdpfth.spin with the SD code commented out. It includes the chess program, which is quite large, and I had forgotten to reduce the size of the padding area.

LoopyByteloose · 2013-06-16 09:59

Will do. I have lots to explore before getting back to you.

LoopyByteloose · 2013-06-16 11:07

I managed to easily find the value to change at near the end of the listing. And I changed the Readme.txt to include the baud rate in the first paragraph for my own reference.

Please take a look that the revision herein. Not big changes, but certainly more user friendly. I am considering going immediately to an SDcard setup to comprehend the overall system.

Dave Hein · 2013-06-16 17:56

Loopy, your edits look good. In the next version I should probably split the readme file up into two files. One file would describe how to use pfth and the other file would provide details on how pfth works.

LoopyByteloose · 2013-06-17 01:57

Hi Dave,
I am not sure that you have to split this file, though another file with deeper discussion might be very welcome.

I did a bit more editing for readability as attached herein. And I really like that it provides so much in a mere 3 or 4 pages.

Meanwhile, I am looking at things the ReadMe.txt indeed does not mention and reading the .spin file in conjunction with a document that provides an eForth overview. As you and I have discussed before eForth was created with a minimal approach to assember primatives and to maximize definitions in Forth. It asserts that only 30 assembler primative words are needed to launch Forth into standing on its own... and it supports ANSI Forth as well.

For now the observations that seem omited are as follow:

1. It seems that pfth relies on a Forth cell size of 32 bits... not really optimized to pack in a larger dictionary (Which Tachyon and PropForth get very fancy at doing).
2. The Data Stack and Return stack size appear to be 100 Long cells... rather deep for Forth on the Propeller
3. I don't know if pfth is case sensitive or not. But stating that would be useful

Am I correct in those fact listed in 1 and 2? If you do create a more in depth second .txt, you might consider these things as part of the introduction.

I have to go back into Starting Forth and review the utility and justification of DOES>.

I have yet to work out all the Branching and Looping behavior and wondering if you ever created a word that supports a time delay. So much of what Propeller users need to do is to control physical motion or the scrolling of the display, so a time delay becomes very important and useful. Traditional Forth could dump output to a file or printer if it came too fast, but that is not always available to the Propeller user.

Looping and Branching are the power and glory of microcontrollers. So I am very interested in their behaviors and uses.

LoopyByteloose · 2013-06-17 02:21

One more topic.... appropriate points of entry for new first-time learners of Forth.

Back in December, when I started with Forth it seemed that everyone just pointed to Leo Brodie's "Starting Forth". And while it is still a good entry, it presents a Forth in a context that is equally old and never considered the micro-controller of today.

BTW - I tend to feel that "Thinking Forth" can be a very big distraction to use of Forth on the Propeller... at least in the beginning. It tends to be more conceptual than practical and eForth -- presented in overview below -- has covered much of the optimization and factoring it talks about. One might spend a lot of time re-inventing optimized Forth by trying to depend too heavily on it.

So consider eForth as a study project in addition to "Starting Forth".

Charles Moore even recently seems to have also endorsed eForth as another point of entry for learning Forth... maybe more appropriate to people that have some ability to program in assembler for their preferred device. (And in my case, the preference is the Propeller.)

Enclosed is a document entitled 'eForth overview'. As it is available online in an .htm version, I converted it to PDF for reading off line. This has added quite a lot of white space and extended the original from about 40 pages to 84 pages. But the benefits are that it stays within the margins of the screen, and the typeface is larger and easier to read.

I suspect I will be using this a lot in exploring Forth and pfth.

It really is must read material for anyone that wants to hack Forth on the Propeller for either versatility or speed. Rather than sitting around trying to think of have to create a Forth word, it lists nearly everything you need or could want in already excellent Forth. And it demonstrates one of the better points of view on what is a minimal Forth kernel.

Dave Hein · 2013-06-17 05:25

Thanks for taking a look at pfth. It does use a cell size of 32 bits, which works well with the Prop's 32-bit architecture. However, I'll look into providing 16-bit support, and maybe a 16-bit mode. The compiled Forth code also uses 32 bits per execution token, which is quite wasteful. My plan was to reduce this to 16 bits that would provide a 2:1 code compaction.

pfth is case insensitive. I'll add that comment to the readme file. I'll also look into the stack usage. A larger stack allows for a greater calling depth and for recursion. The stack size should be easily adjustable by the programmer. I'll make sure the size is defined in the CON section.

I've gone back and looked at eForth again after you had pointed it out to me a few months ago. eForth follows the same philosophy as pfth, where a small core interpreter is defined and it is enhanced by adding higher level Forth words. Actually, almost any implementation of Forth on the Prop has to work this way since COG memory is very limited.

I also want to redo how I implement DOES>. I currently include a DOES> pointer with every word in the library. Not all words need the DOES> pointer, and I can save space by making that more efficient. My implementation of DOES> seems a bit different than the way it's normally done in Forth, so I want to revisit that, and clean it up if necessary.

LoopyByteloose · 2013-06-17 05:56

Hi again,

Well at least you have a DOES> and I have never quite comprehended the need or desire to get rid of it. I need to study it further.

At this point, I suppose I could roll back pfth to have eForth's plan of only 30 primative Forth words and the rest constructed from extensions of those, but it is quite obvious that it would run slow due to having to work the dictionary rather than evoke more efficent machine code.

In other words, the exercise is a bit academic.. and mainly serves as a proof of what eForth is on the Propeller.

Meanwhile, you have departed from the original code in C and switched to optimize via PASM.

I have a copy of pfth011, and pfth072 is a sea change in terms of how it is coded. .... nothing in C.

Back in December, I just wanted a standard version of Forth that was well supported by mainstream tutorials, such as 'And So Forth'.

Now I am thinking how much I enjoy Forth as a way to hack and learn the Propeller and depend on some Propeller specific features heavily. I see you have already created Forth lexicon for "Propeller Words' so that learners can explore more than just an ANSI Forth specification. This looks good and is comforting as pfth is not just an exercise in conformity to ANSI.

If anything, it is very modular and can swap lexicon additions to pursue learning with available resources or to exploit enhanced and exotic lexicons that are purpose driven.

I just have to figure out how I want to explore next.
It does seem I don't really require the SDcard installation if the Dictionary will hold the words I want to use. So I am figuring out my space limits.

There are huge advantages to the newcomer of a 32bit cell versus the 16bits cell. Having to bounce through 32bit, 16bit, and 8 bit sizes as a beginner is daunting. But eventually optimizing to 16 seems to be the optimal trade-off for storage.

So far it is quite fun, but I am having to get use to ANSI Forth all over again.

LoopyByteloose · 2013-06-17 10:20

From a learner's point of view, the @ and ! words are very central to snooping what you have done.... especially the @.

Used with a LOOP+ and formated output with CR, it can nicely do dumps of the active CogRam and HubRAM. That helps to confirm a lot of things. In many ways, the code is much cleaner in 32 bit cells in spite of the wasted space. I think I can actually learn much faster what is central to Forth.

I may try to write some words that do formal DUMPs. It seems to be appealing as a first project.

LoopyByteloose · 2013-06-19 09:43

I am really liking pfth just the way it is... not optimized for a larger Hub Ram spaces. The code is excellent for student work.

There are few quirks that annoy me, but every Forth has a few quirks. Words has not presented itself for easy reading. And I had to tweek my serial terminal software to include a lf so that the 'ok' was not over-writing other output.

I suppose that if I really need big lexicons, the SDcard version can do the job. But I presume that the dictionary searches would be slower.

I am struggling with other Propeller issues and may have to dump Ubuntu Linux 12.04LTS to continue using BST.

So exploring will go slower.

Dave Hein · 2013-06-19 11:47

WORDS is defined as follows:

: .name dup 0d + count type space ;
: ?newline dup >r 0d + c@ dup rot + 1 + dup 4e > if cr else swap then drop r> ;
: words 0 last @ begin dup while ?newline .name @ repeat 2drop ;

.name prints the name followed by a space based on a pointer to the beginning of the word. ?newline determines if the name will fit within a 78-character line, and issues a CR if not. words starts from last and prints names until it reaches a null link value. The link value is the first long of a dictionary entry for a word. The name is located 13 bytes into the word entry.

You could modify .name so that it prints extra blanks to line up the names in columns. You would need to handle names that are wider than a column width.

One thing I need to do is to document what a dictionary entry looks like. The code can be hard to follow without this information. The format of a dictionary entry is as follows:

   Offset     Content   Size
   ------     -------   ----
     0        Link      long
     4        Code Ptr  long
     8        DOES> Ptr long
    12        Flags     byte
    13        Name Len  byte
    14        Name      Len bytes
  14+Len      Pad       (2-Len) & 3 bytes
(Len+17)&(-4) Body      Variable

Dave Hein · 2013-06-19 11:51

You can also modify the definition for CR for terminals that don't do an automatic linefeed. It currently emits a carriage return, but you could change it to emit a linefeed also.

The SD version won't handle a larger dictionary since the dictionary is maintained in hub RAM. If fact, you will have less room available because the SD words take up dictionary room. Of course, with the SD version you can include a file, run it, and then forget it to free up space again. The MARKER word is useful for freeing up space.

I'm looking into reducing the size of dictionary entries and compiled words. I can save 6 bytes per dictionary entry by using words instead of longs for the link, code and does> pointers. I could save a couple of bytes per compiled word by not include a does> pointer. It's only needed for words that are constructed using CREATE, such as variables and constants.

I also use longs for the execution tokens that are compiled into a colon-word. That can be replaced with words also, which should save a lot of memory.

LoopyByteloose · 2013-06-20 01:58

Hi Dave,
I got WORDS to present properly, and also the 'ok' message. This was a startup configuration issue as the serial terminal indeed must add a LF to CR for everything to display right.

I did fool around with your wonderful Chess application and that just proves that the display is right as well. To make sure that the curious new users are not daunted and frustrated, I have added a bit more to your Readme.txt file again. I really hope this is the last revision I make as the shorter it is, the better.

Please see the attached.

At this point I have had a major crisis with my upgrading to Ubuntu 12.04LTS refusing to accept Brad's Spin Tool v 19.3. It seems I have to finally abandon Ubuntu and go to another distribution in Linux to have the ability to program Propellers in Linux. This is a big deal for me as I have enjoyed Ubuntu for quite some time now... I suspect I will use Magenta, a Linux of French origin. But Minit is supposed to be Propeller friendly as well.

Also, I feel I am ready to both use pfth to deploy my own projects. It was easy to get into and find where everything is. Plus, I have far less trouble reading the source code as it is very faithful to legacy Forth.

I will have to remove the chess.fth, chess1.fth, and chess2.fth lexicon to free up the Dictionary space for future personal projects... but that is not difficult to do.

I also need to spend as much time studying the init.fth file and I do studying the pfth.spin file. Together they make the system's core software.

I love it all and am having fun.

And yes.... I have been curious what a dictionary entry looked liked. I have been to busy to try to figure out your exact specifcation. But just knowing it is ANSI compliant makes knowing the details less important.

Dave Hein · 2013-06-20 08:36

Loopy, thanks for your update to the readme file. I'll incorporate it in the next version that I post. I decided to keep it as one file instead of splitting it into two files. I'll just add the more detailed information at the end, such as the dictionary entry format. I also noticed that I need to add the more recent kernel words that I implemented to the readme file.

LoopyByteloose · 2013-06-20 09:24

The dictionary entry format is certainly of use to those that want to reverse engineer your code. To the beginning Forth user, there is already enough in the Readme.txt file

Updating the kernel words listing in the ReadMe.txt is something I completely missed... can't see the forest from the trees when its your first time in the woods. What you did present was well-organized and helpful.

I used FORGET to pare down the WORDS report by eliminating all the CHESS lexicon which was loaded last, from that shorter report .... I can cut and paste a listing into Excel for personal notation and study.

By using WORDS, I am absolutely sure what is included. I've just learned that documentation is so hard to keep crisp and clean.

And when I reboot all of it comes back, and I still have Chess to play.

I guess what I am saying is that I am now beginning to use everything you provided. It feels good, not overly large or excessively ambitious.

I did start a comparison with eForth and was quite surprised by the results. eForth has strongly asserted that it takes at least 31 Forth primitives to create a basis to extend with colon definition words.

But pfth appears to not have any need for the eForth of the System words, so on the Propeller the true number of required Forth primitives might be actually less.

I look forward to whatever you do as I am sure improvements will be sound and sensible. But pfth072 has made an extremely good impression.

I am already pondering migrating some Forth projects to pfth that have worked well in PropForth. Not really much to do, but it will highlight the contrasts.

jazzed · 2013-06-20 09:52

Hi. Not sure why exactly (Easy in the title?), but I downloaded the lastest package and tried to compile pfth.spin.
Both propeller-tool and bstc with optimizations complained that "The object exceeded the program limit by 14 bytes" ....

LoopyByteloose · 2013-06-20 10:46

Hi,
Yes .. there is one parameter near the end of the .spin image that is wrong and how to correct is explained in the beginning of this thread.

Sorry for the glich. I was hoping Dave had gotten to corrrecting the .zip file.

See entries #6 and #7.

LoopyByteloose · 2013-06-20 11:14

@jazzed
I would hate to feel that you think I misrepresented pfth.

You will have to still unzip the pfth072.zip and swap this with the original as the .spin file will seek to load other .fth files that are referred to.

So here is the corrected .spin image. And sincere apologies.

jazzed · 2013-06-20 13:12

Forgive me for missing the posts that were mentioned. I read some things more lightly than others. Will try again when I get home.

LoopyByteloose · 2013-06-20 13:30

It is I that need the forgiveness, not you......

If you are using ithe pfth.spin and don't want all the Chess demonstration.. you have to comment out the chess files that fill up quite a bit of dictionary space.

On the other hand, if you really want to try the Chess, read the Chess.pfh file to get some idea of how to evoke it and how to input your moves.

LoopyByteloose · 2013-06-24 04:02

HI,
I am having a bit of a struggle with INA@, INA!, OUTA@, OUTA!, DIR@, and DIRA!

32 pins is a lot of 1s and 0s in binary to manage.

So I am pondering the good old days of PBasic i/o on a BasicStamp2.

It was easy to designate a PIN from 1-16 and I think that doing a PIN from 1-32 on the pfth would make a lot of new users feel more comfortable in the beginning.

From there, one could clone INPUT, OUTPUT, HIGH, and LOW. Easy and fun stuff, not high-brow geeking factoring of Forth words or heavy study of the Propeller Manual.

Start with a conversion of a decimal pin number to a binary 1 bit.

So if you in 3 PIN,

you get 00000000_0000000_00000000_00000100, which would read as a decimal *, but PIN #3 on the stack and ready for the other words to be created.
~~~~
: PIN dup 1 - 0 do lshift loop ;

That seems all wrong..... I have to figure out how to save the result... more stack manipulation.

And from there, the rest of the lexicon looks fairly easy to accomplish. If you have difficulty, the toggle.fth file is your 'go to' tutorial for simple pin i/o on pfth.

LoopyByteloose · 2013-06-24 08:43

Okay, my PIN idea is not really correct. Dave Hein sent me a PM with the following that does it all... and very simply.

: high 1 swap lshift outasetbit ;
: low 1 swap lshift outaclrbit ;
: input 1 swap lshift diraclrbit ;
: output 1 swap lshift dirasetbit ;

And so, that will help any BasicStamper to get into interpreted Forth on the Propeller.. without much ado. For some that are wary of SPIN and PASM, this is an easy entry point.

Use "Starting Forth" by Brodie or "And so Forth" to learn most of Forth, but apply it directly to i/o pins with what you are familar with from PBasic. We are just using the i/o terminiology as they are very similar... not the whole PBasic language.

And working from Dave's code, we have a solution for the word pin

: pin 1 swap lshift ;

You input a decimal pin number and the binary equivalent of that port goes to the top of the stack... ready to use.

Martin_H · 2013-06-24 09:49

There are three different FORTH dialects for the Propeller that seem to be under active development. Are there any sort of guidelines about suitability for one situation or another?

Tachyon's is supposed to be fast, but its lack of stack underflow protection scares a FORTH novice like me. Currently I used Gforth on the desktop and port my programs to PropForth. Sometimes the port is painless, other times it's more work. I read on the first page this FORTH adheres closely to the ANS, so is it more about portability?

Dave Hein · 2013-06-24 10:09

Yes, the main goal of pfth is to allow for portability. It should be able to run most programs that use the ANS Forth core words. pfth supports most of the extended core words. I think the only extended core words it doesn't support are CASE, OF, ENDOF, ENDCASE and .(. I'll add those in the next update.

LoopyByteloose · 2013-06-25 04:21

I happen to use gforth in Windows or Linux (as it is completely free and well documented) when I study Forth without a Propeller.

There are times that I just don't need to fool with a board and serial port.

So having it all be ANS Forth provides a simple and easy transfer of knowledge and skills. I have fumbled with too many particulars and excepts with other version of Forth on the Propeller. And they are harder to mentor another new users as you have to start with a long list of 'exceptions to the rule'.

CASE, OF, ENDOF, ENDCASE and .(. are not of critical importance to getting started.. but they may provide comfort to others that are used to using some sort of Case structure in other languages.

Why so?
The actual silicon just uses branches and jumps for everything. A Case structure can easily be constructed from the branches that pfth Forth already provides. One might even learn more about the internals of machine code on the Propeller.

pfth revisited -- TRY pfth072 Easy to install, easy use // Forth on the Propeller

Comments