STM8 eForth Alias Words

Alias Words

Alias Words is a unique feature of TG95451/STM8EF for creating dictionary entries for existing machine code in the binary which have no dictionary entry in the binary distribution. The end result is a smaller binary distribution which still contains the machine code of words defined in forth.asm, but the dictionary information for many words has been omitted. Alias Words are the mechanism by which dictionary entries for these machine code words are added at a later date as needed.

Alias Words allow the programmer to create dictionary entries like the following:

• linked previously unlinked Forth words in Flash into the dictionary
• provide words for code positions halfway into a colon definition (instead of factoring)
• keep words accessible after redefinition

Due to a core feature, Alias Words directly return the aliased code addresses. Therefore removing Alias definitions won't break the code using them.

The feature was proposed by @RigTig in issue #26 and #27:

• create minimal Forth core binaries by leaving out all non-essential parts of the dictionary
• extract addresses from a the forth.rst list file in the out folder
• create alias words from extracted addresses when, and compile them into RAM as needed
• compile new words using an alias word

Alias Words for unlinked STM8 eForth words are now automatically generated in the board build process. In the binary release they are in the out/<BOARD>/targetfolder. After linking that folder to ./target in the working directory, in e4thcom (and codeload.py) such Alias Words can be used easily, e.g.:

#require ULOCKF
#require LOCKF

: !F ( n a -- )
  \ write n to a in Flash memory
  ULOCKF ! LOCKF
;

The words ULOCKF and LOCKF were removed from the standard dictionary to safe memory space (in many cases NVM and RAM can be used instead). The example creates aliases to make a simple Flash store word.

For programmers using a windows terminal the following procedure using the example DIGIT will allow dictionary entries to be added for any words which have been left out of the dictionary.

NVM \ if you want to create the dictionary entry in flash for use in a later session
 : DIGIT [ $CC C, $88F1 , OVERT  
\ this is the file DIGIT in the target sub-directory for the board you are using
\ in forth.rst you see the $88F1 address where DIGIT is referenced when the binary using forth.asm was assembled 

words \ we now see Digit in the dictionary
 DIGIT IRET SAVEC RESET RAM <snip>

RAM \ since the dictionary entry for DIGIT was added to NVM, we must switch to RAM to make the dictionary entry permanent

cold \ do a cold restart or power cycle
STM8eForth 2N2.21 ok
 words
 DIGIT IRET SAVEC RESET RAM <snip> \ we see DIGIT is still there
 9 digit . 57 ok  \ and it works as expected

Defining Alias Words

A definer for Alias Words may look like this:

: ALIAS ( "name" xt -- ) \ M.Mahlow's solution
   : $CC C, , [compile] [ OVERT 
;

Using ALIAS creating alias words is akin to defining a constant:

\ create
' . ALIAS .. ok
56 .. 56 ok

: a 123 [ here ] . ; ok
ALIAS b ok
a 123 ok
23 b 23 ok

Alias Words Technical Background

Aliases are simply dictionary entries followed by a JMP instruction:

stm8eForth v2.2
: .. [ OVERT $CC C, ' . , ok
4 .. 4 ok

In this example an alias .. is created for . "print number" (in the standard use case the address comes from the STM8EF build script). The idiom : name [ OVERT creates an empty dictionary entry, and then leaves compile mode. The sequence $CC C, writes a JP (jump) STM8 opcode to code field of the new word, and ' . , completes the JP with the address of the word .. Typing 4 .. demonstrates that the word .. works as expected.

When the alias .. is used, the TG9541/STM8EF implementation of NAME> detects that the code field of .. starts with a the opcode JP ($CC), not any other instruction. NAME> then returns the value of the jump target not the address of the jump.

Running the code directly, of course, would do the same. The advantage is that aliases can be removed from the dictionary (e.g. defined in RAM), and compiled code in the Flash memory will continue to use the "aliased code".

The following code demonstrates that the alias feature is completely transparent to the application:

: ..test .. ; ok
: .test . ; ok
' ..test 10 dump
 117  CD 8A D2 81  1 10  5 2E 74 65 73 74 CD 8A D2 81  M_R____.testM_R_ ok
' .test 10 dump
 123  CD 8A D2 81  0  1  4 64 75 6D 70 74 74  0  0  0  M_R____dumptt___ ok

The code of the words ..test (with the alias ..), and .test (with the original .) is identical (CD 8A D2 81, CALL 8AD2 RET).

Other Use Cases for Alias Words

Another use case for Alias Words is safeguarding a word before overwriting it in the dictionary.

Consider this example (using e4thcom):

stm8eForth v2.2
#r ALIAS  Uploading: ./lib/ALIAS
\ STM8eForth : ALIAS                                                   MM-170929
\ ------------------------------------------------------------------------------
\ ...
nvm hex ok
: a 1 ; ok                                      
' a . 9336 ok                                   
' a ALIAS old-a ok                              
: a 2 ; reDef a ok                              
a old-a . . 1 2 ok
ram cold
stm8eForth v2.2
hex ' old-a . 9336 ok