.. _xbtools_map.rst:

..
   comment:: SPDX-License-Identifier: Apache-2.0
   comment:: Copyright (C) 2019-2021 Xilinx, Inc. All rights reserved.

Utility Migration Guide 
***********************

This document maps the legacy ``xbutil``/``xbmgmt`` commands to the new ``xbutil``/``xbmgmt`` commands. It lists out the new ``xbutil``/``xbmgmt`` calls that replace the existing calls. A few points: 

 1) The new utilities are complete redesign and architecture, hence there may not be exact 1-to-1 mapping. 
 2) The help menus (``--help``) of these new utilities have also been improved and are highly descriptive with regards to both the commands and options. Please refer to them as needed.
 3) The new command opions have both short and long format, for example ``-d`` or ``--device``. In the table below, only the longer option format is used.

You may refer the documentation of the new tools in the following links :doc:`xbutil` and :doc:`xbmgmt` . 

xbutil
~~~~~~

+------------+-------------+-------------------+----------------------+
|Subcommand  | Subcommand  |Option             |Option                |
|Legacy      | New         |Legacy             |New                   |
+============+=============+===================+======================+
|            |             |                   |                      |
|``help``    |``--help``   |                   |                      |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|``version`` |``--version``|                   |                      | 
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|``reset``   |``reset``	   |``-d <bdf>``       |``--device <bdf>``    |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|``validate``|``validate`` |``-d <bdf>``       |``--device <bdf>``    |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|            |             |``-q``             |``--run quick``       |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|            |             |      	       |``--run <testname>``  |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|            |             |      	       |``--format <type>``   |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|            |             |     	       |``--output <file>``   |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|``scan``    |``examine``  |                   |                      |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|``query``   |``examine``  |``-d <bdf>``       |``--device <bdf>``    |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|            |             |                   |``--report <list>``   |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|            |             |                   |``--output <file>``   |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|``dump``    |``examine``  |                   |``--format <type>``   |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|``program`` |``program``  |``-d <bdf>``       |``--device <bdf>``    |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|``dmatest`` |``validate`` |``-d <bdf>``       |``--device <bdf>``    |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|            |             |                   |    ``--run DMA``     |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|            |             |``-b <blksize kb>``|    n/a               |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|            |             |``-p <xclbin>``    |``--user <xclbin>``   |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|``host_mem``|``configure``| ``-d <bdf>``      | ``--device <bdf>``   |
|            |             |                   |            	      |
+------------+-------------+-------------------+----------------------+
|            |             |``--enable``       |``--host-mem enable`` |
|            |             |``--size <sz>``    |``--size <sz>``       |
|            |             |                   |            	      |
+------------+-------------+-------------------+----------------------+
|            |             |``--disable``      |``--host-mem disable``|
|            |             |                   |                      |
|            |             |                   |             	      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|``p2p``     |``configure``| ``-d <bdf>``      | ``--device <bdf>``   |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|            |             | ``--enable``      | ``--p2p enable``     |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|            |             | ``--disable``     | ``--p2p disable``    |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|            |             |                   | ``--p2p validate``   |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
| ``mem``    |             | ``--read``        |   Not Supported      |
|            |             | ``--write``       |                      |  
+------------+-------------+-------------------+----------------------+
|            |                                                        |
| ``top``    |          separate ``xbtop`` command                    |
|            |                                                        |  
+------------+-------------+-------------------+----------------------+



xbmgmt
~~~~~~

