This Page lets the user understand how to use ACAP Cockpit.

Table of Contents

Introduction

ACAP Cockpit Console provides the ability to configure any register of Versal modules (AM012 Versal Register Reference v1.2). It is a handy tool that monitors the health of the register configuration and registers can be configured on the fly.
User can dynamically modify the register configuration (if needed as per the register privileges), reduces time for debugging the system configuration issues, reports registers details.
It also provides user friendly view to monitor the Versal clocking and reset configuration

ACAP Cockpit can be opened from BEAM Tool’s “Run Demos & Designs” screen. ACAP Cockpit opens in a new tab of the browser when clicked on the “Run” button which appears below 'ACAP Cockpit' widget. Please follow steps here to launch BEAM Tool

There are several ACAP Cockpit features contained in the following sections

• ACAP Cockpit Scope

• Board Details

• Menu options in ACAP Cockpit

ACAP Cockpit Scope

ACAP Cockpit is consolidated Versal Console displaying different GUI's of:

• Register configuration and control

• Memory/Register watcher

• Clock/Reset details of Versal

• User Dashboard

Board Details

When user tries to access ACAP cockpit, the tool internally connects to board via JTAG, and when finished returns JTAG control. User can see the board details by placing the mouse on the connected username which is displayed on the top right corner of the application as shown in below video.
ACAP Cockpit will provide a notification about the Ref clock of the board.

ACAP Cockpit reads memory locations using ‘mrd' command. By default, accesses to reserved and invalid address ranges are blocked. In order to overwrite access protection it uses ‘-force’ option.

With Force memory read enabled (mrd -force <address>), accessing a memory location which is not part of design programmed will result in ‘DAP Error’ and closes JTAG. It forces user to power cycle the board and program design again.

With Force memory read disabled (mrd <address>), accessing a memory location which is not part of design programmed will return 'Memory Read error' and user can continue using JTAG. By Default Force memory Read is enabled in ACAP Cockpit.

ACAP Cockpit provides a pop-up to display the board ref clock and a switch to configure “Force Memory Read“ option, User can access this pop-up by clicking on the option called "Board Details" which is available by clicking on the connected username that displayed on the top right corner of the application. User can make the choice of read/write the registers with and without -force option by toggling the "Force Memory Read" switch as shown in the below video. More details on ‘Force Memory Read” is available with 'mrd’ command of XSDB.

When user turns on this option the following command will be executed on XSDB. This will force reading registers. (Similar to ‘mrd -force’ command on XSDB)

When user turns off this option the following command will be executed on XSDB. This will not force reading registers. (Similar to 'mrd' command on XSDB)

Program Versal

ACAP cockpit allows user to program the design which is equivalent to “device program” command in xsdb. User has to click on ‘Program Versal' option which is available on top right corner menu, this will open a dialog. User has to select the ‘User Design’ option and enter the design path which should be accessible by xsdb (i.e system controller path) and click on ‘Program Versal’ button. This will program the design in xsdb internally. If you face any issue while programming PDI please click on 'Reset Versal’ button and try again.
Note: This feature is available only with the boards released as part of system controller release 2022.2 and later. Also please make sure that active boot mode is JTAG while programming the PDI

Open

Open

Menu options in ACAP Cockpit

The ACAP Cockpit offers 4 menu options that are conveniently located on the left side of the GUI.
These are (from top to bottom)

Each view is explained in-detail in the coming sections.

Register Reference

Versal ACAP

• Versal ACAP registers are available on ACAP Cockpit. Register Reference tab lists all the Versal ACAP registers of all the modules.

• All the modules are displayed along with their "Base Address" and "Description". By default, all the modules are sorted by the "Base Address".

• Register database is displayed in pages with 25 rows in each page and the count is configurable with a selection at the bottom of the page as shown below

• Register Reference tab provides an option to search for modules/registers using "Module Name", "Base Address"

• All registers from Versal ACAP can be downloaded by clicking on "DOWNLOAD" button. User can download the registers in "ZIP" and "TCL" format based on their choice
  ZIP - A zip file with a tcl for each module.
  TCL - A consolidated tcl file for all the modules.

• All Registers from Versal ACAP can be refreshed by clicking on "REFRESH ALL" button. (highlighted below in black)

• This feature will take around 18 mins in order to read all the versal ACAP registers.

• As this feature reads all memory locations of versal ACAP, the targets may go into bad state if any memory location is not part of the PDI programmed. In such scenario please reset versal from Reset Versal feature which is available under Program Versal to continue using cockpit

• Registers from a specific module can be downloaded by clicking on download icon available against the module in the table row

• By clicking on Refresh icon, all register values under the module are refreshed and the page is re-directed to register home page
  ex: if CFU_CSR is refreshed by clicking on Refresh icon then the page is redirected to CFU_CSR register list page  as shown below

• If "Live Value" of a register is not same as its "Reset Value", then "Live Value" of that register is displayed in Amber color

• Click on a module name (ex. APU_DUAL_CSR) to see register list

• To read the live value of a register, click on refresh icon against the register

• If the register is permitted to write, user can write into register by providing the value in the input field under update column and click on pen icon

• Registers with access type as "ro" or "RO" (read only) are not allowed to update its value

• To write the values into multiple registers of their choice at a single shot, user can provide the value across each register and click on "WRITE ALL" button

• To write a specific value into all registers , provide the value in "Write to all registers" input field and click on edit icon beside the input field

• Click on "DOWNLOAD" button, to download table information (register information) into csv format

