HxS Objects

This sections describes the fundamental HxS objects, the meaning of their properties.

The HxS language specifies several objects used to describe hardware / software interfaces. The following sections describe the meaning of the objects and their properties.

Namespace

A HxS file may contain one or more namespaces. It is mandatory to specify a namespace for HxS objects, so that they are uniquely identifiable. A namespace is created as follows.

hxs

namespace Eccelerators.HxS.Docs { }

Namespaces do not have any properties. They are just here to group HxS objects and make them uniquely identifiable. HxS objects may also be imported from other namespaces, see use keyword.

Interface

A hardware / software interface description starts always with an interface object in HxS. If no interface object exists in a HxS file, nothing will be generated. It is the top-most object describing a hardware / software interface. A HxS file can have none, one or multiple interface objects as needed. This is an example of a interface objects, just having a Name and Description property.

hxs

namespace Eccelerators.HxS.Docs
{
    interface ExampleInterface
    {
        Name = "Single-line hardware/software interface title";
        Description = "
            Multi-line description of the hardware/software interface
            that appears in the documentation.
        ";
    }
}

The interface object has the following properties. NOTE: All properties are optional. Default values will be used if not set explicitly.

Property Name Description Type Default Value
Name The name of the HW / SW interface. String Empty String
Description A description of the HW / SW interface. String Empty String
BusDescription A description of the HW / SW bus interface. String Empty String
BusType Determines the type of HW / SW bus interface.
  • Avalon
  • AXI4Lite
  • Wishbone (Default)
BusType BusType.Wishbone
AddressBusWidth The size in bits of the address bus. It has a minimum value of 2 bits and is calculated, if not explicitly set. Number 2
DataBusWidth The size in bits of the data bus. Number 32
Blocks A list of logical blocks that are provided by the HW / SW interface. List Empty List
Version Version information (e.g. v1, 0.0.1) String Empty String

Block

A block is used to logically separate functionality of the hardware / software interface. An interface is the top-most object and has a list of one or more blocks.

hxs

namespace Eccelerators.HxS.Docs
{
    interface ExampleInterface
    {
        Name = "Example Interface";
        Description = "This is an interface describing a single block.";
        Blocks = [ExampleBlock];
    }

    block ExampleBlock
    {
        Name = "Example Block";
        Description = "
            This is an example of a logical block. A logical block
            is a design tool to keep related functionality together
            and likewise to separate unrelated functionality.
        ";
    }
}

This is the list of properties of a block object. NOTE: All properties are optional. Default values will be used if not set explicitly.

Property Name Description Type Default Value
Name The name of the block. String Empty String
Description A description of the block. String Empty String
BaseAddress Base address of the block. Number 0x0
Alignment Address alignment of the block in bytes. Is calculated (i.e., Interface.DataBusWidth / 8), if not explicitly set. Number 4
Size Size of the block in bytes. Is calculated using the size of this block's registers, if not explicitly set. Number 0x0
Registers A list of register or delegate objects. List Empty List
Selects A list of selects used by the block. List Empty List
Version Version information (e.g. v1, 0.0.1) String Empty String

Register

The register object is used to describe registers. In order to be part of a hardware/software interface, the register object must be specified in the list of registers of a block.

hxs

namespace Eccelerators.HxS.Docs
{
    interface ExampleInterface
    {
        Name = "Example Interface";
        Description = "
            This is an interface describing a single block and a
            single register.
        ";
        Blocks = [ExampleBlock];
    }

    block ExampleBlock
    {
        Name = "Example Block";
        Description = "This a block describing a single register.";
        Registers = [ExampleRegister];
    }

    register ExampleRegister
    {
        Name = "Example Register";
        Description = "
            This is an example of a register using default values
            for missing properties making it a 8-Bit read-/writable
            register. It is notable that by default no bits are
            defined, meaning the register address can be read and
            written, but it will not have any effect.
        ";
        Width = 8;
    }
}

