IPL: The Icon Program Library Comment Domumentaion

# The Icon Program Libary

    from codegen

    from ststructs.mh

    Variable was directly stack allocated

    Array is contiguously allocated.

    Imported into nested scope

    Variable is referenced other than as

    argument to V or :

    With the -R option, the -G code generator keeps

    identifier bindings or variables in v. registers:

    displacement is v. register number

    r.h.s always evaluates to integer constant decl_const_val:

    RIC (Russell Intermediate Code) Op codes

    The first group has a single string argument

    Needs to do any cleanup (e.g. stack pops)

    necessitated by the preceding ARG instr that

    passed the activation record pointer.

    All labels that need to be known to the

    outside are marked in this way. All labels

    not beginning with an 'L' are intended to be

    unique, and thus may be made globally visible.

    following instruction

    function temporaries may be reserved on the

    stack at this point

    FP should be set to point to one below return

    address. AR should be set to first (and only)

    argument. Other locations are set explicitly.

    Locations (incl. AR) are implicitly saved

    during a procedure call.

    location of the data may be supplied by a

    preceding LBA instruction OBSOLETE

    Arguments may have been pushed.

    except that AR should neither be set, nor does

    the old value need to be saved.

    Arguments to BSF functions are passed

    individually using ARG, rather than passing a

    a single argument containing the activation

    record. If the name of the function does not

    start with Ffn, the generated function must be

    C callable. (Typically it will be, in any

    case.)

    declared by the immediately following DCL

    May be labelled with an LBA instruction.

    The argument is actually a string representing

    representing a floating point constant.

    Such data is read-only.

    constants.

    The remainder has up to 3 integer arguments. Unless otherwise

    specified, they refer to temporary locations (virtual

    registers). An offset is a signed integer value.

    An object is considered accessible only if there is an

    accessible pointer to its beginning.

    Pointers in any active temporary or on the stack are accessible

    args

    (i.e. virtual register)

    The following types are allowed:

    DCL_ADDR and DCL_INT, are assumed to be the

    same size. The distinction is only a hint

    to the machine code generator.

    DCL_FLOAT is unlikely to be used in the

    near future.

    In the following, size is a location:

    If applied to a predefined location, this

    constitutes a declaration that the value it

    contains is dead at this point.

    Duplicate UDC's for the same location may

    occasionally appear. All but the first can be

    safely ignored.

    ARG) into loc

    pointer data

    Both ALS and ALH are assumed to clear the

    allocated space. This is necessary only for

    garbage collection, and may frequently be

    eliminated by an optimizer

    Needs cleanup similar to CLL

    by immediately preceding LBA instruction

    The label must have been previously defined.

    equivalent to ALS 1; STI SP, 0, loc

    $define MVI 34 loc1 loc2 -- *loc2++ := *loc1++

    Add a (word) offset to a pointer value

    Unlike LDI and STI, offset here is a location

    style Russell routine. Nargs

    is an integer. The routine name is given by

    are supplied in reverse order by prior

    ARG instructions.

    object. Object should never contain pointer

    data.

    runtime checks, and may be discarded at

    suitably high levels of optimization.

    pointer to an object that may be on the

    heap. The called procedure does not

    preserve references to this object. Thus

    the ARG instruction may be disregarded for

    purposes of static ref. counting

    following procedure call (CLC, CLL, CLI)

    returns a new object of the indicated

    size. If size is != 0 the object may

    be deallocated by attaching it directly

    to the free list of the indicated size.

    If size is = 0, the size of the object

    is unknown, and the object could be

    statically allocated; rfree should be

    called to release it.

    Atom is either 0 or 1, and

    specifies whether the allocated object is

    atomic, and thus should be returned to the

    atomic object free list.

    the object pointed to by loc may be freed.

    This type of hint is inserted by the

    static reference counter for the benefit

    of the code generator.

    A negative size indicates the object is

    atomic; a positive size means composite,

    and a 0 size means unknown.

    Size is a constant, not a location.

    does not result in a saved continuation.

    Thus the reference counts of objects

    pointed to only by virtual registers

    is unchanged across the call.

    (This is always the case for CLC calls.)

    should store the size of loc if it's known

    that loc has exactly one reference, and 0

    otherwise. Loc contains a pointer to a

    composite object.

    preserved (passed through) as the function

    result.

    again. (The location itself may be reused.

    Thus UDC would be inappropriate.)

    to be updated inside a BSF function.

    Such a hint always precedes the first such

    update in a routine.

    as live up to this point. Such a hint is

    included whenever a location (other than

    GF and AR) could appear to be dead, but a

    derived pointer is not. A value in such a

    location needs to be retained, so as not

    to confuse the garbage collector.

    We do not generate such HINTs if it is

    known that the value in question is also

    stored in an accessible memory location.

    Similarly, we do not generate such a HINT

    if the derived pointer is only implicit

    in an LDI or STI instruction.

    declared by an EXT. All EXTs that do not

    refer to functions are preceded by such a

    hint. The second argument is a type

    specifier, as for the DCL instruction.

    be implemented as a stack allocation.

    This is used only if the comipler is not

    allowed to generate ALS instructions (-f

    or -F flag). Each allocation instruction

    preceded by a HINT ONS is eventually

    followed by a corresponding HINT ONS;

    HINT DEA sequence. All such pairs are

    properly nested. There are no branches

    into or our of such a pair.

    ARG instructions always occur in reverse order,

    with highest numbered argument first. The

    lowest numbered argument is numbered 1.

    Also used to pass the activation record pointer

    through CLL and CLI calls.

    MAY reserve space on the stack.

    Integer operations

    with an LBA

    Consecutive IDTs w/o intervening LBAs generate

    consecutive data.

    Data is read-only.

    Boolean operations

    indicated location.

    indicated location.

    The following instructions are assumed to work on

    both Booleans and bit vectors:

    The following applies only to Booleans:

    String operations

    preceding LBA instruction into loc

    Differs from LDI in that offset is a virtual

    register (location) and it is a BYTE rather than

    word displacement from index. Used to access

    individual characters in a string.

    Operations on single precision floating point numbers

    2 **(x-1) <= op1 < 2**x

    predefined locations

    explicitly saved and restored by

    Thus it can easily be assigned to a

    fixed register.

    An instruction using SK as

    destination or an STI SK,... is a

    noop

    capable of holding max size object

    result of operation. In-line code only

    Can't be legitimate operand to anything

    but LDN

    Dead after first reference.

    T1 and T2 are short term temporaries. They should be

    used only in fixed code sequences, not involving

    arbitrary embedded code. T1 is mapped to the same

    location as RL, and may thus conflict with RS in

    inline code sequences. T2 will never be specified as

    the result location for an inline code sequence.

    T1 is assumed to be predeclared. T2 is not treated

    specially by the final code generator.

    Since T1 and RL are the same, and will presumably be

    mapped to the location used for function results, we

    assume that T1 may be clobbered by ALA and ALH.

    Note: All general locations are expected to be saved and

    restored on procedure call.

    Activation record layout (all parts optional):

    0: static link

    1: 1st arg

    ...

    locals

    Function object layout:

    0: size

    1: ep

    2: ip

    Declarations for precedence levels

    no 0 in list so 1 added

    precedence levels for right associative operators */

    for grammar.y

    0x7fff

    moved from grammar.icn

    following from pass1/parser/rcs.h

    will have to be changed alltogether!

    The following are bit vectors defining which characters may legally */

    appear inside quoted identifiers. The msb of each word corresponds */

    to the character with smallest ascii code. */

    Note the machine and character set dependence of this whole scheme. */

    From scan.h

    * character classes

    */

    From precedence.h

    * Declarations for precedence levels

    */

    $define NLEVELS 14

    $define INFINITE (NLEVELS+1)

    for sigio

    from pass4

    Success indication returned by findsig

    Special signature field values