• Click on "REFRESH" button will read all registers live value

• Click on a register to see the bit fields

• Reserved bit-fields are highlighted in gray color

• Bit fields with access type as "ro" or "RO" are not allowed to update

XSearch

• In XSearch, we can search for any register or any module using Module Name/Address, Register Name/Address and Bit-field name

• For Example, to search all CFRM registers in CFRAME0_REG Module, simply search by "CFRM" in "Register Name" field and " CFRAME0_REG" in "Module Name" field

• Search rules are as follows:

  • To search any module:

    • Input Exact module name (case insensitive)

    • Input any start phrase of module followed by * . It will find all module which starts with that phrase in their name. (ex: CFRAME*)

    • Input any middle phrase of module by prefixing * and postfix * to that phrase . It will find all module which contain that phrase in their name. (ex: *FRAME* )

    • Input any end phrase of module with a prefix of *. It will find all modules that ends with that phrase in their name (ex: *_REG )

  • To search any register:

    • To get registers from a particular module set, use above module filter. (Optional)

    • User can search multiple registers by providing register names separated by commas

    • All phrase search rules are applied just like in module filter

  • To search any bit-fields:

    • To get bit-fields from a particular module set, use above module and register filter. (Optional)

    • User can search multiple bit-fields by providing bit-field names separated by commas

    • All phrase search rules are applied just like in module filter

System Debugger

Debugger

• Debugger Terminal is like Xilinx System Debugger (XSDB). All commands supported by XSDB can be executed through Debugger Terminal

• After writing a command in command line press enter or click on "SEND" button to execute the command. To clear the command line input, click on "CLEAR" button

• Series of commands can also be executed by uploading a file through upload button. Files of .tcl and .xregv are supported. All commands supported by XSDB are supported here as per the XSDB syntax.
  Please go through below file for reference

• A progress bar will be displayed while the file is being uploaded. Upload can be cancelled by clicking on cancel button

• Debugger stores history of commands executed. User can retrieve the previous commands by having focus in the command line input box and by clicking on upward arrow key from the keyboard

• To clear the console of debugger terminal, click on close button as shown below

SysAddress Watch

• Any address in the Versal ACAP can be monitored through SysAddress Watch tab

• Any number of addresses can be monitored at a given time. When user is in SysAddress Watch tab, ACAP Cockpit continuously reads the address and auto updates the data in GUI

• By clicking on "DOWNLOAD" button, user can download the register addresses and its values which are displayed in table

• To stop a watch, click on "STOP" button. (Highlighted in yellow)

• If user wants to monitor multiple address of their choice, then they can list the address in tcl file and upload them using "Upload File" option highlighted in green as shown below

• Please go through below file for reference

Open

System Monitor

Clocks

• User can view all PS/PMC, CPM clocks and resets related information here

Clock Table

• In clock table, it will display selected PLL, divider, target frequency, and the actual frequency for PS/PMC and CPM modules in respective tabs

• By clicking on "DOWNLOAD" button user can download the clock frequency details that are displayed in the table

• Naming convention used for clocking registers are as follows: <module_name>_<clocking_registers_name>

• Clock Enable field indicates that respective clock is enabled or disabled

Clock Tree

• It will show clock frequency values and also displays all available PLL clock Hierarchy. The default value used for reference clock is 33.33 MHz.

Updating Reference clocks

• User can change clock frequency by editing ref clock. It automatically will update all respective clock frequency on GUI. But it will not do any update on board.

• If reference clock is updated on the board, make sure you update the value in ACAP Cockpit (as shown in below video)

• On change a popup will prompt for user permission. Click on "Ok" to impact change

Note: The change in clock value is specific to the tab. For Example, if user changes the reference clock in PS then only PS clock tree frequencies are calculated based on the new value.

• By clicking on "REFRESH" button will again read live clock frequency for all available PLL

• APLL

• NPLL 

• PPLL 

• RPLL 

Reset

• In Reset table we read live value from Board for all reset registers of CRL, CRF and CRP module. And do compare with reset value, if it's match then live value will display in Black else it will display in Amber color

• By clicking on "DOWNLOAD" button will start downloading the table content

User Dashboard

Debugger

• User can read/write any register by name/address. Format to read/write any register is provided in help command

• By clicking on "EXECUTE"/Enter, the command gets executed

• User can upload any valid text file with multiple read/write by clicking on "Upload Files". Please go through below file for reference

Open

• "help" command will list all supported formats

• "read help" command will list all supported read formats

• "write help" command will list all supported write formats

• "clear/cls" will clear the debugger screen

Plot

• User can plot any register by name/address

• Max 8 plot can be configured at a time. Number of plots can be selected from dropdown

• To know more about plot, please place the mouse over the info icon

• By clicking on "GENERATE" button, the graph will be displayed with the requested parameters

• To stop monitor the graphs, please click on "CLOSE" button

FAQ

Version History

1. Latest version - Beta release – September 2021

   1. Initial release of ACAP Cockpit

Related Links

• User Guide - Link to be updated once User guide is available on xilinx.com

• VCK190 Product Page - https://www.xilinx.com/products/boards-and-kits/vck190.html

• VMK180 Product Page - https://www.xilinx.com/products/boards-and-kits/vmk180.html

• VPK120 Product Page - https://www.xilinx.com/products/boards-and-kits/vpk120.html

• VPK180 Product Page -

• VHK158 Product Page -

• VEK280 Product Page -