The register object has the following properties. NOTE: All properties are optional. Default values will be used if not set explicitly.

Property Name Description Type Default Value
Name The name of the register. String Empty String
Description A description of the register. String Empty String
Width Register width in Bits. Is calculated using the register's fields, if not specified. Number 0
Offset Offset relative to the registers block base address. Number 0x0
Address The sum of the register's block base address and offset. The address is calculated, if not specified. Number 0x0
Async Specifies whether the register is accessed asynchronously. Boolean False
WriteRegisterPulse Provides a signal for a register write. Boolean False
WriteTransparentPulse Provides a signal for a transparent write. Boolean False
ReadTransparentPulse Provides a signal for a transparent read. Boolean False
Bits A list of data, enum or reserved objects. List Empty List
Order Determines the order of bits; MSB or LSB. BitOrder BitOrder.MSB
AsyncClk Name of the asynchronuous clock signal. Only relevant if register is asynchronous. String "AsyncClk"
AsyncRst Name of the asynchronuous reset signal. Only relevant if register is asynchronous. String "AsyncRst"
ReadAckDelay Read delay of the Ack signal. Only relevant if register is asynchronous. Number 0
WriteAckDelay Write delay of the Ack signal. Only relevant if register is asynchronous. Number 0
ReadExternalAck Determines whether the register has an external acknowledge signal for read accesses. Boolean False
WriteExternalAck Determines whether the register has an external acknowledge signal for write accesses. Boolean False
Selects A list of selects used by the register. List Empty List
Version Version information (e.g. v1, 0.0.1) String Empty String

Delegate

The delegate object is used to describe areas that are delegated through the bus interface. In order to be part of a hardware / software interface, the delegate object must be specified in the list of registers of a block.

hxs

namespace Eccelerators.HxS.Docs
{
    interface ExampleInterface
    {
        Name = "Example Interface";
        Description = "This is an interface describing a single block.";
        Blocks = [ExampleBlock];
    }

    block ExampleBlock
    {
        Name = "Example Block";
        Description = "This a block describing a delegated address window.";
        Registers = [ExampleDelegate];
    }

    delegate ExampleDelegate
    {
        Name = "Example Delegate";
        Description = "
            The address window 0x0 - 0x100 is transparently routed
            through the bus. It is notable that the default value of
            offset is 0x0. The same applies to the base address of the
            block. Hence, the delegated address window starts at 0x0
            and is 0x100 Bytes wide.
        ";
        Size = 0x100;
    }
}

The delegate object has the following properties. NOTE: All properties are optional. Default values will be used if not set explicitly.

Property Name Description Type Default Value
Name The name of the delegate. String Empty String
Description A description of the delegate. String Empty String
Offset Offset relative to the registers block base address. Number 0x0
Address Address of the delegated area. Is automatically calculated using the sum of the delegate's block base address and offset, if not specified. Number 0x0
Size Size in Bytes of the delegated area. Number 0x0
Selects A list of selects used by the delegate. List Empty List
Version Version information (e.g. v1, 0.0.1) String Empty String

Data

A data object represents one or more bits of a register that are used to store arbitrary data.

hxs

namespace Eccelerators.HxS.Docs
{
    interface ExampleInterface
    {
        Name = "Example Interface";
        Description = "
            This is an interface describing a single block and a
            single register.
        ";
        Blocks = [ExampleBlock];
    }

    block ExampleBlock
    {
        Name = "Example Block";
        Description = "This a block describing a single register.";
        Registers = [ExampleRegister];
    }

    register ExampleRegister
    {
        Name = "Example Register";
        Description = "
            This is an example of a register that has a single
            data bit field. In this case the data bit field
            determines the register's size and makes it a
            readable and writable register.
        ";
        Bits = [ExampleDataBitField];
    }

