Rune - flesh out type support

[rune.git] / docs / ras.txt

                                Rune Assembler

(I) General

    RAS Assembles Rune Assembly into a rune object file.  Rune assembly
    consists of any number of lines of code in the following format:

    [label:]    directive/opcode        additional_spec

    Labels:

        Labels must start with a alpha character (a-z, A-Z, '@', '_', or '.'),
        and may contain a-z, A-Z, 0-9, '@', '_', or '.'.

        Labels are local if not exported via .library or .public.  Be sure
        to be in the correct section when importing/exporting symbols.

        Labels beginning with '.' are always local and may not be imported
        or exported.

    Comments:

        A RAS assembly file may contain '#' style comments (comment to
        end-of-line).  Any amount of whitespace may separate elements of the
        line (minimum one character of whitespace if no label is present).

    Expressions:

        RAS contains a simple expression parser which is able to collect
        symbols, generate relocation information, and perform arithmatic.
        RAS does not distinguish between signed and unsigned storage,
        calculates are performed with signed arithmatic and truncated to fit.

        binary operators: + - * / & | ^

        binary conditionals: < <= == > >= !=

        unary operators:  + - ! ~

        also: parenthesization (exp), and array specifications in certain
              contexts.

        types: int{8, 16, 32, 64, 128, 256, 512}, float{32, 64, 128},
               implied by context.  Strings are interpreted as a
               zero-terminated array of bytes.

               Alignments, element counts, and addresses are limited
               to 64-bits.

        specials: .ORG          - The current origin (as of the start of
                                  the line), will generate a relocation
                                  in a relative section.  Identical to using
                                  a label: defined on that same line.

                  .SECBEG       - Beginning of current section.
                                  generates relocation.

                  .SECBEG(sect) - Beginning of specified section.
                                  generates relocation.

                  .SECEND       - End of current section.
                                  generates relocation.

                  .SECEND(sect) - End of specified section.
                                  generates relocation.

                                  NOTE: Beginning/End of section represents
                                        the consolidated beginning and
                                        consolidated ending post-link.

    Constants:

        General C-style strtoq() parsing is accepted, so generally RAS
        will parse decimal unless you specify a '0' octal prefix or '0x'
        for hex.

        Floating point values are encoded using machine-independent
        RUNE FP formats (which are base-2) and will be converted to
        native formats by the translator.

    Use of smaller (or longer) extension words in instructions.

        Language emitters can place data and code in non-default sections
        to optimize the use of shorter extension words.  This means that
        a program can use e.g. 16-bit offsetes for data accesses even if
        the program defines more than 64KB of data, with proper use of
        .data16 sections.

    Endian

        All emitted Rune code should be endian-independent, meaning that
        proper data and structure layout typing should be used so the loader
        can translate the program between endian architectures.  Instructions
        nominally load and store data in the native endian of the target,
        which is not known until the program is actually run on that target.
        Rune contains instructions for properly converting between types
        and for loading and storing data with a particular endianess when
        such is needed.

    Register renaming, automatic spill, and automatic library %db caching.

        Code emitters can use generic register specifications, e.g. '%r23',
        or specific register specifications such as '%rb3'.  When generic
        specifications are used, RAS will automatically assign the proper
        register and will automatically spill and unspill registers if it
        runs out.  Simple code emitters do not have to try to optimize
        register use.  Register #1 for all register domains is reserved
        by RAS for the spill code if generic register specifications are
        used.

        RAS will automatically optimize and cache library bases for libraries
        specified in instructions.  If you generate an instruction in
        this form:

                move.l  %r23,LIBFUBAR:Counter

        then RAS will cache the library base pointer in a pointer register
        and generate something like:

                (cache LIBFUBAR's base pointer in %p1)
                move.l  %r23,LIBFUBAR:Counter(%p1)


        RAS will automatically generate vector specifications for library
        procedures defined with .lproc and convert LCALL specifications to
        the appropriate vector relocation.  For example:

                lcall   sys:read

        will be converted to something like:

                (cache LIBSYS's base pointer in %p1)
                lcall   *LIBSYS:read(%p1)

        These features can be used to access code and data from any library.

    Manual spill

        The code emitter may manually use the negative frame space for
        any variable storage for which the address of the storage is NOT
        taken.  The negative frame space is used by later passes for
        registerization optimizations.

        Code emitters may place registerizable elements in the negative
        frame space and must place unregisterizable elements in the positive
        frame space.  These elements must be accessed by the target procedure
        the same way (but using %ap-relative instead of %fp-relative
        accesses), and the argument structure must specify at least the
        negative frame space offsets (and should specify all positive frame
        space elements up to any var-args continuation).

        RAS will match up these accesses to guarantee consistency and can
        even handle caching a negative-frame-space argument in a register
        across an entire call/return sequence.

    Branch consolidation, extension selection

        RAS will consolidate branches to unconditional branches or jumps
        and remove dead code in code sections unless the 'noopt'
        (no-optimize) flag is specified.

        RAS will select the best-fit extension width for local branches,
        which can sometimes lead to having to take several passes on the
        file.

        RAS leaves major optimizations for later.

    Section layouts

        All sections are distinguished by library and name.  The actual
        section name winds up being "library:name".

        Elements making up each distinct section are combined together,
        ordered by {addr8, addr16, addr32, addr64}.  bss follows data within
        each addr-ordered subsection.  Note that each library has distinct
        section names so each library can control the addressing modes and
        extension widths used within it to access library-specific data and
        code.

        The final linker pass will collect distinct sections together in
        a final layout for the program, potentially compacting the code and
        data represented by multiple libraries into the same page.

        The linker will further order abs sections according to their origin.
        Most programs are fully relocatable, but pointer registers and storage
        contains absolute addresses so we can't really simulate a fork()
        without real process separation.

(II) Rune Assembly Pseudo-ops

    .library    lib

        Sets the default library name for section directives.  Can be
        overridden by individual section directives.

    .section [lib:]name, type[, flags][, align[, filler]]
    .code       [[lib:]name]    (section [name], code, addrXX)
    .code16     [[lib:]name]    (section [name], code, addr16)
    .code32     [[lib:]name]    (section [name], code, addr32)
    .code64     [[lib:]name]    (section [name], code, addr64)
    .bss        [[lib:]name]    (section [name], data, bss, reorderok, addrXX)
    .bss8       [[lib:]name]    (section [name], data, bss, reorderok, addr8)
    .bss16      [[lib:]name]    (section [name], data, bss, reorderok, addr16)
    .bss32      [[lib:]name]    (section [name], data, bss, reorderok, addr32)
    .bss64      [[lib:]name]    (section [name], data, bss, reorderok, addr64)
    .data       [[lib:]name]    (section [name], data, reorderok, addrXX)
    .data8      [[lib:]name]    (section [name], data, reorderok, addr8)
    .data16     [[lib:]name]    (section [name], data, reorderok, addr16)
    .data32     [[lib:]name]    (section [name], data, reorderok, addr32)
    .data64     [[lib:]name]    (section [name], data, ro, reorderok, addr64)
    .rodata     [[lib:]name]    (section [name], data, ro, reorderok, addrXX)
    .rodata8    [[lib:]name]    (section [name], data, ro, reorderok, addr8)
    .rodata16   [[lib:]name]    (section [name], data, ro, reorderok, addr16)
    .rodata32   [[lib:]name]    (section [name], data, ro, reorderok, addr32)
    .rodata64   [[lib:]name]    (section [name], data, ro, reorderok, addr64)

        Generate a section.  All elements of a file across any number of
        objects belonging to the same section will be collected together
        in the final output and by the linker when linking multiple objects
        together.

        name    - A quoted section name.  If not specified the name will
                  default to 'code', or 'data' depending on the directive
                  (NOTE: name must be specified for the .section directive).

        type    - code          indicates a code section
                  data          indicates a data section

        flags   - nogen         generate for offset info only, generates no
                                output.  The bss type is the same as
                                'data, nogen'.

                  bss           indicates a bss section.  Generates no output.

                  addr8         Accessible with 8-bit relative addressing.
                  addr16        Accessible with 16-bit relative addressing.
                  addr32        Accessible with 32-bit relative addressing.
                  addr64        Accessible with 64-bit relative addressing.

                  abs           indicates access to this section is via
                                absolute addressing.  By default access is
                                always via %db-relative or %pc-relative
                                addressing depending on whether it is a
                                data section or code section.

                  reorderok     Indicates that data layouts (e.g. directives
                                like .int32) can be reordered together to
                                reduce the number of structural relocations
                                required.

                  noreorder     Indicates that data layouts cannot be
                                reordered.

                  ro            read-only

                  strict        Strictly enforce the read-only flag, prevents
                                combining rw and ro sections together within
                                a single page.

        align   - A number indicating section alignment.  The section
                  will be positioned to the specified alignment at the
                  beginning and padded to the specified alignment at
                  the end.  Alignment must be a power of 2.

                  The largest alignment specified for the section or within
                  the section also becomes the section alignment.  Data
                  and code directives also automatically generate a starting
                  alignments.

        NOTE:   .code sections default to 2-byte alignment with a NOP
                instruction as auto filler and 8/16/32/64-bit addressing
                based on arguments to RAS (default is usually 32-bit
                addressing).

                .code16, .code32, and .code64 defines sections whos symbols
                will be accessed with 16, 32, or 64-bit addressing.

                .data sections default to 1-byte alignment with zero for
                the filler and 8/16/32/64-bit addressing based on arguments
                to RAS (default is usually 32-bit addressing).

                .data16, .data32, and .data64 defines sections whos symbols
                will be accessed with 16, 32, or 64-bit addressing.

                Assembly instructions must still specify absolute or relative
                addressing.  For example, SYMBOL(%pc) indicates pc-relative
                addressing, SYMBOL(%db) indicates db-relative addressing.

    .byte       [exp [, exp]*]  (same as .int8)
    .word       [exp [, exp]*]  (same as .int16)
    .long       [exp [, exp]*]  (same as .int32)
    .quad       [exp [, exp]*]  (same as .int64)
    .int*       [exp [, exp]*]
    .float*     [exp [, exp]*]

        Allocate zero or more data elements of the specified size.  These
        directives automatically perform a starting alignment of the native
        size (even with no data elements).

        The .int and .float directives must be suffixed with the number of
        bits (in powers of 2 >= 8), for example .int8, and may also be
        further suffixed with 'le' or 'be' for little-endian or big-endian.
        e.g. '.int8le'.

        If endian is not being forced, a structural relocation is associated
        with the data for endian-conversion purposes.

        If reordering is allowed,

    .space      bytes

        Allocate the specified number of bytes of unstructured space.

    .equ        exp

        Generate a value for a label.  Equates should nominally be specified
        in the appropriate section so the assembler knows how wide an
        extension word it should embed in the code utilizing the symbol
        if used for addressing or if relocations are present.

        When no relocations are present the most compact form possible will
        be used and the section is ignored.  This will generally be the case
        for immediate constants and pc-relative offsets.

    .libsym     lib

        Generate a library symbol for the specified library name.  Library
        names are typically prefixed with an '@LIB', e.g. @LIBSYS,
        distinguishing them from normal variable names.

    .align      align [, filler]

        Align the current origin to the specified value padding with the
        specified filler, and set the default filler for the current
        section.

        If no filler is specified, the current default filler for the
        section is used.

    .fill       element_size[, elements[, value]]
    .fill       structure[, elements][, { value, value, ... }]

        Fill an array[elements] of element_size entities with the value.
        If not specified, the current filler is used.  In structure mode
        the values making up the structure can be specified and the
        structure will be repeated <elements> times.  If <elements> is
        not specified, one copy is loaded.

        Also associates a structural relocation with the fill area.

    .zero       element_size[, elements]
    .zero       structure[, elements]

        Fill an array[elements] of element_size entities with the value 0.

        In structure mode a structural relocation is associated with the
        zerod storage for endian relocation purposes.

    .org        exp

        Set the origin, typically <exp> is a constant.  Only allowed
        in absolute sections.  Origins may not reverse-index within the
        section and the linker will fail if origin ranges for absolute
        sections overlap.  Not recommended.

    .public     [label [, label]*]
    .library    [label [, label]*]

        Specify the scope of labels that may be used in the assembly file.
        This can be done anywhere in the assembly file.  Be sure to specify
        this direction in the correct section so the correct address mode
        and/or extension word length is generated for instructions.

    .struct { [ [id:]element_size[:offset] [, [id:]element_size[:offset]]* ] }

        Associate a structure with a label.  The directive must be labeled.
        The structure may extend over several lines of assembly (successive
        lines should be indented but not repeat the directive, until '}').

        This creates structural relocation information in the object file
        for endian conversion purposes.

        Element sizes may be postfixed with '.le' or '.be' for little-endian
        and big-endian if you desire the data to be formatted in a particular
        way and not subject to automatic endian conversions by the
        translator.

        element_size is defined as the element size as a constant,
        or a structure label.  element_size can be postfixed with
        an array specification [ exp ] where exp is a constant.

    .prototype { struct_spec } ( struct_spec [...:offset] )

        Associate a prototype with a label.  The directive must be labeled
        and structural elements must define appropriate negative and
        positive frame-space offsets for elements.  A var-args procedure
        specifies an additional '...' and supplies the positive frame-space
        offset that begins the variable arguments section.

        This creates prototype relocation information in the object file
        for procedural argument and return value specifications for
        procoedures.  Prototype relocations are basically the same as
        a pair of structural relocations.

        Negative frame-space elements can be optimized by later passes to
        be passed and returned in machine registers.  Note that var-args
        elements are always positive-frame-space elements.

    .proc       prototype
    .lproc      vector, prototype
    .end

        Specify a procedure entry point (label on left).  If this is to be
        a library function, use .lproc to create a library function entry
        point with the specified vector number.  You may specify an optional
        structure for return values (void assumed if none) and MUST specify
        a structure for any arguments.  This will create a structural
        relocation for the procedure which allows later Rune passes to
        optimize calls and returns for register-passing

        You then lay the code out for the procedure, and finish-up with a
        .end directive or another .proc/.lproc directive.  Procedures cannot
        be nested.

        RAS optimizes generic register specifications, spills, negative
        frame space, and other procedural elements within the bounds of
        the procedure specification.

        RLD will generate the library's vector table

    .catch      label

        Generate a CATCH relocation with a target label.  This does not
        generate any actual code, but supplies information to the thread
        manager to aid in RAISE handling.  Any code after a .catch directive,
        up until the next .catch or the end of the procedure, belongs to this
        catch relocation.  If a RAISE is executed or chained up from a
        subroutine, code flow will jump to the target label.

        RAISEd exceptions can unwind recursively.  If an unhandled exception
        occurs within a call, or the exception is handled but the RAISE
        is chained upward, the return-from-procedure will chain to the
        active catch label at the return pc instead of returning normally.

        The huge advantage of .catch / RAISE in Rune is that all code handling
        for a RAISE is out-of-band, leaving critical code paths untouched
        including along procedural return paths.

        Normal instructions do NOT generate RAISEs.  Actual hard exceptions
        such as a divide by zero or a memory fault is NOT considered to be
        a RAISE.  The mechanism is meant for explicit exception handling
        and not for broken instructions.  In otherwords, language emitters
        can avoid having to generate unwind information for an exception
        that might happen at any point in the instruction stream or if the
        target procedure in a call is known to not generate any possible
        RAISEs.

        Language emitters generally use .catch relocations so they can
        generate code to unwind semantic levels and to test and execute
        exception handling code.  The Rune language uses this generously
        to generate unwinding code either for explicit RAISE instructions
        executed within a procedure or to unwind state if a procedure call
        issues a RAISE.

        Note that later passes may be able to optimize out large portions
        of any unwinding code you generate if it is determined to be
        unreachable.

(III) Rune Assembly Op-codes

    See insn.txt.  Generally speaking when laying out op-codes you must
    also specify absolute or relative-addressing by using the appropriate
    indirect register specification.  Constants can be expressions (including
    with parenthesis), and extra spaces in the additional-spec section are
    allowed.  RAS distinguishes between register and non-register
    parenthesized elements by looking for the '%' prefix on register names.