Generic Command Queue IP v2.0 - Product Guide¶
Overview¶
Generic command queue (GCQ) IP is used for communication queues between endpoints for XRT related consumers and producers such as PCIe® host, APU, RPU, and Microblaze.
IP implement queue that contains single doorbell register for tail pointer and interrupt output that is configurable to generate interrupt on write to tail pointer or manually setting the interrupt register.
Current version of IP implements two queues as shown in the block diagram below.
Submission queue
Used to send command to peer.
Generates submission queue interrupt (irq_sq) based on the SQ register settings.
Completion queue
Used to receive command from peer.
Generates completion queue interrupt (irq_cq) based on the CQ register settings.
The sequence to execute commands:
Producer puts commands into submission queue entries with unique command ID for each command.
Producer writes the tail pointer to submission queue doorbell register (triggering an interrupt to consumer in interrupt mode).
Consumer reads submission queue entries and consumes the commands.
Upon completion, consumer writes each completion to completion queue entries with completed command ID.
Consumer writes the tail pointer to completion queue doorbell register (triggering an interrupt to producer in interrupt mode).
Producer reads the completion queue entries and then updates the submission queue head pointer so that those entries can be reused.
Features¶
A command queue IP that receives commands from the producer and writes into register space for the consumer to read and vice versa.
Handshakes through commands and addresses for asynchronous I/O using a ring buffer.
Implements AXI4-Subordinate as an interface for both producer and consumer.
Interrupt output enable/disable capabilities.
Interrupts can be fired directly by setting a bit within the register space or it can be triggered via writing to the interrupt register tail pointer.
AXI4 busses and other internal logic all run on one master clock.
Applications¶
The diagram below outlines a typical use case for the Generic Command Queue IP as deployed within AMD Versal™ devices. The Generic Command Queue IP communicates with other IPs by implementing an AXI4-Subordinate. The register space of the GCQ IP v2.0 allows IPs connected to it through the AXI interface produce CQ and SQ interrupts out of GCQ IP itself. Command queue process is from 1 to 2 shown in the diagram below. This flow is explained in the Architecture Overview section.
Below is an example usage of a GCQ IP v2.0 in Versal device.
Standards¶
Generic Command Queue IP is compliant to the AMBA AXI and ACE Protocol Specification Version E.
Architecture Overview¶
The block diagram below gives a high level overview of the logical structure of the Generic Command Queue IP. The IP implements a logic that does not have a dependency on a parameter, therefore below diagram is valid for any instantiation of the IP.
The flow of command process is from the producer to the consumer. The producer writes commands to the tail on the Submission Queue through S00_AXI. Then, it writes to the tail pointer register in the submission queue indicating the tail for the consumer, this triggers an interrupt (irq_sq). The consumer reads the tail pointer on the submission queue and starts to consume from head to tail in the submission queue, which results in the clearing of the submission queue interrupt (irq_sq). The head pointer is stored within software local memory, so this information is not directly related to the IP, but the software. Reading the command and processing that command, the consumer writes to the tail pointer register in the Completion Queue along with the commands it consumed to the completion queue tail, which also triggers an interrupt (irq_cq). The producer reads the completion queue tail pointer to read the queue from head till the tail, which clears the completion queue interrupt (irq_cq).
Resource Use¶
The table below contains resource utilization data for several configurations of the Generic Command Queue IP core. Any configuration parameters that are not listed have their default values. Any parameters with a blank value are disabled or set automatically by the IP core.
Resource figures are taken from the utilization report issued at the end of implementation using the Out-of-Context flow in the AMD Vivado Design Suite™.
Default Vivado Design Suite 2023.2 settings were used. You may be able to improve on these figures using different settings. Because surrounding circuitry will affect placement and timing, no guarantee can be given that these figures will be repeatable in a larger design.
| Vivado Release | Family | Device | Package | Speedgrade | Configuration Name | Fixed Clocks | LUT | FF | DSP | 36k BRAMs | 18k BRAMs |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 2023.2 | versal | xcv80 | lsva4737 | 2MHP | ip_char | aclk=300 | 464 | 304 | 0 | 0 | 0 |
Interface Descriptions¶
The table below gives an overview of the external interfaces and ports super-set present on the boundary of the GCQ IP v2.0.
| Interface | Signal | Direction | Range | Clock | Enablement Dependency | Description |
|---|---|---|---|---|---|---|
| S00_AXI | s00_axi_awaddr | Input | 11:0 | aclk | true | Producer AXI4-Lite write address |
| s00_axi_awvalid | Input | scalar | aclk | true | Producer AXI4-Lite write address valid | |
| s00_axi_awready | Output | scalar | aclk | true | Producer AXI4-Lite write address ready | |
| s00_axi_wdata | Input | 31:0 | aclk | true | Producer AXI4-Lite write data | |
| s00_axi_wstrb | Input | 3:0 | aclk | true | Producer AXI4-Lite write strobes | |
| s00_axi_wvalid | Input | scalar | aclk | true | Producer AXI4-Lite write data valid | |
| s00_axi_wready | Output | scalar | aclk | true | Producer AXI4-Lite write data ready | |
| s00_axi_bresp | Output | 1:0 | aclk | true | Producer AXI4-Lite write response | |
| s00_axi_bvalid | Output | scalar | aclk | true | Producer AXI4-Lite write response valid | |
| s00_axi_bready | Input | scalar | aclk | true | Producer AXI4-Lite write response ready | |
| s00_axi_araddr | Input | 11:0 | aclk | true | Producer AXI4-Lite read address | |
| s00_axi_arvalid | Input | scalar | aclk | true | Producer AXI4-Lite read address valid | |
| s00_axi_arready | Output | scalar | aclk | true | Producer AXI4-Lite read address ready | |
| s00_axi_rdata | Output | 31:0 | aclk | true | Producer AXI4-Lite read data | |
| s00_axi_rresp | Output | 1:0 | aclk | true | Producer AXI4-Lite read response | |
| s00_axi_rvalid | Output | scalar | aclk | true | Producer AXI4-Lite read valid | |
| s00_axi_rready | Input | scalar | aclk | true | Producer AXI4-Lite read ready | |
| S01_AXI | s01_axi_awaddr | Input | 11:0 | aclk | true | Consumer AXI4-Lite write address |
| s01_axi_awvalid | Input | scalar | aclk | true | Consumer AXI4-Lite write address valid | |
| s01_axi_awready | Output | scalar | aclk | true | Consumer AXI4-Lite write address ready | |
| s01_axi_wdata | Input | 31:0 | aclk | true | Consumer AXI4-Lite write data | |
| s01_axi_wstrb | Input | 3:0 | aclk | true | Consumer AXI4-Lite write strobes | |
| s01_axi_wvalid | Input | scalar | aclk | true | Consumer AXI4-Lite write data valid | |
| s01_axi_wready | Output | scalar | aclk | true | Consumer AXI4-Lite write data ready | |
| s01_axi_bresp | Output | 1:0 | aclk | true | Consumer AXI4-Lite write response | |
| s01_axi_bvalid | Output | scalar | aclk | true | Consumer AXI4-Lite write response valid | |
| s01_axi_bready | Input | scalar | aclk | true | Consumer AXI4-Lite write response ready | |
| s01_axi_araddr | Input | 11:0 | aclk | true | Consumer AXI4-Lite read address | |
| s01_axi_arvalid | Input | scalar | aclk | true | Consumer AXI4-Lite read address valid | |
| s01_axi_arready | Output | scalar | aclk | true | Consumer AXI4-Lite read address ready | |
| s01_axi_rdata | Output | 31:0 | aclk | true | Consumer AXI4-Lite read data | |
| s01_axi_rresp | Output | 1:0 | aclk | true | Consumer AXI4-Lite read response | |
| s01_axi_rvalid | Output | scalar | aclk | true | Consumer AXI4-Lite read valid | |
| s01_axi_rready | Input | scalar | aclk | true | Consumer AXI4-Lite read ready | |
| aclk | aclk | Input | scalar | true | Clock associated with the S00_AXI/S01_AXI interfaces | |
| aresetn | aresetn | Input | scalar | aclk | true | Active-Low reset associated with the S00_AXI/S01_AXI interfaces |
| irq_sq | irq_sq | Output | scalar | aclk | true | Rising Edge interrupt output for submission queue |
| irq_cq | irq_cq | Output | scalar | aclk | true | Rising Edge interrupt output for completion queue |
Clocking¶
Generic Command Queue IP operates on a single clock domain ‘aclk’ and the AXI interface used in the IP is also running on the same clock domain.
The table below outlines the clock frequency ranges supported by the IP.
Clock Domain | Min (MHz) | Max (MHz) | Description |
|---|---|---|---|
| aclk | 0 | 300 | Clock used for S00_AXI and S01_AXI interface and internal core operation. |
Resets¶
Generic Command Queue IP is reset on assertion of the ‘aresetn’ active low reset input associated with the only master clock ‘aclk’ and is resetting AXI4 buses.
Interrupts¶
Interrupts irq_sq and irq_cq will be triggered upon register settings.
Register Space¶
Producer AXI Register Space¶
The table below outlines the layout and descriptions for the memory mapped register space within the GCQ IP v2.0, these registers are accessible via the Producer AXI interface i.e., S00_AXI interface.
| Register Address Offset | Register Name | Field Name | Bit Index | Default Value | Attribute | Field Description |
|---|---|---|---|---|---|---|
| 0x000 | SQ_TAIL_POINTER | TAIL_POINTER_OFFSET | 31:0 | 0x0 | RW | Submission Queue Tail Pointer Offset Configure the Tail Pointer offset for the Submission Queue. If the INTERRUPT_TYPE field in SQ_RESET_INTERRUPT_CTRL register is 0x0, then a write to this register triggers the submission queue interrupt. Once triggered, the submission queue interrupt can only be cleared by reading the the SQ_TAIL_POINTER register on the S01_AXI interface. |
| 0x004 | SQ_INTERRUPT_REG | INTERRUPT | 0 | 0x0 | WO | Submission Queue Interrupt When set - and while the INTERRUPT_TYPE field is 0x1, INTERRUPT_ENABLE field is 0x1, and RESET field is 0x0 in SQ_RESET_INTERRUPT_CTRL register - triggers an interrupt on the submission queue. Once triggered, the submission queue interrupt can only be cleared by reading the INTERRUPT_STATUS field of the SQ_INTERRUPT_STATUS register. 0x0 - Do not trigger an interrupt on the submission queue 0x1 - Trigger an interrupt on the submission queue |
| INTERRUPT_STATUS | 1 | 0x0 | RO | Submission Queue Interrupt Status Reports the current status of the Submission Queue interrupt. 0x0 - Submission Queue interrupt de-asserted 0x1 - Submission Queue interrupt asserted | ||
| 0x008 | SQ_QUEUE_MEM_ADDR_LOW | MEM_ADDR_LOW | 31:0 | 0x0 | RW | Submission Queue Memory Address Low Represents bits 31:0 of the submission queue device memory address. |
| 0x00C | SQ_RESET_INTERRUPT_CTRL | INTERRUPT_ENABLE | 0 | 0x0 | RW | Submission Queue Interrupt Enable When set, enables the submission queue interrupt output. 0x0 - Disable submission queue interrupt 0x1 - Enable submission queue interrupt |
| INTERRUPT_TYPE | 1 | 0x0 | RW | Submission Queue Interrupt Type Determines the interrupt type in use for the submission queue. 0x0 - Interrupt for the submission queue is triggered on a write operation to the SQ_TAIL_POINTER register 0x1 - Interrupt for the submission queue is triggered by setting the INTERRUPT field of the SQ_INTERRUPT_REG register to 0x1 | ||
| RESET | 31 | 0x0 | WO | Reset Performs a soft reset of all submission queue and completion queue registers. 0x0 - Do not reset all submission/completion queue registers 0x1 - Reset all submission/completion queue registers This field is self-clearing once set. | ||
| 0x010 | SQ_QUEUE_MEM_ADDR_HIGH | MEM_ADDR_HIGH | 31:0 | 0x0 | RW | Submission Queue Memory Address High Represents bits 63:32 of the submission queue device memory address. |
| 0x100 | CQ_TAIL_POINTER | TAIL_POINTER_OFFSET | 31:0 | 0x0 | RO | Completion Queue Tail Pointer Offset Returns the tail pointer offset for the completion queue. If the INTERRUPT_TYPE field in CQ_RESET_INTERRUPT_CTRL is 0x0, then reading this register clears the completion queue interrupt if asserted. |
| 0x104 | CQ_INTERRUPT_STATUS | INTERRUPT_STATUS | 0 | 0x0 | RO | Completion Queue Interrupt Status Returns the current state of the interrupt for the completion queue. If the INTERRUPT_TYPE field in CQ_RESET_INTERRUPT_CTRL is 0x1, then reading this register clears the completion queue interrupt if asserted. |
| 0x108 | CQ_QUEUE_MEM_ADDR_LOW | MEM_ADDR_LOW | 31:0 | 0x0 | RO | Completion Queue Memory Address Low Returns bits 31:0 of the completion queue device memory address. |
| 0x10C | CQ_RESET_INTERRUPT_CTRL | INTERRUPT_ENABLE | 0 | 0x0 | RO | Completion Queue Interrupt Enable Returns the enable state for completion queue interrupt. 0x0 - Completion Queue interrupt output disabled 0x1 - Completion Queue interrupt output enabled |
| INTERRUPT_TYPE | 1 | 0x0 | RO | Completion Queue Interrupt Type Returns the interrupt type for the completion queue. 0x0 - Interrupt for the completion queue is triggered on a write operation to the CQ_TAIL_POINTER register 0x1 - Interrupt for the completion queue is triggered by setting the INTERRUPT field of the CQ_INTERRUPT_REG register to 0x1 | ||
| 0x110 | CQ_QUEUE_MEM_ADDR_HIGH | MEM_ADDR_HIGH | 31:0 | 0x0 | RO | Completion Queue Memory Address High Returns bits 63:32 of the completion queue device memory address. |
Consumer AXI Register Space¶
The table below outlines the layout and descriptions for the memory mapped register space within the GCQ IP v2.0, these registers are accessible via the Consumer AXI interface i.e., S01_AXI interface.
| Register Address Offset | Register Name | Field Name | Bit Index | Default Value | Attribute | Field Description |
|---|---|---|---|---|---|---|
| 0x000 | CQ_TAIL_POINTER | TAIL_POINTER_OFFSET | 31:0 | 0x0 | RW | Completion Queue Tail Pointer Offset Configure the Tail Pointer offset for the Completion Queue. If the INTERRUPT_TYPE field in CQ_RESET_INTERRUPT_CTRL register is 0x0, then a write to this register triggers the completion queue interrupt. Once triggered, the completion queue interrupt can only be cleared by reading the the CQ_TAIL_POINTER register on the S00_AXI interface. |
| 0x004 | CQ_INTERRUPT_REG | INTERRUPT | 0 | 0x0 | WO | Completion Queue Interrupt When set - and while the INTERRUPT_TYPE field is 0x1, INTERRUPT_ENABLE field is 0x1, and RESET field is 0x0 in SQ_RESET_INTERRUPT_CTRL register - triggers an interrupt on the completion queue. Once triggered, the completion queue interrupt can only be cleared by reading the INTERRUPT_STATUS field of the CQ_INTERRUPT_STATUS register. 0x0 - Do not trigger an interrupt on the completion queue 0x1 - Trigger an interrupt on the completion queue |
| INTERRUPT_STATUS | 1 | 0x0 | RO | Completion Queue Interrupt Status Reports the current status of the Completion Queue interrupt. 0x0 - Completion Queue interrupt de-asserted 0x1 - Completion Queue interrupt asserted | ||
| 0x008 | CQ_QUEUE_MEM_ADDR_LOW | MEM_ADDR_LOW | 31:0 | 0x0 | RW | Completion Queue Memory Address Low Represents bits 31:0 of the completion queue device memory address. |
| 0x00C | CQ_RESET_INTERRUPT_CTRL | INTERRUPT_ENABLE | 0 | 0x0 | RW | Completion Queue Interrupt Enable When set, enables the completion queue interrupt output. 0x0 - Disable completion queue interrupt 0x1 - Enable completion queue interrupt |
| INTERRUPT_TYPE | 1 | 0x0 | RW | Completion Queue Interrupt Type Determines the interrupt type in use for the completion queue. 0x0 - Interrupt for the completion queue is triggered on a write operation to the CQ_TAIL_POINTER register 0x1 - Interrupts for the completion queue are triggered by setting the INTERRUPT field of the CQ_INTERRUPT_REG register to 0x1 | ||
| RESET | 31 | 0x0 | WO | Reset Performs a soft reset of all submission queue and completion queue registers. 0x0 - Do not reset all submission/completion queue registers 0x1 - Reset all submission/completion queue registers This field is self-clearing once set. | ||
| 0x010 | CQ_QUEUE_MEM_ADDR_HIGH | MEM_ADDR_HIGH | 31:0 | 0x0 | RW | Completion Queue Memory Address High Represents bits 63:32 of the completion queue device memory address. |
| 0x100 | SQ_TAIL_POINTER | TAIL_POINTER_OFFSET | 31:0 | 0x0 | RO | Submission Queue Tail Pointer Offset Returns the tail pointer offset for the submission queue. If the INTERRUPT_TYPE field in SQ_RESET_INTERRUPT_CTRL is 0x0, then reading this register clears the submission queue interrupt if asserted. |
| 0x104 | SQ_INTERRUPT_STATUS | INTERRUPT_STATUS | 0 | 0x0 | RO | Submission Queue Interrupt Status Returns the current state of the interrupt for the submission queue. If the INTERRUPT_TYPE field in SQ_RESET_INTERRUPT_CTRL is 0x1, then reading this register clears the submission queue interrupt if asserted. |
| 0x108 | SQ_QUEUE_MEM_ADDR_LOW | MEM_ADDR_LOW | 31:0 | 0x0 | RO | Submission Queue Memory Address Low Returns bits 31:0 of the submission queue device memory address. |
| 0x10C | SQ_RESET_INTERRUPT_CTRL | INTERRUPT_ENABLE | 0 | 0x0 | RO | Submission Queue Interrupt Enable Returns the enable state for submission queue interrupt. 0x0 - Submission Queue interrupt output disabled 0x1 - Submission Queue interrupt output enabled |
| INTERRUPT_TYPE | 1 | 0x0 | RO | Submission Queue Interrupt Type Returns the interrupt type for the submission queue. 0x0 - Interrupt for the submission queue is triggered on a write operation to the SQ_TAIL_POINTER register 0x1 - Interrupt for the submission queue is triggered by setting the INTERRUPT field of the SQ_INTERRUPT_REG register to 0x1 | ||
| 0x110 | SQ_QUEUE_MEM_ADDR_HIGH | MEM_ADDR_HIGH | 31:0 | 0x0 | RO | Submission Queue Memory Address High Returns bits 63:32 of the submission queue device memory address. |
Customizing and Generating the IP¶
This section includes information about using AMD tools to customize and generate the GCQ IP v2.0 using the Vivado Design Suite.
If you are customizing and generating the IP in the Vivado IP integrator, see the Vivado Design Suite User Guide: Designing IP Subsystems using IP Integrator(UG994) for detailed information.
Importing the IP Repository¶
The GCQ IP v2.0 is delivered as a standalone IP repository that can be imported for use within Vivado Design Suite. Refer to the Vivado Design Suite User Guide: Designing with IP(UG896) for detailed information on adding an external IP repository to a project.
Customizing the IP¶
You can customize the IP for use in your design by specifying values for the various user parameters associated with the IP using the following steps:
Select the IP from the IP catalog.
Double-click the selected IP or select the Customize IP command from the toolbar or right-click menu.
Component Name¶
The Component name is used as the name of the top-level wrapper file for the core. The underlying netlist still retains its original name. Names must begin with a letter and must be composed from the following characters: a through z, 0 through 9, and “_”. The default is cmd_queue_0.
Parameters¶
The GCQ IP v2.0 does not have any user parameters. Therefore, there cannot be any pre-synthesis customizations to the IP.
Output Generation¶
For detailed information on generating IP output products, please refer to the Vivado Design Suite User Guide: Designing with IP (UG896).
Simulation¶
For comprehensive information about Vivado simulation components, as well as information about using supported third-party tools, see the Vivado Design Suite User Guide: Logic Simulation(UG900).
Synthesis and Implementation¶
For details about synthesis and implementation, see the Vivado Design Suite User Guide: Designing with IP (UG896).
Driver¶
Please refer to AMI Architecture for details on the software driver and interactions with the Generic Command Queue IP.
Example Design¶
The GCQ IP v2.0 does not currently support generation of an IP example design.
Page Revision: v. 14