STM8 eForth Word List Extensions

Word List Extensions for STM8 eForth

In the talk "Forth WORDLISTs im Flash" at the Convention of the German Forth Society 2018, Manfred Mahlow presented a lightweight Word List feature for two embedded µC Forth systems, Mecrisp-Stellaris and STM8 eForth.

Word List Kernel Changes

From STM8 eForth release 2.2.21 on this feature is part of the regular distribution as a set of words in the lib folder. The most important of these words is CURRENT. With the help of the e4thcom (or codeload.py) dependency management feature, CURRENT patches and extends an existing STM8 eForth binary.

The Word List feature extends the dictionary with an WID (Word List Identifier) and a tag-bit in the length-encoding header byte in the following way:

tag-bit X=0 (untagged)
               |Link|i,c,X,Length|Name|Body|

tag-bit X=1 (tagged)
           |WID|Link|i,c,X,Length|Name|Body|

In eForth, the bit location of the tag-bit was originally vacant.

The CURRENT library file does the following:

• define variable CURRENT for holding the active WID ("0" for Wordlist FORTH)
• make $,n add a WID field and set the tag-bit of a new dictionary entry unless CURRENT equals 0
• redefine CONTEXT as an array
• extend find and WORDS with tag-bit evaluation
• make NAME? respect a search order of tagged and untagged words
• make UNIQUE? search only in compilation context

This extension adds about 320 bytes to the Flash size, and requires 6 bytes of RAM. Since applying CURRENT patches the existing binary, it's necessary to use PERSIST to protect the changes (otherwise a RESET would render the patched Forth kernel unusable).

Word List Flavors

The library word FORTH sets CONTEXT to 0, and thus provides a functionality well known from many other Forth systems.

The flavor of the Word List feature is the user's choice:

• WORDLIST WORDLIST ?RAM
• VOCABULARY ORDER .VOC NVM VOCABULARY DEFINITIONS FORTH
• VOC NVM VOC VP0 VP FORTH DEFINITIONs