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 User Application 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 <bus_no> -F <dev_no> -l

Parameters

b <bus_no>:

  • Specify PCI bus no on which device sits

F <dev_no>:

  • 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 <bus_no> -F <dev_no> -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 <bus_no> -F <dev_no> -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 <bus_no> -F <dev_no> -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 <bus_no> -F <dev_no> -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 <bus_no> -F <dev_no> -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 <bus_no> -F <dev_no> -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 <bus_no> -F <dev_no> -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 <bus_no> -F <dev_no> -c 0x1 -a <byte offset> [type [data]]

Description: This command is used to read/write the MCAP config Register.

Parameters

<byte offset>:

  • 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 <bus_no> -F <dev_no> -c 0x1 -s <register no> [w [data]]

Description: This command is used to read/write the FPGA config Register.

Parameters

<register no>:

  • 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 <bus_no> -F <dev_no> -c 0x1 -p <file>

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.

    1. 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

    1. 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

    2. 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 <bus_no> -F <dev_no> -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 <bus_no> -F <dev_no> -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 <bus_no> -F <dev_no> -c 0x1 -p mode <32b/128b> type <fixed/incr> <Address> <PDI File> [tr_mode <slow/fast>] [sbi <SBI reg block addr>]

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

  • <fixed>: Address is fixed

  • <incr>: Address should be incremented based on specified mode

<Address>

  • Address to be used for PDI download

<PDI File>

  • 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 <bus_no> -F <dev_no> -c 0x1 -t type <fixed/incr> <Address> <Length_2_Read> <PDI File>

Description: It Reads the contents at given address for the given length into given file

Parameters

type

  • <fixed>: Address is fixed

  • <incr>: Address should be incremented based on specified mode

<Address>

  • Address to Read the contents

<Length_2_Read>

  • Number of bytes to read

<PDI File>

  • 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 <bus_no> -F <dev_no> -c 0x1 -a <Reg Offset> <b/h/w> <Data>

Description: This command is used to read/write the MCAP config Register.

Parameters

<byte offset>:

  • 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 <bus_no> -F <dev_no> -c 0x1 -x mode <32b/128b> <address> w <data>

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>

  • 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 <bus_no> -F <dev_no> -c 0x1 [axi_cache <data> axi_prot <data>]

Description: It will configure the AXI cache and protections bits.

Parameters

[axi_cache <data>]

  • axi_cache valid range 0 to 15

[axi_prot <data>]

  • 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