docs/library/vip/amd/axis: Added documentation

Signed-off-by: Istvan-Zsolt Szekely <[email protected]>

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

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

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_agent>
+   ADI AXIS Master Sequencer <m_axis_sequencer>
+   ADI AXIS Slave Sequencer <s_axis_sequencer>
+   ADI AXIS Monitor <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] <https://docs.amd.com/v/u/en-US/pg277-axi4stream-vip>`__
 
-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
 -------------------------------------------------------------------------------