Previous - Up - Next

4.8   Object Declarations

The general form of an object declaration is "type name extras desc { ... }" or "type name extras desc;", where type is an object type such as bank, name is an identifier naming the object, and extras is optional special notation which depends on the object type. desc is an optional string constant giving a very short summary of the object. Ending the declaration with a semicolon is equivalent to ending with an empty pair of braces. The body (the section within the braces) may contain parameter declarations, methods, data fields, and object declarations.

For example, a register object may be declared as

    register r0 @ 0x0100 "general-purpose register 0";
where the "@ offset" notation is particular for the register object type; see below for details.

An object declaration with a desc section, on the form

    type name ... desc { ... }
is equivalent to defining the parameter desc, as in
    type name ... {
        parameter desc = desc;
In the following sections, we will leave out desc from the object declarations, since it is always optional. Another parameter, documentation (for which there is no short-hand), may also be defined for each object, and is used to give a more detailed description. See Section 5.1.1 for details.)

If two object declarations with the same name occur within the same containing object, and they specify the same object type, then the declarations are concatenated; e.g.,

    bank b {
        register r size 4 { ...body1... }
        register r @ 0x0100 { ...body2... }
is equivalent to
    bank b {
        register r size 4 @ 0x0100  {
However, it is an error if the object types should differ.

Some object types (register, group, attribute, and connect) may be used in arrays. The general form of an object array declaration is

    type name [size] extras { ... }
where size is the number of elements in the array. The size must be a compile time constant. For instance,
    register regs[16] size 2 {
        parameter offset = 0x0100 + 2 * $i;
or written more compactly
    register regs[16] size 2 @ 0x0100 + 2 * $i;
defines an array named regs of 16 registers (numbered from 0 to 15) of 2 bytes each, whose offsets start at 0x0100. There is also a special syntax "type name [variable in 0..max] ...", where max = size - 1. See Section 5.1.2 for details about arrays and index parameters.

The following sections give further details on declarations for object types that have special conventions.

4.8.1   Bank Declarations

The general form of a bank declaration is

    bank name { ... }
where name may be omitted. The elements (e.g., registers) of a bank that has no name belong to the namespace of the parent object, i.e., the device. There is at most one such anonymous bank object per device; multiple "bank { ... }" declarations are concatenated.

4.8.2   Register Declarations

The general form of a register declaration is

    register name size n @ d is (templates) { ... }

Each of the "size n", "@ d", and "is (templates)" sections is optional, but if present, they must be specified in the above order.

Templates are further described in Section 4.9.2.

4.8.3   Field Declarations

The general form of a field declaration is

    field name [highbit:lowbit] is (templates) { ... }
or simply
    field name [bit] ... { ... }
specifying a range of bits of the containing register, where the syntax [bit] is short for [bit:bit]. Both the "[...]" and the is (templates) sections are optional; in fact, the "[...]" syntax is merely a much more convenient way of defining the (required) field parameters lsb and msb (cf. Section 5.1.7).

For a range of two or more bits, the first (leftmost) number always indicates the most significant bit, regardless of the bit numbering scheme used in the file. This corresponds to how bit fields are usually visualized, with the most significant bit to the left.

The bits of a register are always numbered from zero to n - 1, where n is the width of the register. If the default little-endian bit numbering is used, the least significant bit has index zero, and the most significant bit has index n - 1. In this case, a 32-bit register with two fields corresponding to the high and low half-words may be declared as

    register HL size 4 ... {
        field H [31:16];
        field L [15:0];

If instead big-endian bit numbering is selected in the file, e.g., with a "bitorder be32;" declaration, the most significant bit has index zero, and the least significant bit has the highest index. In that case, the register above may be written as

    register HL size 4 ... {
        field H [0:15];
        field L [16:31];
This is useful when modeling a system where the documentation uses big-endian bit numbering, so it can be compared directly to the model.

Note that for a bit field declaration, only the "endianism" selected by a bitorder declaration in the file has any effect; the base width is always that of the containing register, so in a 16-bit register, big-endian bit 0 corresponds to little-endian bit 15, but in a 32-bit register, big-endian bit 0 corresponds to little-endian bit 31.

Previous - Up - Next