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.


    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.


    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.


    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.


    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.


    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.


    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.


    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.


    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.


    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.


    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.


    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