Dictionary¶

Example Dictionary Listing¶

Address: 0000DFD4 Link: 0000DFEC Flags: 00000040 Code: 0000DFE4 Name: pull-down
Address: 0000DFEC Link: 0000E024 Flags: 00001820 Code: 0000DFFC Name: green-on
Address: 0000E024 Link: 0000E05C Flags: 00001820 Code: 0000E034 Name: green-off

see green-on

0000DFFC: 2090  movs r0 #90
0000DFFE: 04C0  lsls r0 r0 #13
0000E000: 3080  adds r0 #80
0000E002: 0100  lsls r0 r0 #4
0000E004: 6983  ldr r3 [ r0 #18 ]
0000E006: 2280  movs r2 #80
0000E008: 0092  lsls r2 r2 #2
0000E00A: 4313  orrs r3 r2
0000E00C: 6183  str r3 [ r0 #18 ]
0000E00E: 4770  bx lr

Forth Definition Components¶

Address  Link  Flags  Code  Name

Word Header Fields¶

Name	Description
ADDRESS	Start of the definition block, always 16 Bytes before the CODE section
LINK	Address of the next definition, the one after this one
FLAGS	see “FLAG Codes” below
CODE	The address of the start of the executable code for this Word. Call this address to execute this Word.
NAME	The name of the definition (Word)

FLAG Codes¶

Taken from: mecrisp-stellaris-source/common/datastackandmacros.s

Flag	RA Only?	Description
0x0000		Visible, non-immediate
0x0008		Opcodable; 0: special case 1: plusminus 2: computational logic 3: DC unequal 4: push 5: memory Write,
0x0010		Immediate
0x0020		Inline - that means, it’s contents will be inlined until $4130, the ret opcode is found. On ARM, this is either $4770 bx lr or $BD00 pop {pc}.
0x0030		Immediate+Inline means: Immediate, Compile-Only
0x0080		Ramallot means that RAM is reserved and initialised by catchflashpointers for this definition on startup
0x0040		0-foldable, e.g. constants
0x0041		1-foldable, e.g. 1+
0x0042		2-foldable, e.g. swap, xor
0x0043		3-foldable
0x0044		4-foldable
0x0045		5-foldable
0x0046		6-foldable
0x0047		7-foldable
0x0100		buffers in compiletoflash mode
0x0200	Y	Allocator, this definition has individal optimisation code and a second entry point for the optimiser after the first bx lr or pop {pc} opcode.
0x0400	Y	Jump Eaters, this definition can handle cached jump instructions itself, for merging of comparisons with control structures.
0x0800	Y	Bxlr, is used once for ; and means that despite ; is immediate we can keep the direct bx lr return without the need to write the push {lr} opcode first for a later pop {pc}. Usually, the optimiser falls back to the push {lr} … pop {pc} sequence as soon as a call is compiled or something flagged as immediate is encountered.
0x1000	Y	Inlinecache, denotes that this definition carries an automatically generated inline cache table, which allows recompilation of this definition elsewhere with local optimisations in place.
0x2000	Y	Literator, never shows up in the dictionary, but appears in inline cache table to denote literals instead of code entry point with flag pairs.
0x4000	Y	User, is unused in all Mecrisp-Stellaris cores. This flag is free for the user, and the loadable vocabulary extension relies on it.
0xFFFF		Invisible

RA Core Register Usage¶

Register Purpose Notes

r0 Free scratch register Saved on interrupt entry by hardware r1 Free scratch register Saved on interrupt entry by hardware r2: Free scratch register Saved on interrupt entry by hardware r3: Free scratch register Saved on interrupt entry by hardware

r4: Inner loop count Needs Push and Pop when used otherwise r5: Inner loop limit Needs Push and Pop when used otherwise

r6=TOS: Top-Of-Stack Stack design is interrupt safe ) r7=PSP: Parameter Stack Pointer Stack design is interrupt safe )

r8: Unused r9: Unused r10: Unused r11: Unused r12: Unused Saved on interrupt entry by hardware

r13=SP: Return Stack Pointer r14=LR: Link Register r15=PC: Program Counter, always odd

Number Bases¶

prefix	Base	exactly ANS
%	binary	( - - )	Sets base to 2
#	decimal	( - - )	Sets base to 10
$	hex	( - - )	Sets base to 16
	base	( - - a-addr )	Base variable address

Data Types¶

Name	Bits	Description
Word	32	Native Mecrisp-Stellaris data length
Cell	32	Same as Word above
Half Word	16	Half Word length
Character	8	One Byte
Bit	1	Smallest

Key to Tables¶

Phrase	Description	Comment	Examples
n, n1,	single-length signed integer	-2147483648 to 2147483647	$80000000 . -2147483648, $7FFFFFFF . 2147483647
d, d1,	double-length signed integer	-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807	$FFFFFFFF $FFFFFFFF m* d. 1 ok. ( -1 * -1 = 1 )
u, u1,	single-length unsigned integer	0 to 4294967295	$FFFFFFFF u. 4294967295,
ud, ud1	unsigned double-length integer	0 to 18,446,744,065,119,617,025	$FFFFFFFF $FFFFFFFF um* ud. 18446744065119617025
c	character (byte)	8 bits, 0 to 255	$FF
h	halfword	16 bits, 0 to 65,535	$FFFF
x	cell		logic, memory operations, logging, bitmaps …
a-addr	cell address
h-addr	half word address
c-addr	character (byte) address
R:	return stack
flag	Binary 1 or 0
“name”	input stream token

Compiler Error Messages¶

Derived by grepping the source for “write”, “writeln” and “Fehler” (error).

Message	Source	Comments
Jump too far		Dreaded conditional jump range limitation. Workaround: create new Word with offending code.
Cannot write into core !	flash16bytesblockwrite.s
Cannot write into core !	flash.s
Create needs name !	compiler-flash.s	Often caused by a lone “;”
Flash full	compiler-flash.s	The chip Flash Memory is full.
is compile only	interpreter.s	Cannot be used interactively, must be inside a Definition (Word)
Jump too far	controlstructures.s	All jumps use Thumb 1 short opcodes. Solution; split your code into smaller Words
Not enough RAM	compiler-flash.s	Not enough RAM is available to complete the Word
not found.	interpreter.s	Name of word, constant, variable, etc cannot be found, usually a source typo
ok.	interpreter.s	All is good!
Ram full	compiler-flash.s	The chip RAM is full
Redefine	compiler-flash.s	A Word, constant, variable, etc has been defined more than once
Stack underflow	interpreter.s	The Data Stack is empty, you tried to pop data off it, but there is no data there
Stack not balanced.	compiler.s	The Return Stack is unbalanced, use of >R and R> was not equal
Stack overflow	interpreter.s	The Data Stack is full, default size is 64 elements, same as the Return Stack.
Structures don’t match	controlstructures.s	Example: a missing “then” from a “if else then” statement
Unhandled Interrupt !	interrupts-common.s	A Interrupt has been triggered, but no code is handling it. See Exceptions
Variables collide with dictionary	compiler-flash.s
Wrong address or data for writing flash !	flash.s for your MCU	See notes

Word Definitions¶

The complete word reference — every word with its stack comment and a short description, in one consistent format — is on the Words - the Mecrisp-Stellaris Dictionary page. That page is the single source for the word definitions, and it feeds the LSP.

The sections above (Dictionary layout, FLAG codes, register usage, number bases, data types, and compiler error messages) explain how the words work. For the words themselves, go to Words - the Mecrisp-Stellaris Dictionary.