+-------------+-------------+---------------------------+----------------------------------+
|Subcommand   | Subcommand  |Option                     |Option                            |
|Legacy       | New         |Legacy                     |New                               |
+=============+=============+===========================+==================================+
|             |             |                           |                                  |
|``help``     |``--help``   |                           |                                  |
|             |             |                           |                                  |
+-------------+-------------+---------------------------+----------------------------------+
|             |             |                           |                                  |
|``version``  |``--version``|                           |                                  |
|             |             |                           |                                  |
+-------------+-------------+---------------------------+----------------------------------+
|             |             |                           |                                  |
|``flash``    |``program``  |``-d <bdf>``               |``--device <bdf>``                |
|             |             |                           |                                  |
+-------------+-------------+---------------------------+----------------------------------+
|             |             |                           |                                  |
|             |             |``--update``	        |``--base``	                   |    	
|             |             |                           |                                  |
+-------------+-------------+---------------------------+----------------------------------+
|             |             |                           |                                  |
|             |             |``--update --shell <name>``|``--base --image <name w/ path>`` |
|             |             |                           |	   	                   |
+-------------+-------------+---------------------------+----------------------------------+
|             |             |                           |                                  | 
|             |             |``--factory_reset``        |``--revert-to-golden``            |
|             |             |                           |                                  |
+-------------+-------------+---------------------------+----------------------------------+
|             |             |                           |                                  | 
|``partition``|``program``  |``--card <bdf>``           |``--device <bdf>``                |	
|             |             |                           |                                  |
+-------------+-------------+---------------------------+----------------------------------+
|             |             |                           |                                  | 
|             |             |``--program``              |``--shell <shell-file w/ path>``  |	
|             |             |``--name <shell name>``    |                                  |
|             |             |                           |                                  |
+-------------+-------------+---------------------------+----------------------------------+
|             |             |                           |                                  | 
|             |             |``--path <xclbin w/ path>``|``--user <xclbin w/ path>``       |	
|             |             |                           |                                  |
+-------------+-------------+---------------------------+----------------------------------+
|             |             |                           |                                  |    
|``scan``     |``examine``  |                           |``--report host``                 |
|             |             |                           |                                  |
+-------------+-------------+---------------------------+----------------------------------+
|             |             |                           |                                  |    
|	      |``examine``  |                           |``--device <bdf>``                |
|             |             |                           |                                  |
+-------------+-------------+---------------------------+----------------------------------+
|             |             |                           |                                  | 
|             |             |     	                |``--report <list>``               |	
|             |             |                           |                                  |
+-------------+-------------+---------------------------+----------------------------------+
|             |             |                           |                                  | 
|             |             |      	                |``--format <type>``               |
|             |             |                           |                                  |
+-------------+-------------+---------------------------+----------------------------------+
|             |             |                           |                                  |
|             |             |     	                |``--output <file>``               |
|             |             |                           |                                  |
+-------------+-------------+---------------------------+----------------------------------+
|             |             |                           |                                  |    
|``reset``    |``reset``    |``-d <bdf>``               |``--device <bdf>``                |
|             |             |                           |                                  |
+-------------+-------------+---------------------------+----------------------------------+
|             |             |                           |                                  |    
|``config``   |             |``--enable_retention``     | To be implemented in next release|
|             |             |                           |                                  |
|             |             |``--disable_retention``    |                                  |
|             |             |                           |                                  |
+-------------+-------------+---------------------------+----------------------------------+



Few examples of legacy vs new commands 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Here are few example use-cases of legacy vs new commands

**1. Getting all the information obtained from the userspace kernel driver**

**Legacy command**

There were two variants of legacy commands

.. code-block:: shell

       xbutil query  
       
or 

.. code-block:: shell

       xbutil dump


**New command**

.. code-block:: shell

       xbutil examine --device 0000:b3:00.1 --report all

**2. Validate the card**

**Legacy command**

.. code-block:: shell

        xbutil validate 
        
**New command**

.. code-block:: shell
 
        xbutil validate --device 0000:b3:00.1
        
**3. Obtaining platform information such as SC version, flashed partition(s) running on the card, etc.** 

**Legacy command**

.. code-block:: shell

   xbmgmt  flash --scan
   
**New command**

.. code-block:: shell

   xbmgmt examine --device 0000:b3:00.0 --report platform 
   
   
You need to use a combination of ``xball xbmgmt`` command if you prefer to see information from all the cards attached to the host server. Please see ``xball`` page for more details. 
   
**4. Programming the base partition**

**Legacy command**

.. code-block:: shell

   xbmgmt --update --shell <partition name>
   
**New command**

.. code-block:: shell

   xbmgmt program --base --device 0000:d8:00.0 --base 
   
or when a specific partition to choose

.. code-block:: shell

   xbmgmt program --base --device 0000:d8:00.0 --base --image <partition name> 

**5. Resetting the device**

**Legacy command**

.. code-block:: shell

   xbutil --reset 
   
**New command**

.. code-block:: shell

   xbutil --reset --device 0000:d8:00.1