From 0a9b6967315d7be6a8450b0acee7164505966cc6 Mon Sep 17 00:00:00 2001 From: Istvan-Zsolt Szekely Date: Thu, 23 Jan 2025 11:29:17 +0200 Subject: [PATCH] docs/library/vip/amd/axis: Added documentation Signed-off-by: Istvan-Zsolt Szekely --- .../vip/amd/axis_vip/adi_axis_agent.rst | 102 +++++++++ .../vip/amd/axis_vip/adi_axis_monitor.rst | 69 ++++++ .../vip/amd/axis_vip/amd_axis_aggregation.svg | 182 +++++++++++++++ .../vip/amd/axis_vip/amd_axis_inheritance.svg | 182 +++++++++++++++ docs/library/vip/amd/axis_vip/index.rst | 51 ++++- .../vip/amd/axis_vip/m_axis_sequencer.rst | 207 ++++++++++++++++++ .../vip/amd/axis_vip/s_axis_sequencer.rst | 112 ++++++++++ 7 files changed, 896 insertions(+), 9 deletions(-) create mode 100644 docs/library/vip/amd/axis_vip/adi_axis_agent.rst create mode 100644 docs/library/vip/amd/axis_vip/adi_axis_monitor.rst create mode 100755 docs/library/vip/amd/axis_vip/amd_axis_aggregation.svg create mode 100755 docs/library/vip/amd/axis_vip/amd_axis_inheritance.svg create mode 100644 docs/library/vip/amd/axis_vip/m_axis_sequencer.rst create mode 100644 docs/library/vip/amd/axis_vip/s_axis_sequencer.rst diff --git a/docs/library/vip/amd/axis_vip/adi_axis_agent.rst b/docs/library/vip/amd/axis_vip/adi_axis_agent.rst new file mode 100644 index 00000000..8fa8fde4 --- /dev/null +++ b/docs/library/vip/amd/axis_vip/adi_axis_agent.rst @@ -0,0 +1,102 @@ +.. _adi_axis_agent: + +ADI AXIS Agent (VIP) +================================================================================ + +Overview +------------------------------------------------------------------------------- + +The ADI AXIS Agent uses the AMD (Xilinx) AXIS VIP at its core with added +sequencer, monitor and wrapper class. Has a master, slave and passthrough +variant. Provides functions to start, stop and run the classes within. Its +purpose is to create and contain everything under a single construct and not +have the user to create and manage each of these modules separately. + +Parameters +------------------------------------------------------------------------------- + +The ADI AXIS Agent parameters ``must`` be compatible with the VIP used in the +design. The virtual interface that is defined must be of the same type that +the VIP is using. The AMD AXIS VIP must also be compatible with the specified +parameters. The axis_definitions.svh header files has useful macros to create +and build the required parameter list. + +Variables +------------------------------------------------------------------------------- + +The core components are available for access depending on the agent type that +is instantiated. + +adi_axis_master_agent variant +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + * axi4stream_mst_agent agent + * m_axis_sequencer sequencer + * adi_axis_monitor monitor + +adi_axis_slave_agent variant +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + * axi4stream_slv_agent agent + * s_axis_sequencer sequencer + * adi_axis_monitor monitor + +adi_axis_passthrough_agent variant +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + * axi4stream_passthrough_agent agent + * m_axis_sequencer master_sequencer + * s_axis_sequencer slave_sequencer + * adi_axis_monitor monitor + +Methods +------------------------------------------------------------------------------- + +function new(input string name, virtual interface axis_vip_if vip_if, input adi_environment parent); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Creates the ADI AXIS Agent object. The name string is assigned to the instance +as an Identifier when logging. The vip_if is a Virtual Interface that is +instantiated inside the AXIS VIP when created. This is used to connect the VIP +(in block design) to the simulation. The parent variable is optional, it is +used to narrow down the origin of this class, used in logging. The parent +variable can only reference an adi_environment. + +task start(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Used to start the master or slave agent when not in passthrough mode. In +passthrough mode it throws a warning, since in the passthrough agent can only +work in master, slave or passthrough mode at a given time. + +.. important:: + + This warning message can be ommitted, as this causes no harm during + simulation. Its main use is to notify the user that the VIP in passthrough + mode is only monitoring and it must be changed manually to master or slave + mode if needed. + +task run(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Used to run the sequencer(s) and the monitor. + +task stop(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Used to stop the agent, the sequencer(s) and the monitor. + +Usage and recommendations +------------------------------------------------------------------------------- + +Basic usage of the ADI AXIS Agent: + +* Declare the ADI AXIS Agent, preferably inside an environment with the correct + parameters, give a name and if it's inside an environment, set the parent as + well +* Call the start function before resetting the entire system +* Configure the sequencer(s) +* Call the run function +* Call the start function in the case of master mode +* Run the test stimulus +* Call the stop function before the clocks associated to the VIP are stopped diff --git a/docs/library/vip/amd/axis_vip/adi_axis_monitor.rst b/docs/library/vip/amd/axis_vip/adi_axis_monitor.rst new file mode 100644 index 00000000..23b4e544 --- /dev/null +++ b/docs/library/vip/amd/axis_vip/adi_axis_monitor.rst @@ -0,0 +1,69 @@ +.. _adi_axis_monitor: + +ADI AXIS Monitor (VIP) +================================================================================ + +Overview +------------------------------------------------------------------------------- + +The ADI AXIS Monitor is created to efficiently capture data and broadcast it to +a set of subscribers that are monitoring the interface. + +Parameters +------------------------------------------------------------------------------- + +The ADI AXIS Monitor parameters are inherited from the ADI AXIS Agent. + +Variables +------------------------------------------------------------------------------- + +The publisher class is instantiated inside the monitor, which is available for +external access. This provides a means for other classes to subscribe and +receive captured data. + +Methods +------------------------------------------------------------------------------- + +function new(input string name, input axis_monitor monitor, input adi_agent parent); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Creates the ADI AXIS Monitor object. The name string is assigned to the instance +as an Identifier when logging. The axis_monitor references the monitor class +that is in the AMD AXIS VIP agent. The parent variable is optional, it is used +to narrow down the origin of this class, used in logging. The parent variable +can only reference an adi_agent. + +task run(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Used to start up the monitor. If a monitor instance is already running, it will +throw an error message and continues the simulation. + +.. important:: + + This error message can be ommitted, as this causes no harm during simulation. + However, it is highly recommended to review the simulation stimulus and + correct this error. + +function stop(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Used to stop the monitor. If the monitor is not running, it will have no effect. + +task get_transaction(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An infinite loop called by the run function. It is used to monitor the AXIS +interface, collect data and broadcast to the modules that subscribed to it. + +Usage and recommendations +------------------------------------------------------------------------------- + +Basic usage of the ADI AXIS Monitor: + +* Use it through the ADI AXIS Agent, declare and instantiate the agent +* Call the run function through the Agent +* Subscribe the modules that need to check data on this interface +* Run the test stimulus +* Call the stop function through the Agent before the clocks associated to the + VIP are stopped diff --git a/docs/library/vip/amd/axis_vip/amd_axis_aggregation.svg b/docs/library/vip/amd/axis_vip/amd_axis_aggregation.svg new file mode 100755 index 00000000..2e7c400c --- /dev/null +++ b/docs/library/vip/amd/axis_vip/amd_axis_aggregation.svg @@ -0,0 +1,182 @@ +xil_analysis_port#+writeinput T+getoutput Taxi4stream_vif_proxy#axi4stream_monitor#axi4stream_mst_driver#axi4stream_slv_driver#axi4stream_mst_agent#axi4stream_slv_agent#axi4stream_passthrough_agent# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/library/vip/amd/axis_vip/amd_axis_inheritance.svg b/docs/library/vip/amd/axis_vip/amd_axis_inheritance.svg new file mode 100755 index 00000000..376933b0 --- /dev/null +++ b/docs/library/vip/amd/axis_vip/amd_axis_inheritance.svg @@ -0,0 +1,182 @@ +xil_voidxil_objectxil_reporterxil_componentxil_agent-emptyxil_analysis_port#+writeinput T+getoutput Txil_driver#-emptyxil_monitor-emptyaxi4stream_vif_proxy#axi4stream_monitor#axi4stream_mst_driver#axi4stream_slv_driver#axi4stream_mst_agent#axi4stream_slv_agent#axi4stream_passthrough_agent# + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/library/vip/amd/axis_vip/index.rst b/docs/library/vip/amd/axis_vip/index.rst index 06066bbd..41815760 100644 --- a/docs/library/vip/amd/axis_vip/index.rst +++ b/docs/library/vip/amd/axis_vip/index.rst @@ -1,31 +1,64 @@ .. _xilinx_axis_vip: -Xilinx AXI Stream Verification IP (VIP) +Xilinx AXIS Stream Verification IP (VIP) ================================================================================ +.. toctree:: + :hidden: + + ADI AXIS Agent + ADI AXIS Master Sequencer + ADI AXIS Slave Sequencer + ADI AXIS Monitor + Overview -------------------------------------------------------------------------------- +The ADI AXIS Agent VIP uses the AMD (Xilinx) AXIS VIP at its core with added +sequencer, monitor and wrapper class. `[1] `__ -m_axi_sequencer --------------------------------------------------------------------------------- +Inheritance diagram for AMD AXIS VIP +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. svg:: ./library/vip/amd/axis_vip/amd_axis_inheritance.svg + :align: center + +Aggregation diagram for AMD AXIS VIP +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Files +.. svg:: ./library/vip/amd/axis_vip/amd_axis_aggregation.svg + :align: center + +Components +------------------------------------------------------------------------------- + +:ref:`adi_axis_agent` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Functions +Has a master, slave and passthrough variant. Encapsulates the AMD AXIS VIP, ADI +AXIS Master and/or Slave Sequencers and the ADI AXIS Monitor. Provides functions +to start, stop and run the classes within. + +:ref:`m_axis_sequencer` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -s_axi_sequencer --------------------------------------------------------------------------------- +The ADI AXIS Master Sequencer provides functions to generate data on an AXI +Streaming interface. -Files +:ref:`s_axis_sequencer` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Functions +The ADI AXIS Slave Sequencer provides functions to create user specified +backpressure characteristics. + +:ref:`adi_axis_monitor` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The ADI AXIS Monitor provides functions to monitor an AXI Stream interface, +collect data transmitted and broadcast it to other classes using a +publisher-subscriber pattern. + References ------------------------------------------------------------------------------- diff --git a/docs/library/vip/amd/axis_vip/m_axis_sequencer.rst b/docs/library/vip/amd/axis_vip/m_axis_sequencer.rst new file mode 100644 index 00000000..74b076eb --- /dev/null +++ b/docs/library/vip/amd/axis_vip/m_axis_sequencer.rst @@ -0,0 +1,207 @@ +.. _m_axis_sequencer: + +ADI AXIS Master Sequencer (VIP) +================================================================================ + +Overview +------------------------------------------------------------------------------- + +The ADI AXIS Master Sequencer is created to easily generate AXI Stream +transfers. + +Parameters +------------------------------------------------------------------------------- + +The ADI AXIS Master Sequencer parameters are inherited from the ADI AXIS Agent. + +Variables +------------------------------------------------------------------------------- + +None are available for direct external access. + +Methods +------------------------------------------------------------------------------- + +function new(input string name, input axi4stream_mst_driver driver, input adi_agent parent); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Creates the ADI AXIS Master Sequencer object. The name string is assigned to the +instance as an Identifier when logging. The write and read drivers reference +the driver classes that are in the AMD AXIS VIP agent. The parent variable is +optional, it is used to narrow down the origin of this class, used in logging. +The parent variable can only reference an adi_agent. + +virtual task set_inactive_drive_output_0(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the AMD AXIS VIP to drive the outputs of the AXIS interface with 0s when +inactive. + +virtual function bit check_ready_asserted(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Provides a way through the sequencer to check if the slave interface asserts +ready. + +virtual task wait_clk_count(input int wait_clocks); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Waits for the specified amount of clock cycles that is associated with the VIP. + +virtual protected task packetize(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Packetizes the data before sending it to the driver. + +virtual protected task sender(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the packetize method finished creating a packet, it notifies the sender. +The sender gets the data and transfers it to the driver. When finished, it +notifies the other methods that the transfer is complete and a new packet can +be created. + +virtual function void add_xfer_descriptor_packet_size(...); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Used to set the number of samples that each packet is going to have using the +VIP's parameters. + +virtual task beat_sent(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Function provided to the sequencer to wait until a data beat is sent. If the +driver module is already inactive, it means that no transfer is being processed +and the sequencer can be safely disabled. + +virtual task packet_sent(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Function provided to the sequencer to wait until a data packet is sent. If the +driver module is already inactive and the last signal has been sent, it means +that no transfer is being processed and the last sample in the packet was also +sent, so the sequencer can be safely disabled. + +function void set_stop_policy(input stop_policy_t stop_policy); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the stop policy to data beat, packet or queue finished. If the sequencer +is already enabled, it will throw an error message. + +function void set_data_gen_mode(input data_gen_mode_t data_gen_mode); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the data generation mode. It can be a ramp, randomly generated data, or +user specified data. If the sequencer is already enabled, it will throw an +error message. + +.. caution:: + + If the data is user specified, the user must make sure that the packetizer + is fed with enough data to complete a packet, otherwise the packet will not + be transfered to the driver. + +function void set_descriptor_gen_mode(input bit descriptor_gen_mode); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the packet generation mode. If set to 0, it will only create the packets +that are in the queue. If set to 1, it will repeat all of the packets that are +in the queue in a round-robin mode. If the sequencer is already enabled, it +will throw an error message. + +function void set_data_beat_delay(input int data_beat_delay); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets a specified amount of inactive clock cycles between each data beat. + +function void set_descriptor_delay(input int descriptor_delay); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets a specified amount of inactive clock cycles between each packet transfer. + +function void set_keep_all(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the generated data to be all valid bytes. Automatically adjusts the packet +length, increasing its size, if the specified number of bytes don't fill all +samples with data. If the sequencer is already enabled, it will throw an error +message. + +function void set_keep_some(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the generated data to have not valid bytes. If the sequencer is already +enabled, it will throw an error message. + +function void add_xfer_descriptor(...); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Used to set the number of bytes to be sent to the driver. + +protected task descriptor_delay_subroutine(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Used by the generator function to wait for a specified amount of clock cycles +before transferring the next packet. + +task wait_empty_descriptor_queue(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Function provided to the sequencer to wait until the transfer queue is empty. +If the queue is already empty, it will automatically return. + +task clear_descriptor_queue(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Clears the transfer queue. Transfers that are already being processed by the +packetizer will be finished regardless. + +protected task generator(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The generator checks the status of the sequencer and if it's enabled, it will +call the packetize task to create a transfer based on the packets description +in queue. If the queue is empty, it generates an event, notifying that all of +the data has been processed. When a new packet description is added to the +queue it resumes its operation. + +function void push_byte_for_stream(xil_axi4stream_data_byte byte_stream); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Used when the data descriptor mode is set for user generated data. In this mode, +the user must specify a byte, which is put into a byte stream. The byte stream +is processed by the packetizer when it is ready to prepare a new transfer. + +protected task data_beat_delay_subroutine(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Used by the packetize method to set the transfer wait time between data beats. + +task start(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enables the sequencer. + +task stop(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Disables the sequencer. + +task run(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Starts the generator and the sender functions. + +Usage and recommendations +------------------------------------------------------------------------------- + +Basic usage of the ADI AXIS Master Sequencer: + +* Use it through the ADI AXIS Agent, declare and instantiate the agent +* Configure the sequencer +* Call the run function +* Call the sequencer's start function +* Generate data packets +* Call the stop function to stop the sequencer if needed +* Call the stop function through the Agent before the clocks associated to the + VIP are stopped diff --git a/docs/library/vip/amd/axis_vip/s_axis_sequencer.rst b/docs/library/vip/amd/axis_vip/s_axis_sequencer.rst new file mode 100644 index 00000000..a051a57d --- /dev/null +++ b/docs/library/vip/amd/axis_vip/s_axis_sequencer.rst @@ -0,0 +1,112 @@ +.. _s_axis_sequencer: + +ADI AXIS Slave Sequencer (VIP) +================================================================================ + +Overview +------------------------------------------------------------------------------- + +The ADI AXIS Slave Sequencer is created to configure the AXI Stream +backpressure. + +Parameters +------------------------------------------------------------------------------- + +The ADI AXIS Slave Sequencer parameters are inherited from the ADI AXIS Agent. + +Variables +------------------------------------------------------------------------------- + +None are available for direct external access. + +Methods +------------------------------------------------------------------------------- + +function new(input string name, input axi4stream_slv_driver driver, input adi_agent parent); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Creates the ADI AXIS Master Sequencer object. The name string is assigned to the +instance as an Identifier when logging. The write and read drivers reference +the driver classes that are in the AMD AXIS VIP agent. The parent variable is +optional, it is used to narrow down the origin of this class, used in logging. +The parent variable can only reference an adi_agent. + +function void set_use_variable_ranges(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the variable ranges variable value to 1. This will mean that the sequencer +will generate backpressure based on a range of variables. + +function void clr_use_variable_ranges(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the variable ranges variable value to 1. This will mean that the sequencer +will generate a repeating sequence of backpressure. + +function void set_mode(input xil_axi4stream_ready_gen_policy_t mode); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the ready generation policy to the specified mode. This value is defined +in the AMD AXIS VIP ready generation policies. + +function xil_axi4stream_ready_gen_policy_t get_mode(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Get the current ready generation policy. This value is defined in the AMD AXIS +VIP ready generation policies. + +function void set_high_time(input xil_axi4stream_uint high_time); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the high signal clock cycles of the ready signal when the sequencer has a +repeating sequence of backpressure. + +function xil_axi4stream_uint get_high_time(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Get the high signal clock cycles of the ready signal. + +function void set_high_time_range(...); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the high signal clock cycles ranges of the ready signal when the sequencer +has varying backpressure. + +function void set_low_time(input xil_axi4stream_uint low_time); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the low signal clock cycles of the ready signal when the sequencer has a +repeating sequence of backpressure. + +function xil_axi4stream_uint get_low_time(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Get the low signal clock cycles of the ready signal. + +function void set_low_time_range(...); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the low signal clock cycles ranges of the ready signal when the sequencer +has varying backpressure. + +task run(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Calls the user generated tready function. + +virtual task user_gen_tready(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Creates a ready generation data structure based on the provided configuration +and then it sends to the driver. + +Usage and recommendations +------------------------------------------------------------------------------- + +Basic usage of the ADI AXIS Master Sequencer: + +* Use it through the ADI AXIS Agent, declare and instantiate the agent +* Configure the sequencer +* Call the run function +* If the sequencer needs to be reconfigured during simulation, then reconfigure + the parameters and then call the run function again