    data ExampleDataBitField
    {
        Name = "Example Data Bit Field";
        Description = "A 8-Bit wide readable and writeable data bit field.";
        Behaviour = BitBehaviour.Register;
        Width = 8;
    }
}

The data object has the following properties. NOTE: All properties are optional. Default values will be used if not set explicitly.

Property Name Description Type Default Value
Name The name of the data field. String Empty String
Description A description of the data field. String Empty String
Behaviour
  • Register (Default)
  • Transparent
  • Loopback
  • Constant
  • ReadTransparent
  • WriteTransparent
  • WriteRegister
  • ReadTransparentWriteRegister
BitBehaviour BitBehaviour.Register
Order Determines the order of bits; MSB or LSB. If not set, uses the bit order of its corresponding register object. BitOrder Register.Order
Position Specifies the position of the data field in the register's Bits property. If no position is given, it is calculated using its predecessors. Number 0
Width Width in Bits Number 0
Values A list or dictionary of bit values.

The values specified in the list or dictionary override the value set by the bus reset.
List / Dictionary Empty List
Resets A list of reset objects used to reset a data object's bit field.

The first reset in the list determines the bus reset. It is used to specify the bit field's value after reset has been released.
A developer might refer to an own reset object or make use of an exising one. The following library objects are provided by the HxS Base Library:

  • BusReset.None - Bit field is not affected by bus reset
  • BusReset.Sync - Bit field is affected by synchronous bus reset
  • BusReset.Async - Bit field is affected by asynchronous bus reset
Any reset specified in addition to the bus reset creates a soft reset that has its own reset signal at the bus interface. As with the bus reset, a soft reset can be synchronous or asynchronous and set different reset values for the bit field.

If the list is empty, an asynchronous bus reset is used to set the value of the bit field to zero.

Note: A data object's Values property overrides the bus reset value.

List / Dictionary Empty List
Version Version information (e.g. v1, 0.0.1) String Empty String

Enum

The enum object represents a predefined set of bits of a register object.

hxs

namespace Eccelerators.HxS.Docs
{
    interface ExampleInterface
    {
        Name = "Example Interface";
        Description = "
            This is an interface describing a single block and a
            single register.
        ";
        Blocks = [ExampleBlock];
    }

    block ExampleBlock
    {
        Name = "Example Block";
        Description = "This is a block describing a single register.";
        Registers = [ExampleRegister];
    }

    register ExampleRegister
    {
        Name = "Example Register";
        Description = "
            This is an example of a register that has a single
            enum bit field. It is a readable and writeable
            register describing predefined bit values. The size
            of the register is determined by the size of the enum
            bit field.
        ";
        Bits = [ExampleEnumBitField];
    }

    enum ExampleEnumBitField
    {
        Name = "Example Enum Bit Field";
        Description = "
            A 1-Bit wide readable and writeable enum bit field
            predefining the values and signal names for on and
            off.
        ";
        Values = {
            0b0: "Off",
            0b1: "On"
        };
    }
}

The enum object has the following properties. NOTE: All properties are optional. Default values will be used if not set explicitly.

Property Name Description Type Default Value
Name The name of the enum field. String Empty String
Description A description of the enum field. String Empty String
Behaviour
  • Register (Default)
  • Transparent
  • Loopback
  • Constant
  • ReadTransparent
  • WriteTransparent
  • WriteRegister
  • ReadTransparentWriteRegister
BitBehaviour BitBehaviour.Register
Order Determines the order of bits; MSB or LSB. If not set, uses the bit order of its corresponding register object. BitOrder Register.Order
Position Specifies the position of the data field in the register's Bits property. If no position is given, it is calculated using its predecessors. Number 0
Width Width in Bits Number 0
Values A list or dictionary of bit values.

The first value in the list determines the default value, which is used if it is not overridden by a reset signal.
List / Dictionary Empty List
Resets A list of reset objects used to reset an enum object's bit field.

