INTERNALS(3X)

NAME
internals - tile forth kernel internal data structures

SYNOPSIS
#include internals.f83

forth

DESCRIPTION
High level definitions of the internal data structures of the tile forth kernel. Defines the structure of vocabulary entries; the linkage structure, name string, mode field, interpretation code, and parameter field. Utility functions for displaying the current vocabulary search order, the current definitions vocabulary and the internal state of an entry. General definitions iterator for extraction of entries of specific code type.

  Numerical constants
Predefined constants for some of the most common values used for storage allocation and integer value initialization.

constant BITS/BYTE ( -- num)
    Number of bits per byte.

constant BITS/WORD ( -- num)
    Number of bits per word in stack data etc.

constant BYTES/WORD ( -- num)
    Number of bytes per word.

constant MAX_INT ( -- int)
    Maximum integer number in two's complement.

constant MIN_INT ( -- int)
    Minimum integer number in two's complement.

  Entry structure
The internal fields of an entry in a tile forth vocabulary. Defined as a structure with the traditional fields; link, name, mode, code, and parameter. Definition of the entry mode and interpretation code field.

struct.type ENTRY ( -- )
    Structure of vocabulary entries. Contains the fields; "+link", "+name", "+mode", "+code", and "+parameter".

ptr +link ( entry -- addr)
    Field access of link to predecessor entry in vocabulary list. The vocabulary chain is maintained as a linked list in definition order and may be manipulated with the "lists" extensions.

ptr +name ( entry -- addr)
    Field access of name string of an entry. The string is stored as a null terminated character sequence and may be manipulated using the "string" extensions.

long +mode ( entry -- addr)
    Field access of mode bit field of an entry. See also "ENTRY-MODES" for the definition of the bit fields.

long +code ( entry -- addr)
    Field access of code enumerative of an entry. Stored as a number, enum, or pointer to high level code. See also "ENTRY-CODES". If the code field contains a number larger than the exception entry code "EXCEPTION" it is interpreted as a pointer to a high level management block by the inner address interpreter.

long +parameter ( entry -- addr)
    Field access of parameter part of entry structure. Stored as a long. May contain a pointer to the body of the entry. This is the case for colon definitions and other entries with bodies larger than a "cell". The kernel word ">body" returns the contents of this field.

bitfield.type ENTRY-MODES ( -- )
    Bit field structure definition of the possible set of entry modes. The kernel uses four bits and allows applications to use the bits within the three most significant bytes (bit 8-31). Defines the modes "IMMEDIATE", "EXECUTION", "COMPILATION", and "PRIVATE" as bit fields. These may be manipulated with the "bitfields" extension.

bit IMMEDIATE ( -- pos width)
    Access of immediate bit field in the mode field of an entry. If the bit is set the entry is an "immediate" word. This bit is set by the kernel word "immediate".

bit EXECUTION ( -- pos width)
    Access of execution bit field in mode. If the bit is set the entry is not visible in compilation mode. This bit may be set by the kernel word "execution".

bit COMPILATION ( -- pos width)
    Access of compilation bit field in mode. If the bit is set the entry is not visible in execution mode. This bit may be set by the kernel word "compilation"

bit PRIVATE ( -- pos width)
    Access of private bit field in mode. If the bit is set the entry is only visible when the vocabulary in which it is defined is currently the definitions, "current", vocabulary.

bits RESERVED ( -- pos width)
    Access of reserved bit field in mode. These bits of the mode are reserved for the kernel. Bits 8-31 may be freely used by applications.

enum.type ENTRY-CODES ( -- )
    Predefined code types. Used by the kernel, inner interpreter, to determine management of primitives. Defines the enumerates; "CODE", "COLON", "VARIABLE", "CONSTANT", "VOCABULARY", "CREATE", "USER", "LOCAL", and "EXCEPTION". Codes larger than "EXCEPTION" are regarded as pointers to forth level management code, and are used to implement high level management compiled by the words following "does>".

enum CODE ( -- enum)
    Numeral for machine level code management. The parameter field of the entry is a pointer to a C procedure implementing the function. The inner interpreter will call the procedure.

enum COLON ( -- enum)
    Numeral for forth level code management. The parameter field of the entry is a pointer to the body of the definition. The inner interpreter will push the instruction pointer onto the return stack and use the parameter field as the new instruction pointer.

enum VARIABLE ( -- enum)
    Numeral to mark variable management of entry. The parameter field of the entry is used for the variable area. The address of the parameter field is pushed onto the data stack.

enum CONSTANT ( -- enum)
    Numeral to mark constant management of entry. The parameter field contains the constant value. The value is pushed onto the data stack.

enum VOCABULARY ( -- enum)
    Numeral to mark vocabulary management of entry. The parameter field contains a pointer to the latest defined entry in the vocabulary. The vocabulary is appended first to the vocabulary search set, "context".

enum CREATE ( -- enum)
    Numeral to mark create, symbol, management of entry. The parameter field contains a pointer to the data area for the entry. This pointer is pushed onto the parameter stack by the inner interpreter.

enum USER ( -- enum)
    Numeral to mark user management of entry. The parameter field contains the offset from the task instance pointer. The address of the user variable, calculated from the current running task pointer, "running", and the offset is pushed onto the parameter stack by the inner interpreter.

enum LOCAL ( -- enum)
    Numeral to mark local variable management of entry. The parameter field contains the offset within the current frame to the location of the argument or local variable. The value of the frame variable is pushed onto the parameter stack.

enum FORWARD ( -- enum)
    Numeral to mark forward management of entry. The parameter field contains initially "nil" and is replaced if the entry is redefined later. If the entry is used before defined an error message is given and execution is aborted.

enum FIELD ( -- enum)
    Numeral to mark field management of entry. The parameter field contains the field offset. The offset is added to the pointer on top of the parameter stack.

enum EXCEPTION ( -- enum)
    Numeral to mark exception variable management of entry. The parameter field contains a pointer to the entry.

  Utility functions
Functions for displaying the current vocabulary search path and internal state of entries. Also display function to retrieve the current set of vocabularies.

: .entry ( entry -- )
    Given a pointer to an entry prints all fields of the entry.

: .context ( -- )
    Similar to "words" but prints the current state of the vocabulary search set, "context".

: .current ( -- )
    Prints the name of the current definitions vocabulary.

: .entries ( code -- )
    Prints the name of the available entries of the given code type along the current definitions vocabulary, "current".

SEE ALSO
tile(1), forth(3X), string(3X), enumerates(3X), structures(3X), bitfields(3X), blocks(3X), lists(3X), sets(3X).

EXAMPLES
To print the internal fields of the entry forth, and access and verify its code type:

    #include internals.f83

A procedure to print out all variables in the "current" vocabulary:

    #include blocks.f83
    #include lists.f83

    blocks lists

    : .variables ( -- )
    	last
    	block[ ( entry -- )
    		dup +code @ VARIABLE =
    		if .name space else drop then
    	];
    	map-list
    ;

NOTE
The function list in each sub-section is sorted in logical order. The type and mode of the entries are indicated together with their parameter stack effect.

WARNING
These extensions are very implementation dependent and caution must be take as code written using these definitions is not directly portable to other forth environments.

COPYING
Copyright (C) 1990 Mikael R.K. Patel

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the original English.

AUTHOR
Mikael R.K. Patel
Computer Aided Design Laboratory (CADLAB)
Department of Computer and Information Science
Linkoping University
S-581 83 LINKOPING
SWEDEN
Email: mip@ida.liu.se