.. _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>``    |
|            |             |                   |                      |
+------------+-------------+-------------------+----------------------+
|            |             |                   |                      |
|            |             |``-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``       |                      |  
+------------+-------------+-------------------+----------------------+



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``    |                                  |
|             |             |                           |                                  |
+-------------+-------------+---------------------------+----------------------------------+