Home Vocabulary: Building words


Target CPU characteristics

CHARBITS ( -- x ) Target's bits per character.
>CHARBITS ( x -- ) Sets the target's bits per character.
CELLBITS ( -- x ) Target's bits per cell.
>CELLBITS ( x -- ) Sets the target's bits per cell.
ADDRNIBBLES ( -- x ) Target's debugger address width in nibbles.
>ADDRNIBBLES ( x -- ) Sets the target's debugger address width in nibbles.
CPUTYPE ( -- x ) Returns the CPU type being compiled for.
CELL ( -- n ) Cell size in address units on the target.
CELLS ( n1 -- n2 ) Multiplies n1 by the target's cell address units.
CALIGNMENT ( -- n ) Alignment value for code space.
DALIGNMENT ( -- n ) Alignment value for data space.
ALIGNMENT ( -- n ) Gets the larger alignment value of code and data space.
BRANCHBYTES ( -- n ) Gets # of bytes of a control structure branch, set by the target-specific builder file.
MAXUINT ( -- u ) Maximum unsigned integer available on target.
SF ( <frac#> -- n ) Gets a signed fraction between -1.0 and +1.0 from the input stream and converts it to integer for the target's cell width. Example: on a 16-bit target, SF 0.5 maps to 16384.
UF ( <frac#> -- u ) Gets a signed fraction between 0 and +1.0 from the input stream and converts it to integer for the target's cell width. Example: on a 16-bit target, UF 0.5 maps to 32768.
UF1.0 ( -- d ) Returns double cell value: 2^cellsize.
ROM-BOUNDS ( addr-lo addr-hi -- ) Sets boundaries for ROM image. Boundaries include endpoints.
ROM-BOUNDS? ( -- addr-lo addr-hi ) Gets boundaries for ROM image.
CODE-BOUNDS ( addr-lo addr-hi -- ) Sets boundaries for code space. Boundaries include endpoints.
CODE-BOUNDS? ( -- addr-lo addr-hi ) Gets boundaries for code space.
DATA-BOUNDS ( addr-lo addr-hi -- ) Sets boundaries for data space. Boundaries include endpoints.
DATA-BOUNDS? ( -- addr-lo addr-hi ) Gets boundaries for data space.
TAR? ( -- ) Display comprehensive target information.

Token number manipulation

TOKEN# ( -- x ) Gets the current token number.
>TOKEN# ( x -- ) Store to TOKEN#. Same as {{ TO TOKEN# }}.
LOW-TOKENS ( -- ) Selects the low set of token values.
MAIN-TOKENS ( -- ) Selects the main set of token values.
TEMP-TOKENS ( -- ) Selects the temporary set of token values.
MAKEDEFINING ( <name> -- ) Places a new defining word in the TOKENIZER wordlist.

ROM image manipulation

HERE ( -- t-addr ) Points to the next free byte addressed by HERE. See RAM and ROM, which affect HERE.
ORG ( t-addr -- ) Sets new start address. Opposite of HERE.
STATIC ( -- ) Sets compiler and tester to ignore (bypass) the binding table.
DYNAMIC ( -- ) Sets compiler and tester to use the binding table.
HEX[ ( -- ) Compiles data into program space. Lays down incoming blank-delimited hex numbers until an unrecognizable number or end of line is encountered. Usage: hex[ 0AB 07F ... 0FC ]
BOUNDS>NA ( addr-hi addr-lo -- #cells addr )
  Converts address bounds to base address and cell count. Used by debugger attribute table.
CHECKSUM ( t-addr length -- checksum )
  Computes the checksum of a block of image data.

The following words support pin scrambling on the ROM. This allows you to reorder the address or data lines to simpilfy the PCB layout. It sounds radical, but think about it. If you're trying to keep the routing on one layer (keeping the other as ground plane), this can help. SCRAMBLE reorders the image data to compensate for reordered pins. You could get the same effect by building a custom EPROM programming socket.

SCRAM-A ( cpu-pin rom-pin -- ) Re-map an address bus pin.
SCRAM-D ( cpu-pin rom-pin -- ) Re-map a data bus pin.
SCRAM-INIT ( -- ) Clear the ROM scramble table.
.SCRAM ( -- ) Displays the ROM scramble table.
SCRAMBLE ( -- ) Scramble ROM image for byte-wide ROM
SCRAMBLE16 ( -- ) Scramble ROM image for 16-bit-wide ROM
SCRAMBLE32 ( -- ) Scramble ROM image for 32-bit-wide ROM

ROM image display and I/O

SEE ( <name> -- )
  Disassembles <name>. If <name> is tokenized code, the bytecode viewer is used. Otherwise, the disassembler is used. Hit ESC to quit early.
VIEW ( <name> -- )
  View/browse the source code of <name>.
INCLUDE-BINARY ( <filename> -- )
  Appends raw binary data to the ROM image.
HLOAD ( <filename> -- )
  Loads an Intel HEX file into the ROM image.
BSAVE ( <filename> -- )
  Saves the ROM image (up to HERE) in binary format.
HSAVE ( <filename> -- )
  Saves the ROM image (up to HERE) in Intel HEX format.
SSAVE ( <filename> -- )
  Saves the ROM image (up to HERE) in Motorola S format.
DSAVE ( <filename> -- )
  Saves the ROM image as an assembly listing using the disassembler.
TSAVE ( <filename> -- )
  Saves the token list as an FLOADable file.
.STATUS ( -- )
  Displays ROM image information.
$DIS ( t-addr -- )
  Starts disassembly at an arbitrary address. Disassembly will proceed until the address of a known word is reached or the ESC key is pressed.
$HLOAD ( $filename -- )
  Loads an Intel HEX file into the ROM image. $filename is a counted string.
~BOOT0 ( -- )
  Downloads the tokenized program in the image to the target board's primary boot area.
~BOOT1 ( -- )
  Downloads the tokenized program in the image to the target board's secondary boot area.
.FILES ( -- )
  Lists all filenames included in a build.
.VOCS ( -- )
  Lists all created vocabularies.

Assembler

ASMLABEL ( x <name> -- )
  Defines an assembler label whose value is x.
ASMLABEL? ( <name> -- x )
  Returns the value of an existing assembler label.
.ASMLABELS ( -- )
  Lists all assember labels. These are usually port labels and local code routines.
>@@0 ( x -- )
  Stores value to local assembler label @@0.
  The same goes for >@@1 to >@@9
ASMBYTE ( <name> -- )
  Defines an assembler label and allots one byte for it. Use HERE and ORG to set start addresses, etc.
ASMWORD ( <name> -- )
  Defines an assembler label and allots two bytes for it.
ASMLONG ( <name> -- )
  Defines an assembler label and allots four bytes for it.
ASMARRAY ( #bytes <name> -- )
  Defines an assembler label and allots #bytes bytes for it.