The first reset in the list determines the bus reset. It is used to specify the bit field's value after reset has been released.
A developer might refer to an own reset object or make use of an exising one. The following library objects are provided by the HxS Base Library:

  • BusReset.None - Bit field is not affected by bus reset
  • BusReset.Sync - Bit field is affected by synchronous bus reset
  • BusReset.Async - Bit field is affected by asynchronous bus reset
Any reset specified in addition to the bus reset creates a soft reset that has its own reset signal at the bus interface. As with the bus reset, a soft reset can be synchronous or asynchronous and set different reset values for the bit field.

If the list is empty, an asynchronous bus reset is used to set the value of the bit field to zero.

Note: A enum object's Values property overrides the bus reset value.

List / Dictionary Empty List
Version Version information (e.g. v1, 0.0.1) String Empty String

Reserved

The reserved object represents one or more reserved bits of a register.

hxs

namespace Eccelerators.HxS.Docs
{
    interface ExampleInterface
    {
        Name = "Example Interface";
        Description = "
            This is an interface describing a single block and a
            single register.
        ";
        Blocks = [ExampleBlock];
    }

    block ExampleBlock
    {
        Name = "Example Block";
        Description = "This is a block describing a single register.";
        Registers = [ExampleRegister];
    }

    register ExampleRegister
    {
        Name = "";
        Description = "
            This is an example of a register that has a single
            reserved bit field. In this case the reserved bit
            field determines the register's size and makes it a
            readable and writable register.
        ";
        Bits = [ExampleReservedBitField];
    }

    reserved ExampleReservedBitField
    {
        Name = "Example Reserved Bit Field";
        Description = "A 8-Bit wide readable and writeable reserved bit field.";
        Behaviour = BitBehaviour.Register;
        Width = 8;
    }
}

The reserved object has the following properties. NOTE: All properties are optional. Default values will be used if not set explicitly.

Property Name Description Type Default Value
Name The name of the reserved field. String Empty String
Description A description of the reserved field. String Empty String
Behaviour
  • Register (Default)
  • Transparent
  • Loopback
  • Constant
  • ReadTransparent
  • WriteTransparent
  • WriteRegister
  • ReadTransparentWriteRegister
BitBehaviour BitBehaviour.Register
Order Determines the order of bits; MSB or LSB. If not set, uses the bit order of its corresponding register object. BitOrder Register.Order
Position Specifies the position of the reserved field in the register's Bits property. If no position is given, it is calculated using its predecessors. Number 0
Width Width in Bits. Number 0
Resets A list of reset objects.

It's important to note that resets do not affect the behaviour of a reserved object.
List / Dictionary Empty List
Version Version information (e.g. v1, 0.0.1) String Empty String

Value

The value object is used to describe a value of an enum object more specifically.

hxs

namespace Eccelerators.HxS.Docs
{
    interface ExampleInterface
    {
        Name = "Example Interface";
        Description = "
            This is an interface describing a single block and a
            single register.
        ";
        Blocks = [ExampleBlock];
    }

    block ExampleBlock
    {
        Name = "Example Block";
        Description = "This is a block describing a single register.";
        Registers = [ExampleRegister];
    }

    register ExampleRegister
    {
        Name = "Example Register";
        Description = "
            This is an example of a register that has a single
            enum bit field. It is a readable and writeable
            register describing predefined bit values. The size
            of the register is determined by the size of the enum
            bit field.
        ";
        Bits = [ExampleEnumBitField];
    }

    enum ExampleEnumBitField
    {
        Name = "Example Enum Bit Field";
        Description = "
            A 1-Bit wide readable and writeable enum bit field
            predefining the values and signal names for on and
            off. The values for on and off are reference to a
            value object that enables more precise description
            of that value.
        ";
        Values = {
            0b0: ExampleValueOff,
            0b1: ExampleValueOn
        };
    }

    value ExampleValueOff
    {
        Name = "Example Value Off";
        Description = "This value describes signal off.";
        Value = 0b0;
    }

