Epson HX-20 - FORTH ROM

[GeoffB17]

The article attached. 4 pages?

Should be. Server is refusing. Took page 1 OK, page 2 is too big? Some pages are just over 2 Mb?

Geoff

 

[Dwight Elvey]

I'm curious as to which Forth was it build from? The original FIG and Forth79 had a few differences. Things like the value returned by logical operations and bit versus flag for some words.
Dwight

 

[GeoffB17]

Dwight,

The intro to the manual refers explicitly to FIG Forth, and makes no mention of F79.

Geoff

 

[Martin Hepperle]

In order to complete my mission, I adapted the raw code generated by DASMx to the syntax of the A09 assembler (https://github.com/Arakula/A09).
I had used this assembler in the past, as it was the only one I could find at the time, which supported the 6301 instruction set.
Besides replacing the data byte and word mnemonics I also went many times through the code until it assembled properly.

The result is a binary identical ROM image.

I also took care to replace all references to addresses inside the Forth ROM by labels (e.g. the LFA, NFA, CFA, PFA fields in the header of each word).
For better readability I also rewrite the last characters of each string which had its high bit set.

This should make it possible to move code around, e.g. when inserting or deleting words without breaking the system.
However it is very likely that there are still some places which have to be reworked.

In some places I have added comments with ???? to highlight areas where I am not sure what happens there.
This is also true for the block of trailing bytes, which seem to be unused, but may be used by indexed access.
I did not investigate this detail further, nor did I fill these bytes with zeroes to try what happens.

The assembler understands some constructs like if/else/endif which can be used to adapt the source to different HX-20 ROM constellations.

Unfortunately my Workhorse-HX-20 has developed a keyboard problem. Something with the contact sheets not contacting anymore on three keys. I have to revert to a different machine and/or try to repair this. Too bad, as I had already replaced all capacitors and of course the battery.
The broken keys are not on a single row or column, so it is not a wiring or connector problem.
Unfortunately it is not possible to replace individual switches. I guess that the coating on these thin membranes wears over time. And the membranes seem to be glued together, forming the thin black layer on top of the pcb.
Anyone has an extra keyboard (without key caps and springs)... in Europe?

Martin

 

[GeoffB17]

Martin,

Just for info - or in case this is useful?

My HX also has problems with certain keys, but here it relates to a few grouped together, and it's prob a connector problem. It's worse in cold weather, and tends to go away during warmer weather.

I merely programmed some of the PF keys to provide the same key function, and this works perfectly, if a little inconvenient. But this was more because I needed to have up to 3 key chars on each PF key - if you have 3 only problem keys then you could have one char per PF key which would be a lot easier.

While the keys were working, I created a little BAS prog with the PF key settings, and saved this, so I can more easily reload the definitions.

Just now, all keys are working again fine, and I hope it will stay this way until Oct?

Geoff

 

[GeoffB17]

An update to the above, in case anyone doesn't know.

There IS a 6301 assembler system written for the HX, written by Julian Wald (or Elizabeth ?) as per their other famous utilities for the HX. I think it may still be available directly, although their old web site is no longer active.

I would expect that a system (cross-assembler) based on a bigger system would be more convenient, although this does leave the problem of moving the generated system to the HX, but there are ways around this.

The version of the Assembler that I have (floppy disk and substantial manual) is the version for use with the TF-20 drive. There was also a version for use with the micro cassette. Not sure if the disk version would work the same with the 'virtual' floppy drive systems (as per the one that MH has produced).

Not sure to what extent this assembler would be an improvement over the one you're using now though?

I've just checked the archived web site for 'Classway', and I should add to the above:

The assembler is implemented as an extension to BASIC, it uses the virtual screen system and editor of BASIC, and you can use normal BASIC functions within the assembly. Compilation is to RAM, but the result can be saved using SAVEM. More interesting, the notes (back from 2002) suggest that there was also an EPROM version as well as the versions I mentioned above.

I think I still have a valid email address for the Walds somewhere (re Ptolemy ?) . I'll need to 'dig it out' from the dark depths of my archives?

Geoff

 

[Martin Hepperle]

The book "Using and programming the Epson HX-20 portable computer" by Balkan also lists an assembler written in BASIC. However the listing has a few minor misprints due to manual typesetting and one major error which can be corrected easily. Because it runs on the HX-20 the size of programs it can assemble is severly limited by memory constraints.

The A09 assembler, on the other hand, runs on any platform with a "C" compiler - I use it on my Windows 7 system.
While this is maybe less fun, it is more practlcal for me.

Martin

 

[Martin Hepperle]

I have attached another update of the reconstructed Forth ROM source file for the A09 assembler.
This version has been refined and some comments have been added.
Also the required changes for the various System/Basic ROM versions have been integrated and can be selected before assembling.

The archive also contains my notes on the modifications for the different system ROM versions (JAPAAN, EUROPE, V1.0, V1.1) and an updated Quick Reference Guide.

Things which I still do not understand, are marked with ????.
For example: why does the system copy part of itself into RAM (e.g. the "FORTH" word. figForth does this, but even there it is unclear to me, why.
This "FORTH" word contains a literal number $81A0 whose purpose I do not understand. The same magic number occurs in figForth 6800.

I also see a few dead regions of code or data bytes as well as some NOPs (figForth has some for patching, but patching a ROM is hard...)
Also, the restart code which copies part of the code to RAM jumps wildly around - seems to be grown over time. If it had been written from scratch, it would probably be much tidier.


Still TODO: change all relative jumps in BRANCHes to relative labels in the form LABEL-* to get rid of the hard coded numbers. I have done that in a few places, but not globally.

I*think* that I have removed all location dependency, but there seems to be something left which becomes visible when moving or inserting code.
I tried to insert a new word "SHIFT" into the dictionary (in the source, if/endif-ed with MH_MODS) but this did not work.
The system hangs after booting when I input the first word (e..g. a "1") and press ENTER.

Martin

 

[GeoffB17]

The FORTH word relates to the definition of the primary vocabulary. I don't think it does anything other than select this vocab as the default.

The activation of the FORTH ROM needs to add an item into the HX menu, i.e. the word FORTH and I assume a link to something so that selecting FORTH from the menu starts FORTH. I would assume that this will need something in the RAM area. But the address that you refer to would be in ROM (81A0)?

The manual refers to a section of RAM D00 - D12 as 'Booted entry for FORTH'.

Geoff

 

[Dwight Elvey]

Things copied in to RAM are things I mentioned before. These are called USER variables. They are things that are often actively modified. They include both values and some vectors.
Say for instance, one wants to send the text output to a different terminal. It may have a different backspace. Things like this are placed in these user variables.
Dwight

 

[Dwight Elvey]

To clarify a little. These are things that a different task may need to change. Also, a task may create local user variables These of course won't be saved in the ROM. Those that are in the ROM are those that are needed for a COLD reset. Things like HERE that is the beginning of the user dictionary. Say,you have written a piece of code that crashes the running Forth and you'd like to do a cold reset to clean up every thing. These values are loaded from the ROM. If your crash is believe to be a minor crash and you don't want to trash all of RAM ( done want to have to reload what was previously saved ) you can do a WARM start. This does minimal damage to what was in RAM.
The USER variables in ROM are the minimal variables the the Forth engines needs to run.
Normal VARIABLEs can be used by a program but if there are multiple task running on a particular Forth program, these may want to have a different table of USER variables. Having a specific block of USER variables makes it easy for the the task to switch these needed variables with a single pointer change yet switch back to the original interpreter's USER variables quickly. Say one task is writing bytes to a serial port, while the main interpreter is writing to the display. There may be a number of things that need to be modified for each's use, like buffer pointers and such. Being able to designate a separate table of these makes task switching very quick.
I suspect, as a beginner at Forth you'll mostly be interested in the USER variables that are loaded by Forth. When you start getting more advanced you may be using one of the typical multi tasking capabilities of Forth. Switching task quickly is one of the primary features of Forth. In the original implementations of Forth used to control an observatory, the same computer was used for multiple users. Some were controlling time programmed task while others may just be editing reports.
I hope this makes some sense.
The main USER variables usually exist as a single block of data so that they can be quickly loads as a block of memory.
Dwight

 

[Martin Hepperle]

Thank you for the clarifications. The HX-20 Forth uses USER variables, probably simply because it is built on figForth - there is no multitasking like a TASK word..

I also found out, what the "magic" number $81A0 in the FORTH vocabulary is: it is not ann address, but just a name field with the name of ' ' (blank, one character long: (1|$80) and (' '|$80) written as a word) - simple, but I could find no explanation until I looked into McCabe's book "Forth Fundamentals" where the structure of a figForth vocabulary is explained.

 

[GeoffB17]

Interesting that space (chr(32)) is defined as a word. I suppose sort of like the definitions 1, 2 and 3. Although they do something, by putting the respective value on the stack.

The 'space' word is not mentioned in the manual, as far as I can see.

'space' is an important separator in FORTH, so it's something that the input parser would be looking out for... Maybe it helps having it defined?

Did you note the address in the ROM where this definition is? Typing a space does NOT seem to put 32 on the stack. Interesting to see if it actually does something?

Geoff

 

[Martin Hepperle]

My understanding is that it is a "dummy name field" only for linkage purposes in the VOCABULARY structure.
The parser will never see it.

See the book by McCabe for some graphs with linkage of regular words and the Vocabularies.
In the assembler code you can find it easily by searching for the FORTH word (e.g. NFA_FORTH in my annotated assembler listing).

Martin

 

[Dwight Elvey]

The fact that there is no TASK work doesn't mean that one couldn't do multi-tasking. It just means that this Forth is the base to be expanded to one's desire.
Still, the USER variables contain a lot of things a person might want to look at or even modify. It usually has such things as where the input text buffer is located or where the current dictionary pointer is. The Forth interpreter is a task that Forth runs by default.
Forth is meant to be expanded into the desired application. In a philosophical sense, you don't really write programs in Forth, you expand Forth to be your application. You have full control ( for good or bad ) of every aspect of Forth, including things like modifying the compiler or adding special interpreters. This is unlike other languages like C where the programs you write are just an input stream and you have no real control of the compiler, other than some simple parameters.

The null word is just a convenient way to mark the end of a vocabulary search. Not all Forths do it this way.
Dwight

 

[Martin Hepperle]

Returning to the HX-20 specific Forth ROM.

In the meantime I refined "my" assembler code of the FORTH ROM and was finally able to add new words to the ROM.

While my first try to INSERT a new word failed (for reasons not yet understood by myself), I was successful to APPEND (or better: prepend) new words to the dictionary using some of the (what I believe is) unused space at the end of the ROM.

As an exercise for myself I added a word "SHIFT" and another one "FSHIFT" which both perform exactly the same: shift the bits in a word by +/- 0...15 bits left or right.

The difference between these two is (that was the execise), that the first one is implemented in assembler/machine language, while the second one is implemented as a chain of Forth words. The latter uses about 70% more space and is surely slower - how much, I still have to evaluate.

Thus, I think it should be possible to add a a handful of new words to the Forth ROM for the HX-20 - there are still about 100 bytes left.

Martin

 

[GeoffB17]

Martin,

I don't know if you're interested, but way back, while my TF-20 was still working (or at least linking) I created some FORTH words to allow the FORTH to do something with the floppy drive. I don't know if they will work with your TF emulator? Not sure if your version, or the other one, did NOT support the direct sector access (DSKO/DSKF).

Most of the 'action' is via calls to the ROM routines, my code is mainly re moving data re buffers etc so it's in the right place at the right time.

It did actually work though!

The process needs a special format disk, as it's using a dummy file to simulate the old fashioned FORTH disk system where Screens (1k) are mapped directly to sectors, but there is a 'file' there that can be accessed outside of FORTH. If my TF was still connecting, something like that would make good use of those extra bytes?

Geoff

 

[Dwight Elvey]

When linking in new words in ROM, look at the USER words CONTEXT and CURRENT. Some times it is easier to do a VLIST and patch in a word in the dictionary between the first word listed and the next one down. That is just a simple patch to the the links.
For such operations as SHIFT, you should see a large difference between the code word and the high level word! Most Forths have away to do low level code. Some even include a full assembler.

 

[LambdaMikel]

Forth is meant to be expanded into the desired application. In a philosophical sense, you don't really write programs in Forth, you expand Forth to be your application. You have full control ( for good or bad ) of every aspect of Forth, including things like modifying the compiler or adding special interpreters. This is unlike other languages like C where the programs you write are just an input stream and you have no real control of the compiler, other than some simple parameters.

In that regard, Forth is the other Lisp. I tried to bring that aspect across in some of my Forth videos. It's a fascinating language.

 

[Martin Hepperle]

The attached archive contains the reconstructed assembler source file with my comments and (optional) additional word as well as four image files. I have actually only used the EUROPEAN_V1.0 version, as I did not want to rip out the RAM extension board of my V1.1 system. S the other combinations may work - or not. But the source is there, so that you can adapt it as needed.

It could be interesting to add a few words to the ROM (as space permits). I am not sure whether accessing the floppy disk would be useful - currently I am using the internal microcassette with SAVE and LOAD. Slow, but working. But looking at your implementation would surely be interesting, at least from a learning perspective.
For me, access to one of the serial ports for general character I/O would be nice to have, but that is a personal preference.
Serial I/O is probably a core part of your implementation.

Martin