WB_INTERFACE - Configuring Item Types

The following sections take a closer look at configuration of each of the supported item types – Internal Register, Command Set, External Address Range – with respect to the WB_INTERFACE's custom interface.

Internal Register

An internal register allows a value to be read from, and/or written to, connected logic. This item type is defined using the Internal Register Properties dialog (Figure 1).

Figure 1. Configuration dialog for the internal register item.

Use the dialog to define the following properties for the internal register:

Name

A unique name for the register. Each item in the custom interface must have a unique name so that there are no name 'clashes' in the schematic document, the generated VHDL code, or the generated C code.
 

Data Width

The width of the data bus, in bits. This value can range from 1 to 32 bits, but must be less than or equal to, the value defined for the width of the Wishbone data bus.

IO Type

The direction of data access. You can specify Read, Write, or Read/Write.

Graphical Attributes

When the component is placed on a schematic sheet, this property allows you to specify the amount of blank space to be inserted after the item's bank of pins.

Slices

A register can, if required, be divided into smaller 'slices'. Each slice consists of a contiguous group of bits and the bit ranges of slices can not overlap.

Use the controls in this region of the dialog (buttons or commands from the right-click menu accessible from within the list area) to add, edit, remove, and reorder slice definitions.

When adding or editing a slice, its properties are defined in the Register Slice Properties dialog. From here, you define a unique name for the slice, and its bit range – in terms of Start (low order bit) and End (high order bit) indices. The start and end indices are inclusive.
 

 
Figure 2 illustrates the slicing of an internal register (named BIG) into two equal slices name HI (bits 7..4) and LO (bits 3..0).

Figure 2. Example division of a register into slices.

Command Set

A command set is a collection of commands, grouped into one or more command classes. Each command allows an operation to be enabled on connected logic. Similar to an instruction executed in a program, a command in the set consists of an opcode (command code) and one or more optional operands (data).

MSB                                                                                                                                                                                                                LSB
31                                             24	23                                             16	15                                             8	7                                             0
Opcode: 0101 0101	Operand1: AAAAAAAA	Operand2: BBBBBBBB	Operand3: CCCCCCCC

Figure 3. Example command that uses three operands.

 
This item type is defined using the Command Set Properties dialog (Figure 4).

Figure 4. Configuration dialog for the command set item.

Use the dialog to define the following properties for the command set:

Name

A unique name for the command set. Each item in the custom interface must have a unique name so that there are no name 'clashes' in the schematic document, the generated VHDL code, or the generated C code.
 

Data Width

The width of the data bus, in bits. This value can range from 1 to 32 bits, but must be less than or equal to, the value defined for the width of the Wishbone data bus.

Graphical Attributes

When the component is placed on a schematic sheet, this property allows you to specify the amount of blank space to be inserted after the item's bank of pins.

Immediate Acknowledgement

Enable this option to have an acknowledgement sent immediately (and automatically) to the host processor through the ACK_O pin in the Wishbone interface, upon completion of a successful operation.
 

 
When this option is disabled, an ACK_I pin will be added to the custom interface for the command set item. The externally-connected logic must take this pin High to generate the acknowledge signal (High) on the WB_INTERFACE'S ACK_O line to the host processor.

Commands and Classes

This region of the dialog is used to display and manage the command set's constituent command classes, commands and operands.

Use the available buttons (or commands from the right-click menu accessible from within the list area) to add, edit, remove, and reorder command classes and their constituent commands.

Defining a Command Class

When adding or editing a command class, its properties are defined in the Command Class Properties dialog (Figure 5).

Figure 5. Configuration dialog for a command class.

Use the upper region of the dialog to define a unique name for the class.

The lower region is used to display and manage any operands for the class. The command class itself is a collection of commands with the same type of operands. Therefore, any defined operands (and their corresponding outputs) will be shared by all commands in that class.

Use the controls in this region of the dialog (buttons or commands from the right-click menu accessible from within the list area) to add, edit, remove, and reorder operand definitions.

When adding or editing an operand, its properties are defined in the Operand Properties dialog. From here, you define a unique name for the operand, and its bit range – in terms of Start (low order bit) and End (high order bit) indices. The start and end indices are inclusive
 

 
Figure 6 illustrates the definition of an operand named BANK_NUM. It is 4 bits in size and is specified to be aligned to the lower 4 bits of a command that uses it. Figure 6 also illustrates the resulting entry for the operand in the Commands and Classes region of the main Command Set Properties dialog.

Figure 6. Example operand definition.

