1.. _board_inspector_tool:
2
3Board Inspector Tool
4####################
5
6This guide describes all features and uses of the tool.
7
8About the Board Inspector Tool
9******************************
10
11The Board Inspector tool ``board_inspector.py`` enables you to generate a board
12configuration file on the target system. The board configuration file stores
13hardware-specific information extracted from the target platform and is used to
14customize your :ref:`ACRN configuration <acrn_configuration_tool>`.
15
16Prerequisites
17*************
18
19This guide assumes you have set up your target system and successfully launched
20the Board Inspector. For steps, see the following Getting Started Guide
21sections:
22
23* :ref:`gsg-dev-computer`
24* :ref:`gsg-board-setup`
25
26Generate a Board Configuration File
27***********************************
28
29.. important::
30
31   Whenever you change the configuration of the board, such as peripherals, BIOS
32   settings, additional memory, USB devices, or PCI devices, you must generate a
33   new board configuration file.
34
35The following steps describe all options in the Board Inspector for generating
36a board configuration file.
37
38#. Run the Board Inspector tool (``board_inspector.py``) to generate the board
39   configuration file. This example assumes the tool is in the
40   ``~/acrn-work/`` directory and ``my_board`` is the desired file
41   name. Feel free to modify the commands as needed.
42
43   .. code-block:: bash
44
45      cd ~/acrn-work
46      sudo board_inspector.py my_board
47
48#. Confirm that the board configuration file ``my_board.xml`` was generated in
49   the current directory.
50
51.. _board_inspector_cl:
52
53Command-Line Options
54********************
55
56You can configure the Board Inspector via command-line options. Running the
57Board Inspector with the ``-h`` option yields the following usage message:
58
59.. code-block::
60
61   usage: board_inspector.py [-h] [--out OUT] [--basic] [--loglevel LOGLEVEL]
62                             [--check-device-status]
63                             [--add-llc-cat <capacity_mask_length:int>,<clos_number:int>,<has_CDP:bool>]
64                             board_name
65
66   positional arguments:
67     board_name            the name of the board that runs the ACRN hypervisor
68
69   optional arguments:
70     -h, --help            show this help message and exit
71     --out OUT             the name of board info file
72     --basic               do not extract advanced information such as ACPI
73                           namespace
74     --loglevel LOGLEVEL   choose log level, e.g. debug, info, warning, error or
75                           critical
76     --check-device-status
77                           filter out devices whose _STA object evaluates to 0
78     --add-llc-cat <capacity_mask_length:int>,<clos_number:int>,<has_CDP:bool>
79                           manually set the Cache Allocation Technology
80                           capability of the last level cache
81
82Details about certain arguments:
83
84.. list-table::
85   :widths: 33 77
86   :header-rows: 1
87
88   * - Argument
89     - Details
90
91   * - ``board_name``
92     - Required. The board name is used as the file name of the board
93       configuration file and is placed inside the file for other tools to read.
94
95   * - ``--out``
96     - Optional. Specify a file path where the board configuration file will be
97       saved (example: ``~/acrn_work``). If only a filename is provided in this
98       option, the Board Inspector will generate the file in the current
99       directory.
100
101   * - ``--basic``
102     - Optional. By default, the Board Inspector parses the ACPI namespace when
103       generating board configuration files. This option provides a way to
104       disable ACPI namespace parsing in case the parsing blocks the generation
105       of board configuration files.
106
107   * - ``--loglevel``
108     - Optional. Choose the log level. (Default is warning.)
109
110   * - ``--check-device-status``
111     - Optional. On some boards, the device status (reported by the _STA
112       object) returns 0 while the device object is still useful for
113       pass-through devices. By default, the Board Inspector includes the
114       devices in the board configuration file. This option filters out the
115       devices, so that they cannot be used.
116
117   * - ``--add-llc-cat``
118     - Optional. Add the Cache Allocation Technology (CAT) capabilities of the
119       last level cache (LLC) to the generated board configuration file even
120       when the hardware does not report them for any reason. For example,
121       ``--add-llc-cat=12,16,y``. CDP (Code and Data Prioritization) performance
122       feature enables separate control over code and data placement in the
123       processor's cache. Valid values for ``bool`` are
124       ``true|false|y|n|yes|no``.
125