.. _userguide: User Guide ========== This section describes the details on usage of the XVSEC IP **Control XVSEC through "xvsecctl" application** ------------------------------------------------ XVSEC SW includes a command-line utility called ``xvsecctl`` to manage the driver which gets built with driver and allows controlling of vendor specific functionality. It supports the following functionalities - Generic VSEC functionality - Lists the supported VSECs by the device - Verbose information about the device - The following MCAP operations supported for US/US+ devices - Configuration Logic Reset - MCAP Module Reset - Full Reset (Both Configuration Logic and MCAP Module Reset) - List MCAP Read Data Registers - List MCAP Register set - List FPGA Configuration Register set - Access(Read/Write) any MCAP register by providing offset - Access(Read/Write) any FPGA configuration register by providing register number - Program partial clear bitstream - Program Stage-2/partial reconfigurable bitstream - The following MCAP operations supported for Versal devices - MCAP Module Reset - List MCAP Register set - File Download at user specified address - Fixed Address download for FIFO devices - Increment Address download - 32b mode download for 32b supported devices - 128b mode download for 128b suppported devices - Slow and Fast download mode supported - File Upload from user specified address - Fixed Address upload for FIFO devices - Increment Address upload - Access(Read/Write) any MCAP register by providing offset - Access(Read/Write) any Device register connected to AXI bus by providing address - Set the AXI cache and protections bits - For help run - xvsecctl -h - Refer to :ref:`usr_app` for command options for all supported options by application tool This version of the driver has the following limitation: **Only MCAP VSEC is supported** Some MCAP functional usecases supported by xvsecctl application are given below ************************************ XVSEC Control Application (xvsecctl) ************************************ **Get the list of VSECs supported by device** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - List the devices using lspci to cross check the devices are detected as PCIe devices - login with root credentials and execute the below command to list the devices. :: [xilinx@] # lspci | grep -i Xilinx 65:00.0 Serial controller: Xilinx Corporation Device 9034 **Generic xvsecctl utility commands** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **1. List XVSEC Capabilities** command: ``xvsecctl -b -F -l`` **Parameters** b : - Specify PCI bus no on which device sits F : - Specify PCI device no on the bus Description: Lists the supported VSECs :: [xilinx@]# ./xvsecctl -b 0x65 -F 0x0 -l No of Supported Extended capabilities : 3 VSEC ID VSEC Rev VSEC Name Driver Support ------- -------- --------- -------------- 0x0001 0x0001 PCIe_MCAP_VSEC Yes 0x0000 0x0000 UNKNOWN No 0x0008 0x0000 PCIe_XVC_DEBUG_VSEC No **2. Lists basic information about the device** command: ``./xvsecctl -b -F -v`` Description: Prints Verbose Information of the given device. :: [xilinx@]# ./xvsecctl -b 0x65 -F 0x0 -v Xilinx VSEC Tool : v2020.2.0 Xilinx VSEC Library : v2020.2.0 ----------------------------------- vendor_id = 0x10EE device_id = 0xB03F device_no = 0x0 device_fn = 0x0 subsystem_vendor = 0x10EE subsystem_device = 0x7 class_id = 0x5800 cfg_size = 0x1000 is_msi_enabled = 0x0 is_msix_enabled = 0x0 **US/US+ MCAP Specific Options** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **1. MCAP Reset** command: ``./xvsecctl -b -F -c 0x1 -r`` Description: It Performs Simple Reset. :: [xilinx@]# ./xvsecctl -b 0x08 -F 0x0 -c 0x1 -r MCAP version: 1 Configuration Logic Reset Successful **2. MCAP Module Reset** command: ``./xvsecctl -b -F -c 0x1 -m`` Description: Performs Module Reset. :: [xilinx@]# ./xvsecctl -b 0x08 -F 0x0 -c 0x1 -m MCAP version: 1 MCAP Module Reset Successful **3. MCAP Full Reset** command: ``./xvsecctl -b -F -c 0x1 -f`` Description: This command Performs Full Reset. It is equivalent to MCAP Simpale Reset + MCAP Module Reset. :: [xilinx@]# sudo ./xvsecctl -b 0x08 -F 0x0 -c 0x1 -f MCAP version: 1 Both Configuration Logic & MCAP Module Reset Successful **4. Lists Data register Contents** command: ``./xvsecctl -b -F -c 0x1 -D`` Description: Reads and prints MCAP Data Registers. :: [xilinx@]# sudo ./xvsecctl -b 0x08 -F 0x0 -c 0x1 -D MCAP version: 1 BYTE OFFSET Register Name Data Value ----------- ---------------- ---------- 0x001C FPGA Read Data[0] 0x00000000 0x0020 FPGA Read Data[1] 0x00000000 0x0024 FPGA Read Data[2] 0x00000000 0x0028 FPGA Read Data[3] 0x00000000 **5. Lists MCAP Register Contents** command: ``./xvsecctl -b -F -c 0x1 -d`` Description: It Dumps all the MCAP config Registers. :: [xilinx@]# ./xvsecctl -b 0x08 -F 0x0 -c 0x1 -d MCAP version: 1 BYTE OFFSET Register Name Data Value ----------- ---------------- ---------- 0x0000 Ext Capability 0x4801000B 0x0004 VSEC Header 0x02C10001 0x0008 FPGA JTAG ID 0x14B31093 0x000C FPGA BitStream Ver 0x00000000 0x0010 Status 0x00000004 bit 0 MCAP Error 0 bit 1 MCAP EOS 0 bit 4 MCAP Read Complete 0 bit 5:7 MCAP Read Count 0 bit 8 MCAP FIFO Overflow 0 bit 12:15 MCAP FIFO Occupancy 0 bit 24 Req for MCAP Release 0 0x0014 Control 0x00001000 bit 0 MCAP Enable 0 bit 1 MCAP Read Enable 0 bit 4 MCAP Reset 0 bit 5 MCAP Module Reset 0 bit 8 Req for MCAP by PCIe 0 bit 12 MCAP Design Switch 1 bit 16 Write Data Reg Enable 0 0x0018 FPGA Write Data 0x00000000 0x001C FPGA Read Data[0] 0x0000000B 0x0020 FPGA Read Data[1] 0x00000000 0x0024 FPGA Read Data[2] 0x00000000 0x0028 FPGA Read Data[3] 0x00000000 **6. Lists FPGA Config Reg Dump** command: ``./xvsecctl -b -F -c 0x1 -o`` Description: Reads and prints all FPGA Config Registers. :: [xilinx@]# ./xvsecctl -b 0x08 -F 0x0 -c 0x1 -o MCAP version: 1 FPGA CFG Registers Dump (see Configuration User Guide for more details) Register No Register Name Data Value ----------- ---------------- ---------- 0x0000 crc 0x00000000 0x0001 far 0x07FC0000 0x0002 fdri 0x00000000 0x0003 fdro 0x00000000 0x0004 cmd 0x00000000 0x0005 ctl0 0x00000401 0x0006 mask 0x00000000 0x0007 stat 0x109079FC 0x0008 lout 0x00000000 0x0009 cor0 0x38003FE5 0x000A mfwr 0x00000000 0x000B cbc 0x00000000 0x000C idcode 0x14B31093 0x000D axss 0x00000000 0x000E cor1 0x00400000 0x0010 wbstar 0x00000000 0x0011 timer 0x00000000 0x0014 scratchpad 0x00000000 0x0016 bootsts 0x00000001 0x0018 ctl1 0x00000000 0x001F bspi 0x0000000B **7. Access the MCAP Registers** command: ``./xvsecctl -b -F -c 0x1 -a [type [data]]`` Description: This command is used to read/write the MCAP config Register. **Parameters** : - MCAP register offset [type[data]]: - Write operation with data - b for byte data [8 bits] read - h for half word data [16 bits] read - w for word data [32 bits] read :: 1) Read MCAP register --------------------- [xilinx@]# ./xvsecctl -b 0x08 -F 0x0 -c 0x1 -a 0x4 w MCAP version: 1 [XVSEC] : xvsec_mcap_access_config_reg : read operation completed BYTE OFFSET Register Name Data Value ----------- ---------------- ---------- 0x0004 VSEC Header 0x02C10001 2) Write MCAP register ---------------------- [xilinx@]# ./xvsecctl -b 0x08 -F 0x0 -c 0x1 -a 0x14 w 0x10000 MCAP version: 1 [XVSEC] : xvsec_mcap_access_config_reg : write operation completed BYTE OFFSET Register Name Data Value ----------- ---------------- ---------- 0x0014 Control 0x00010000 **8. Access FPGA Config Registers** command: ``./xvsecctl -b -F -c 0x1 -s [w [data]]`` Description: This command is used to read/write the FPGA config Register. **Parameters** : - FPGA register offset [w [data]]: - Write operation with data - Read Operation if 'w' not given :: 1) Read FPGA config register ---------------------------- [xilinx@]# ./xvsecctl -b 0x08 -F 0x0 -c 0x1 -s 0x14 MCAP version: 1 [XVSEC] : xvsec_mcap_access_fpga_config_reg : read operation completed Register No Register Name Data Value ----------- ---------------- ---------- 0x0014 scratchpad 0x00000000 2) Write FPGA config register ---------------------------- [xilinx@]# ./xvsecctl -b 0x08 -F 0x0 -c 0x1 -s 0x14 w 0xDEADBEEF MCAP version: 1 In -s option [XVSEC] : xvsec_mcap_access_fpga_config_reg : write operation completed Register No Register Name Data Value ----------- ---------------- ---------- 0x0014 scratchpad 0xDEADBEEF **9. Program Stage 2 Bit-stream(.bin/.bit/.rbt)** command: ``./xvsecctl -b -F -c 0x1 -p `` Description: Programs Stage 2 Bitstream into FPGA. Supported file extentions are *.bin, *.bit, *.rbt. :: [xilinx@]# ./xvsecctl -b 0x08 -F 0x0 -c 0x1 -p Tul_Des03_tfu_update_region_partial.bit MCAP version: 1 [XVSEC] : xvsec_mcap_configure_fpga : Bitstream Program successful FPGA configuration successful **Versal MCAP Specific Options** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Design Requirements** ~~~~~~~~~~~~~~~~~~~~~~~ The capability to load reconfigurable, partial bitstreams for DFX regions in the PL or Stage 2 bitstreams to employ the Tandem PCIe boot methodology via the combined hardware and software solution of the Xilinx MCAP for Versal devices is carried over from Ultrascale/Ultrascale+ devices, but differs significantly from previous generations. While Ultrascale/Ultrascale+ devices had a dedicated connection to the configuration engine, Versal devices access the configuration engine via a generic connection to the NOC. This means that there are design requirements that must be followed to enable the MCAP feature for Versal devices and successfully use the MCAP VSEC software. For detailed information, refer to PG346 or PG347, but the design requirements are listed here for brevity. 1. Enable the MCAP capability and the “CPM to NOC” port via the CIPS GUI’s CPM module in the block design 2. Enable the “NOC to PMC” port via the CIPS GUI’s PS PMC module in the block design 3. Instantiate the AXI NOC IP and connect the CPM master to the PMC slave in the BD 4. Assume the CPM master connects to the AXI NOC’s S00_AXI port and the PMC slave connects to the AXI NOC’s M00_AXI port. Issue the following configuration TCL command. a. set_property CONFIG.REMAPS {M00_AXI {{0xF122_0000 0x1_0122_0000 64K} {0xF210_0000 0x1_0210_0000 64K}}} [get_bd_intf_pins /axi_noc_0/S00_AXI] 5. Using the IPI Address Editor tab, assign the pspmc_0_psv_pmc_slave_boot_stream and the pspmc_0_psv_pmc_slave_boot PMC slaves to the CPM master a. assign_bd_address -offset 0xF1220000 -range 0x00010000 -target_address_space [get_bd_addr_spaces versal_cips_0/CPM_PCIE_NOC_0] [get_bd_addr_segs versal_cips_0/NOC_PMC_AXI_0/pspmc_0_psv_pmc_slave_boot] -force b. assign_bd_address -offset 0xF2100000 -range 0x00010000 -target_address_space [get_bd_addr_spaces versal_cips_0/CPM_PCIE_NOC_0] [get_bd_addr_segs versal_cips_0/NOC_PMC_AXI_0/pspmc_0_psv_pmc_slave_boot_stream] -force **Example usage** ~~~~~~~~~~~~~~~~~ **1. MCAP Module Reset** command: ``./xvsecctl -b -F -c 0x1 -m`` Description: It Performs MCAP Module Reset. :: [xilinx@]# ./xvsecctl -b 0x01 -F 0 -c 1 -m MCAP version: 2 MCAP Module Reset Successful **2. Lists MCAP Register Contents** command: ``./xvsecctl -b -F -c 0x1 -d`` Description: It will print the contents of the MCAP Registers. :: [xilinx@]# ./xvsecctl -b 0x01 -F 0 -c 1 -d MCAP version: 2 BYTE OFFSET Register Name Data Value ----------- ---------------- ---------- 0x0000 Ext Capability 0x3A01000B 0x0004 VSEC Header 0x02020001 0x0008 Status 0x01800000 bit 5:4 MCAP Read/Write Status 0 bit 8 MCAP Read Complete 0 bit 20:16 MCAP FIFO Occupancy 0 bit 21 MCAP Write FIFO Full 0 bit 22 Write FIFO Almost Full 0 bit 23 Write FIFO Almost Empty 1 bit 24 MCAP Write FIFO Empty 1 bit 25 Write FIFO Overflow 0 0x000C Control 0x00000000 bit 0 MCAP Read Enable 0 bit 4 MCAP Write Enable 0 bit 5 MCAP 128-bit Mode 0 bit 8 MCAP Reset 0 bit 19:16 MCAP AXI Cache 0 bit 22:20 MCAP AXI Protect 0 0x0010 MCAP RW Adrr register 0x00000000 0x0014 MCAP Write Data 0x00000000 0x0018 MCAP Read Data 0x00000000 **3. PDI Download** command: ``./xvsecctl -b -F -c 0x1 -p mode <32b/128b> type
[tr_mode ] [sbi ]`` Description: This command is used to Download the specified File (.pdi) at given address. **Parameters** mode - <32b>: 32-bit mode should be used - <128b>: 128-bit mode should be used type - : Address is fixed - : Address should be incremented based on specified mode
- Address to be used for PDI download - PDI file to be downloaded [tr_mode ] - optional slow/fast download mode option for data transfer - If tr_mode is not specified, It will use Default(fast) mode [sbi ] - Slave Boot Interface register address, If the target is an SBI device :: 1) Slow mode example: 32b, incr mode with DDR at address 0x0 ------------------------------------------------------------ [xilinx@]# ./xvsecctl -b 0x01 -F 0x0 -c 0x1 -p mode 32b type incr 0x0 ./design_routed_tandem_off_rp_1_partial.pdi tr_mode slow MCAP version: 2 tr_mode: 0 [XVSEC] : xvsec_mcap_file_download : File Download successful File Download successful 2) Fast mode example: 128b, incr mode with DDR at address 0x0 ------------------------------------------------------------- [xilinx@]# ./xvsecctl -b 0x01 -F 0x0 -c 0x1 -p mode 128b type incr 0x0 ./design_routed_tandem_off_rp_1_partial.pdi tr_mode fast MCAP version: 2 tr_mode: 1 [XVSEC] : xvsec_mcap_file_download : File Download successful File Download successful 3) Slow mode example: 128b, fixed mode with SBI fixed address 0xF2100000 ------------------------------------------------------------------------ [xilinx@]# ./xvsecctl -b 0x01 -F 0x0 -c 0x1 -p mode 128b type fixed 0xF2100000 ./design_routed_tandem_off_rp_1_partial.pdi tr_mode slow MCAP version: 2 tr_mode: 1 [XVSEC] : xvsec_mcap_file_download : File Download successful File Download successful 4) SBI register example: 128b, fixed mode with SBI fixed address 0xF2100000 and SBI register address 0x1220000 ----------------------------------------------------------------------------------------------------------- [xilinx@]# ./xvsecctl -b 0x01 -F 0x0 -c 0x1 -p mode 128b type fixed 0xF2100000 ./design_routed_tandem_off_rp_1_partial.pdi tr_mode slow sbi 0x1220000 MCAP version: 2 tr_mode: 1 [XVSEC] : xvsec_mcap_file_download : File Download successful **4. PDI Upload** command: ``./xvsecctl -b -F -c 0x1 -t type
`` Description: It Reads the contents at given address for the given length into given file **Parameters** type - : Address is fixed - : Address should be incremented based on specified mode
- Address to Read the contents - Number of bytes to read - Read the contents and save in given file :: 1) PDI upload with incr mode and DDR at address 0x0 ------------------------------------------------------------ [xilinx@]# ./xvsecctl -b 0x01 -F 0 -c 1 -t type incr 0x0 843312 ./read_from_ddr_32bit_incr.pdi MCAP version: 2 [XVSEC] : xvsec_mcap_file_upload : File Upload successful File Upload successful **5. Access MCAP Register** command: ``./xvsecctl -b -F -c 0x1 -a `` Description: This command is used to read/write the MCAP config Register. **Parameters** : - MCAP register offset [type[data]]: - Write operation with data - b for byte data [8 bits] read - h for half word data [16 bits] read - w for word data [32 bits] read :: 1) Read MCAP register --------------------- [xilinx@]# ./xvsecctl -b 0x01 -F 0 -c 1 -a 0xc w MCAP version: 2 [XVSEC] : xvsec_mcap_access_config_reg : read operation completed BYTE OFFSET Register Name Data Value ----------- ---------------- ---------- 0x000C Control 0x00000000 2) Write MCAP register ---------------------- [xilinx@]# ./xvsecctl -b 0x01 -F 0 -c 1 -a 0xc w 0x0010 MCAP version: 2 [XVSEC] : xvsec_mcap_access_config_reg : write operation completed BYTE OFFSET Register Name Data Value ----------- ---------------- ---------- 0x000C Control 0x00000010 **6. Access the AXI Registers** command: ``./xvsecctl -b -F -c 0x1 -x mode <32b/128b>
w `` Description: This command is used to read/write the 32b/128b AXI addresses. **Parameters** mode - <32b>: 32-bit mode should be used - <128b>: 128-bit mode should be used - Mode is Not valid for Read Operation
- Address to be used for PDI download [w [data]] - Write operation with data - Read Operation if 'w' not given :: 1) 32bit AXI read ----------------- [xilinx@]# ./xvsecctl -b 0x01 -F 0 -c 1 -x 0xf11a0008 MCAP version: 2 [XVSEC] : xvsec_mcap_access_axi_reg : read operation completed axi address: Data Value ------------ ---------- 0xF11A0008: 0x00000000 2) 32-bit AXI write ------------------- [xilinx@]# ./xvsecctl -b 0x01 -F 0 -c 1 -x mode 32b 0xf11a0008 w 0x00302021 MCAP version: 2 [XVSEC] : xvsec_mcap_access_axi_reg : write operation completed axi address: Data Value ------------ ---------- 0xF11A0008: 0x00302021 3) 128b AXI write ----------------- [xilinx@]# ./xvsecctl -b 0x01 -F 0 -c 1 -x mode 128b 0x0 w 0xA0000000 0xB1000000 0xC2000000 0xF10000FF MCAP version: 2 [XVSEC] : xvsec_mcap_access_axi_reg : write operation completed axi address: Data Value ------------ ---------- 0x00000000: 0xA0000000 0x00000004: 0xB1000000 0x00000008: 0xC2000000 0x0000000C: 0xF10000FF **7. To set AXI cache and protection settings** command: ``./xvsecctl -b -F -c 0x1 [axi_cache axi_prot ]`` Description: It will configure the AXI cache and protections bits. **Parameters** [axi_cache ] - axi_cache valid range 0 to 15 [axi_prot ] - axi_prot valid range 0 to 7 :: [xilinx@]# ./xvsecctl -b 0x01 -F 0 -c 1 -q axi_cache 0x1 axi_prot 0x2 MCAP version: 2 axi_cache: 0x1 axi_prot: 0x2