From Figure 6 we can see that the data width for the parent command set item has been set to 32 bits. The operand BANK_NUM, is 4 bits. In the command class REG to which this operand is associated, there is a single command – BANK. As can be seen, this 32-bit command is comprised of a 1-bit opcode ("0"), 27 unused bits ("XXXXXXXXXXXXXXXXXXXXXXXXXXX") and the 4-bit operand ("AAAA"). The unused bits are neither part of the opcode, nor the operand and will simply be ignored. With 28 bits available for the opcode, this command class can support a maximum of 2 ²⁸ commands (all of which would use the 4-bit operand, BANK_NUM).

To hit home the importance of correct operand definition and alignment, consider the following example of non-optimal operand definition:

• A command set with data width 32 bits

• A command class with two defined operands:
   
  • Operand1 – 8 bits located in the bit range 29..22
  • Operand2 – 8 bits located in the bit range 15..8

Figure 7 illustrates the make-up of a generic command added to this command class.

MSB                                                                                                                                                                                                                LSB
31         30	29                                             22		15                                             8
Opcode	Operand1: AAAAAAAA		Operand2: BBBBBBBB

Figure 7. Resulting command based on operand definition.

As mentioned previously, the opcode is automatically assigned to a command, and aligned to the higher order bits. From Figure 7 we can see that because of the way in which the two operands have been defined, only a 2-bit opcode can be generated. This allows for a maximum of 2 ² = 4 commands in this particular command class.

If the bit ranges for the operands were edited, so that they are aligned to the right and with no spaces between them, there would be 16 bits available to opcode assignment. This would result in a maximum of 2 ¹⁶ = 65536 commands definable for the command class.

Defining a Command

When adding or editing a command, its properties are defined in the Command Properties dialog (Figure 8).

Figure 8. Example command definition.

Simply give the command a unique name. The opcode for the command will automatically be assigned, taking into account any defined operands for the command class into which the command is added.
 

 
Each command will have a corresponding output pin in the interface, which will be driven High when enabled.

Troubleshooting

Sometimes adding an operand or command will fail. This happens because Altium Designer is unable to assign an opcode to all commands. When this happens, try one or more of the following solutions:

• Increase the data width of the command set if it is currently less than 32 bits

• Check that all operands are aligned to the low order bits, with no gaps between them

• Decrease the width of some operands if their expected range of values is smaller than the allocated width

• Remove some commands if they are not really needed.

If none of the above solutions offer a viable possibility, simply add another command set to the custom interface and define the required additional commands and operands there.

External Address Range

An external address range allows access to a block of addresses on connected logic. This item type is defined using the External Address Range Properties dialog (Figure 9).

Figure 9. Configuration dialog for the external address range item.

Use the dialog to define the following properties for the external address range:

Name

A unique name for the address range. Each item in the custom interface must have a unique name so that there are no name 'clashes' in the schematic document, the generated VHDL code, or the generated C code.
 

Data Width

The width of the data bus, in bits. This value can range from 1 to 32 bits, but must be less than or equal to, the value defined for the width of the Wishbone data bus.

IO Type

The direction of data access. You can specify Read, Write, or Read/Write.

Immediate Acknowledgement

Enable this option to have an acknowledgement sent immediately (and automatically) to the host processor through the ACK_O pin in the Wishbone interface, upon completion of a successful operation.
 

 
When this option is disabled, an ACK_I pin will be added to the custom interface for the external address range item. The connected logic must take this pin High to generate the acknowledge signal (High) on the WB_INTERFACE'S ACK_O line to the host processor.

Address Width

The width of the address bus (ADR_O) to the connected logic, in bits. This value can range from 0 bits (Range = 1) to 32 bits (Range = 4GB).

The base address is automatically assigned to an external address range item. In the main Configure (Wishbone Interface) dialog, the Item Address will reflect the address range in hex and binary format. Consider a WB_INTERFACE component configured with a single external address range item with a 5-bit address width. The Item Address will appear as:

0x00 - 0x1F (XXXXX)

As there is only one item in the interface, no bits are used to decode the item. Therefore all five bits (XXXXX) are forwarded to the connected logic in order to select an address in that component. To Read/Write address XXXXX on the component, put XXXXX on the Wishbone ADR_I bus.

Now consider a second external address range item added to the interface, with an 8-bit address width. The Item Address entries for the two items will appear as:

5-bit width item: 0x100 - 0x11F (1000XXXXX)

8-bit width item: 0x000 - 0x0FF (0XXXXXXXX)

Looking at our 5-bit width item, the 1000 prefix is used to decode the item, and the XXXXX bits are forwarded to the connected logic to select the required address. To Read/Write address XXXXX on the component, put 1000XXXXX on the Wishbone ADR_I bus.
 

Graphical Attributes

When the component is placed on a schematic sheet, this property allows you to specify the amount of blank space to be inserted after the item's bank of pins.