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.
|
BusType | BusType.Wishbone |
AddressBusWidth | The size in bits of the address bus. | Number | 32 |
DataBusWidth | The size in bits of the data bus. | Number | 8 |
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. | Number | 0x0 |
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 |
|
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:
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 |
|
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:
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 |
|
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 |
|
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 |
|
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 |
|
SelectBehaviour | SelectBehaviour.ReadWrite |
Version | Version information (e.g. v1, 0.0.1) | String | Empty String |