Glossary

Cornerstone

A Cornerstone is a special Word which can be defined at any point. Calling this word will then erase all definitions added after it.

Cornerstone Word for 1 KB Flash pages

: cornerstone ( Name ) ( -- )
  <builds begin here $3FF and while 0 h, repeat
  does>   begin dup  $3FF and while 2+   repeat
  eraseflashfrom ;

Example

  1. Enter the “cornerstone” Word into Flash on your system as above
  2. Enter the following, the reply from Mecrisp-Stellaris is indented
words
  Address: 00003CE6 Link: 00004000 Flags: 0000FFFF Code: 00003D06 Name: --- Flash Dictionary ---

cornerstone corner-a
: testa 2 2 + . cr ;
words

  Address: 00003CE6 Link: 00004000 Flags: 0000FFFF Code: 00003D06 Name: --- Flash Dictionary ---
  Address: 00004000 Link: 0000405C Flags: 00000000 Code: 00004012 Name: cornerstone
  Address: 0000405C Link: 00004400 Flags: 00000000 Code: 0000406C Name: corner-a
  Address: 00004400 Link: FFFFFFFF Flags: 00000000 Code: 0000440C Name: testa

corner-a
  Erase block at  00004404  from Flash
  Mecrisp-Stellaris 2.4.5 for TM4C1294 by Matthias Koch

words
  Address: 00003CE6 Link: 00004000 Flags: 0000FFFF Code: 00003D06 Name: --- Flash Dictionary ---

Warning

Depending on the Flash implementation of the MCU, results may vary from this example.

Imm

An immediate value (or simply an immediate or imm) is a piece of data that is stored as part of the instruction itself instead of being in a memory location or a register. Immediate values are typically used in instructions that load a value or performs an arithmetic or a logical operation on a constant.

ARM data processing instructions have 12 bits of space for values in their instruction word. This is arranged as a four-bit rotate value and an eight-bit immediate value.

The 4-bit rotate value stored in bits 11-8 is multiplied by two giving a range of 0-30 in steps of two.

Using this scheme we can express immediate constants such as:

0x000000FF
0x00000FF0
0xFF000000
0xF000000F

But immediate constants such as:

0x000001FE
0xF000F000
0x55550000

…are not possible.

An assembler will convert big values to the rotated form. Impossible values will cause an error.

Some assemblers will use other tricks such as using MVN instead of MOV to form the bitwise complement of the required constant. For example the impossible instruction MOV r0,#0xFFFFFFFF could be assembled as MVN r0,#0. [davespace]

<builds does>

Or create does>

Michael Ham has called the word pair CREATE...DOES>, the “pearl of Forth”. CREATE is a component of the compiler, whose function is to make a new dictionary entry with a given name (the next name in the input stream) and nothing else. DOES> assigns a specific run-time action to a newly CREATEd word.

Folding

Constant folding is a well known technique in optimisation. It means that if an operator works on constants the result may be replaced by a constant that is calculated at compile time. In Forth we generalise this to folding. Folding refers to all words that can be replaced by simpler words in case they receive constant data on the stack. [vanderhorst]

“n-foldable” is mostly used on words that take n arguments as input. When the compiler encounters a n-foldable word, it looks back to see if the word is preceded by n literals (or constants), puts them on the stack, calls the word, and compiles the result as a literal.

Inlining

Inlining means replacing a Forth word with its constituents. This technique is very important in Forth, more so than in other languages, due to the small size of Forth words. Inlining is always a winner in speed, and mostly even also a winner with regard to space. Even more important is the fact that inlining allows folding to be applied across constituent words. This applies to high level and low level code alike. Inlining high level code is trivial. A further inlining stage replaces a high level definition that only calls code words, by a code definition which concatenates the code words. [vanderhorst]

Inlining means taking the code of a word, and putting it in place of a call to this word (saving the cost of a call, usually at the cost of memory)

INLINE is the Mecrisp-Stellaris binary inliner tool

Inlining Example

: somemore 42 + inline ;

see somemore
2000039C: 362A  adds r6 #2A
2000039E: 4770  bx lr
ok.

: inserthere somemore ;

see inserthere
200003C2: 362A  adds r6 #2A
200003C4: 4770  bx lr
ok.

The INLINE flag needs to be inserted into the definition which is to be inlined.

Warning

Inlining will fail if there are PC-relative BL opcodes in the definition to be inlined

Carefully check the definition(s) in question using the disassembler before specifying

INLINE flag or INLINE,

RA Kernel v/s Classic Kernel

RA Kernels feature automatic inlining but the Classic Kernel does not.

Mecrisp-Stellaris RA 2.4.7 with M0 core for STM32F051 by Matthias Koch

: somemore 42 + ;  ok.

see somemore
2000039C: 362A  adds r6 #2A
2000039E: 4770  bx lr
ok.

: inserthere somemore ;  ok.

see inserthere
200003C2: 362A  adds r6 #2A
200003C4: 4770  bx lr
 ok.

Mecrisp-Stellaris 2.4.7 with M0 core for STM32F051 by Matthias Koch

This is the Classic Kernel

: somemore 42 + ;  ok.

see somemore
20000340: B500  push { lr }
20000342: 362A  adds r6 #2A
20000344: BD00  pop { pc }
 ok

: inserthere somemore ;  ok.

see inserthere
2000035A: B500  push { lr }
2000035C: F7FF  bl  20000340  --> somemore
2000035E: FFF0
20000360: BD00  pop { pc }
 ok.


: somemore 42 + inline ; Redefine somemore.  ok.

see somemore
200003E4: 362A  adds r6 #2A
200003E6: 4770  bx lr

see inserthere
200003C2: 362A  adds r6 #2A
200003C4: 4770  bx lr

Smudge

Finishes a definition by flushing all flash buffers and inserts a link into the dictionary chain, making the new definition visible.

Vocabularies

July 2017, great news! Manfred Mahlow’s Final Release of VOCs extension for Mecrisp-Stellaris 2.3.6-hook-find (vocs-0.6.2-FR) has arrived for testing. See the new GPIO MODE Demo

Amforth

In amforth there is a word that can place newly defined words in wordlists automatically. e.g. a word called foo:bar is placed as bar in wordlist foo. It is like a sibling of a dot (colon)-recognizer that can detect the foo:bar notation and searches bar in foo (only). This word does not affect the definition wordlist or the search order, not even temporarily. [mtrute]