win/doc: document idd-setup-tool

Signed-off-by: Dmitry Rogozhkin <dmitry.v.rogozhkin@intel.com>

sources/apps/idd-setup-tool/readme.rst

@@ -0,0 +1,297 @@
+IDD Setup Tool
+==============
+
+.. contents::
+
+.. _IDD: ../../drivers/idd
+
+.. |intel-flex| replace:: Intel® Data Center GPU Flex Series
+.. _intel-flex: https://ark.intel.com/content/www/us/en/ark/products/series/230021/intel-data-center-gpu-flex-series.html
+
+idd-setup-tool is a tool to install, uninstall and tune virtual `IDD`_ devices
+and displays. Tool supports the following commands:
+
++--------------+--------------+--------------+
+| `install`_   | `uninstall`_ | `set`_       |
++--------------+--------------+--------------+
+| `enable`_    | `disable`_   | `pair`_      |
++--------------+--------------+--------------+
+| `rearrange`_ | `show`_      |              |
++--------------+--------------+--------------+
+
+**NOTE:** Some of the commands do not work under non-interactive shells,
+specifically - `install`_ and `set`_.
+
+Some commands allow to select displays/adapters with patterns. Overall,
+supported patterns are:
+
++----------------+--------------------------------------------------------------+
+| Pattern        | Mapping                                                      |
++================+==============================================================+
+| ``msft``       | Microsoft Basic Adapter or Display                           |
++----------------+--------------------------------------------------------------+
+| ``virtio``     | Red Hat VirtIO GPU DOD controller and Red Hat QXL controller |
++----------------+--------------------------------------------------------------+
+| ``flex``       | |intel-flex|_ adapter                                        |
++----------------+--------------------------------------------------------------+
+| ``non-flex``   | All except |intel-flex|_ adapter                             |
++----------------+--------------------------------------------------------------+
+| ``idd``        | `IDD`_ device or display                                     |
++----------------+--------------------------------------------------------------+
+| ``non-idd``    | All except `IDD`_ device or display                          |
++----------------+--------------------------------------------------------------+
+| ``<pattern>N`` | All except `IDD`_ device or display                          |
++----------------+--------------------------------------------------------------+
+
+Some commands additionally support selecting specific adapter/display if few
+adapters/displays of the same type present on the system. In this case use
+``<pattern>N``, for example ``idd1``.
+
+Global options
+--------------
+
+Overall usage for the tool is the following::
+
+  idd-setup-tool.exe <command> [<options>] [<global-options>]
+
+The followin options apply to all commands supported by the tool.
+
+-h, --help
+    Print help
+
+-v, --verbose
+    Turn on additional logging (default: off)
+
+-y, --yes
+    Assume "yes" on all prompts (default: off)
+
+--delay=<milliseconds>
+    Applies the specified delay (in milliseconds) after every action that
+    changes display or adapter states (default: ``2000ms``)
+
+Command Reference
+-----------------
+
+install
+~~~~~~~
+
+Usage::
+
+  idd-setup-tool.exe install [<options>] [<global-options>]
+
+This command installs `IDD`_ display for each IDD compatible adapter
+available on the system. Compatible adapters are:
+
+* |intel-flex|_
+
+If IDD driver is not signed installation will fail. You either need
+to sign the driver (which is not covered here) or enable Windows test
+mode with the following command (run from cmd shell as Administrator)::
+
+  bcdedit /set testsigning on
+
+After reboot you should be able to install the driver. Command will first
+uninstall any previously installed IDD displays. After installing IDD device
+and its driver it will be paired with the IDD compatible adapter. If few
+compatible adapters present on the system, command will install respective
+number of IDD displays.
+
+Using ``--resolution`` and ``--scale`` options you can configure IDD display
+resolution and scaling respectively.
+
+Using ``--disable-adapter`` and ``--disable-display`` you can disable specific
+adapters or displays specified by the pattern. These options are useful to
+disable non-idd adapters or displays such as Microsoft Basic Adapter.
+
+Examples:
+
+* Install `IDD`_ display(s) with 1080p resolution and 100% scaling and disable
+  Microsoft Basic Display and Adapter::
+
+    idd-setup-tool.exe install -y --trust ^
+      --resolution=1920x1080 --scale=100 --rearrange ^
+      --disable-adapter=msft --disable-display=msft
+
+Options:
+
+--disable-adapter=<VALUE,VALUE,...>
+    Disable specified adapter (options: ``msft``, ``idd``, ``flex``)
+
+--disable-display=<VALUE,VALUE,...>
+    Disable specified display (options: ``non-flex``, ``msft``,
+    ``idd``, ``virtio``, ``non-idd``)
+
+--location=</path/to/idd>
+    Location of IDD driver (.inf, .cat, .dll) to install (default:
+    ``idd`` folder relative to idd-setup-tool executable)
+
+--rearrange
+    Rearrange displays horizontally, set leftmost as primary
+
+--resolution=<WxH>
+    Configure specified resolution for the display (default: use system
+    default)
+
+--scale=<SCALE%>
+    Configure specified scaling for the display (default: use system
+    default)
+
+--trust
+    Extract IDD certificate (from IDD driver .cat file) and add it to the
+    trustred store. That's not being done by default.
+
+install bugs
+^^^^^^^^^^^^
+
+* This command requires interactive shell to work properly.
+
+* Pairing of IDD display with physical adapters does not preserve over reboot.
+  To workaround the issue rerun the pairing with the following command::
+
+    idd-setup-tool.exe pair
+
+uninstall
+~~~~~~~~~
+
+Usage::
+
+  idd-setup-tool.exe uninstall [<options>] [<global-options>]
+
+Command uninstalls `IDD`_ device and display. Optionally command enables
+adapters and displays which were explicitly switched off.
+
+Options:
+
+--enable-adapter=<VALUE,VALUE,...>
+    Enable specified adapter (options: ``msft``, ``idd``)
+
+--enable-display=<VALUE,VALUE,...>
+    Enable specified display (options: ``msft``, ``idd``, ``virtio``,
+    ``non-idd``)
+
+The following is IDD setup tool recommended usage for ``uninstall`` command:
+
+set
+~~~
+
+Usage::
+
+  idd-setup-tool.exe set <settings>... [<global-options>]
+
+This command applies specified settings to displays available on the system.
+Execute this command few times with different settings if ordering in which
+settings are applied is important. By default command first configures
+resolution then scaling.
+
+Settings:
+
++----------------------+----------------------------------------------+
+| ``resolution=<WxH>`` | Configure specified resolution for available |
+|                      | displays                                     |
++----------------------+----------------------------------------------+
+| ``scale=<SCALE%>``   | Configure specified scaling for available    |
+|                      | displays                                     |
++----------------------+----------------------------------------------+
+
+.. _set-bugs:
+
+set bugs
+^^^^^^^^
+
+* This command requires interactive shell to work properly.
+
+enable
+~~~~~~
+
+Usage::
+
+  idd-setup-tool.exe enable <settings>... [<global-options>]
+
+
+This command enables specified adapters and/or displays.
+
+Settings:
+
++-------------------------------+---------------------------------------------------+
+| ``adapter=<VALUE,VALUE,...>`` | Enable specified adapter (patterns: ``msft``,     |
+|                               | ``idd``, ``flex``, ``<pattern>N``)                |
++-------------------------------+---------------------------------------------------+
+| ``display=<VALUE,VALUE,...>`` | Enable specified display (patterns: ``non-flex``, |
+|                               | ``msft``, ``idd``, ``virtio``, ``non-idd``,       |
+|                               | ``<pattern>N``)                                   |
++-------------------------------+---------------------------------------------------+
+
+disable
+~~~~~~~
+
+Usage::
+
+  idd-setup-tool.exe disable <settings>... [<global-options>]
+
+This command disables specified adapters and/or displays.
+
+Settings:
+
++-------------------------------+---------------------------------------------------+
+| ``adapter=<VALUE,VALUE,...>`` | Disable specified adapter (patterns: ``msft``,    |
+|                               | ``idd``, ``flex``, ``<pattern>N``)                |
++-------------------------------+---------------------------------------------------+
+| ``display=<VALUE,VALUE,...>`` | Disable specified display (options: ``non-flex``, |
+|                               | ``msft``, ``idd``, ``virtio``, ``non-idd``,       |
+|                               | ``<pattern>N``)                                   |
++-------------------------------+---------------------------------------------------+
+
+pair
+~~~~
+
+Usage::
+
+  idd-setup-tool.exe pair [<options>] [<global-options>]
+
+Loops through IDD displays and adapters and pairs each IDD display with next
+IDD compatible adapter. If there are more displays than adapters, adapters'
+loop starts anew so some adapters will be assigned with few displays.
+
+We strongly recommend to rerun pairing explicitly anytime the following occurs:
+
+* IDD Driver is disabled/enabled
+* GFX Driver is disabled/enabled
+* System is rebooted (see BUGS)
+
+pair bugs
+^^^^^^^^^
+
+* This command might re-enable any previously disabled displays. It is
+  recommended to check and disable any unwanted displays after running this
+  command.
+
+* Pairing of IDD display with physical adapters does not preserve over reboot.
+  Rerun the pairing after reboot as needed.
+
+rearrange
+~~~~~~~~~
+
+This command rearranges displays horizontally, and sets the leftmost display
+as the primary.
+
+show
+~~~~
+
+Usage::
+
+  idd-setup-tool.exe show [<options>] [<global-options>]
+
+This command prints information on adapters or displays.
+Along with information about each display and adapter the list of adapter and display enabling and disabling
+patterns that will affect each device is also displayed.
+
+Options:
+
+--count=<yes|no>
+    Print number of IDD compatible adapters on the system (default: ``yes``)
+
+--adapters=<yes|no>
+    Print adapters information (default: ``yes``)
+
+--displays=<yes|no>
+    Print displays information (default: ``yes``)