    value ExampleValueOn
    {
        Name = "Example Value On";
        Description = "This value describes signal on.";
        Value = 0b1;
    }
}

The value object has the following properties. NOTE: All properties are optional. Default values will be used if not set explicitly.

Property Name Description Type Default Value
Name The name of the value. String Empty String
Description A description of the value. String Empty String
Value A Bit value. BitValue 0b0
Width Width in Bits. Number 0
Behaviour
  • Read
  • Write
  • ReadWrite
ValueBehaviour ValueBehaviour.ReadWrite
Version Version information (e.g. v1, 0.0.1) String Empty String

Reset

The reset object is used to describe a reset that is used by either an enum, data or reserved object.

hxs

namespace Eccelerators.HxS.Docs
{
    interface ExampleInterface
    {
        Name = "Example Interface";
        Description = "
            This is an interface describing a single block and a
            single register.
        ";
        Blocks = [ExampleBlock];
    }

    block ExampleBlock
    {
        Name = "Example Block";
        Description = "This is a block describing a single register.";
        Registers = [ExampleRegister];
    }

    register ExampleRegister
    {
        Name = "Example Register";
        Description = "
            This is an example of a register that has two bit
            fields; an enum and data bit field. It is a readable
            and writeable register. The size of the register is
            determined by the sum of the size of both bit fields.
        ";
        Bits = [
            ExampleDataBitField,
            ExampleEnumBitField
        ];
    }

    data ExampleDataBitField
    {
        Name = "Example Data Bit Field";
        Description = "An data bit field having a single reset signal.";
        Width = 1;
        Resets = [ExampleReset];
    }

    enum ExampleEnumBitField
    {
        Name = "Example Enum Bit Field";
        Description = "An enum bit field having a single reset signal.";
        Values = {
            0b0: "Off",
            0b1: "On"
        };
        Resets = [ExampleReset];
    }

    reset ExampleReset
    {
        Name = "Example Reset";
        Description = "
            This reset object determines the value of a
            corresponding field if the reset is asserted.
        ";
        Value = 0b0;
    }
}

The reset object has the following properties. NOTE: All properties are optional. Default values will be used if not set explicitly.

Property Name Description Type Default Value
Name The name of the reset. String Empty String
Description A description of the reset. String Empty String
Async Determines whether its an asynchronous reset. Boolean True
Value Value to set for this reset. ResetValue 0b0
Width Width in Bits. Number 0
Behaviour
  • Read
  • Write
  • ReadWrite
ResetBehaviour ResetBehaviour.ReadWrite
Version Version information (e.g. v1, 0.0.1) String Empty String

Select

The select object can be used by a register to specify how a register should be selected.

hxs

namespace Eccelerators.HxS.Docs
{
    interface ExampleInterface
    {
        Name = "Example Interface";
        Description = "
            This is an interface describing a single block and a
            single register.
        ";
        Blocks = [ExampleBlock];
    }

    block ExampleBlock
    {
        Name = "Example Block";
        Description = "This is a block describing a single register.";
        Registers = [ExampleRegister];
    }

    register ExampleRegister
    {
        Name = "Example Register";
        Description = "
            This is an example of a register that uses a select
            signal. Writing to the register is only possible when
            the select signal is asserted.
        ";
        Selects = [ExampleSelect];
    }

    select ExampleSelect
    {
        Name = "Example Select";
        Description = "Select on write.";
        Behaviour = SelectBehaviour.Write;
    }
}

The select object has the following properties. NOTE: All properties are optional. Default values will be used if not set explicitly.

Property Name Description Type Default Value
Name The name of the select. String Empty String
Description A description of the select. String Empty String
Behaviour
  • Read
  • Write
  • ReadWrite
SelectBehaviour SelectBehaviour.ReadWrite
Version Version information (e.g. v1, 0.0.1) String Empty String