From f78c8f13ee10b83c3cbde48453bb44ec90941a05 Mon Sep 17 00:00:00 2001 From: Jonas Rebmann Date: Mon, 28 Jul 2025 13:56:53 +0200 Subject: [PATCH 1/7] man: Migrate to doc/ As sphinx supports generating manpages, use it to simplify the process and drop the dependency on rst2man. All manpages are now tracked in doc/man. The Makefile in man/ remains for forward compatibility. Stop tracking manpages themselves in troff format. Signed-off-by: Jonas Rebmann --- doc/conf.py | 19 +- doc/man.rst | 4 +- doc/man/client.rst | 263 ++++++++++++++- doc/man/coordinator.rst | 36 ++- doc/man/device-config.rst | 241 +++++++++++++- doc/man/exporter.rst | 105 +++++- man/labgrid-pytest.rst => doc/man/pytest.rst | 11 - .../man/suggest.rst | 15 +- man/Makefile | 16 +- man/labgrid-client.1 | 304 ------------------ man/labgrid-client.rst | 272 ---------------- man/labgrid-coordinator.1 | 70 ---- man/labgrid-coordinator.rst | 48 --- man/labgrid-device-config.5 | 277 ---------------- man/labgrid-device-config.rst | 253 --------------- man/labgrid-exporter.1 | 142 -------- man/labgrid-exporter.rst | 117 ------- man/labgrid-pytest.7 | 71 ---- man/labgrid-suggest.1 | 95 ------ 19 files changed, 670 insertions(+), 1689 deletions(-) rename man/labgrid-pytest.rst => doc/man/pytest.rst (62%) rename man/labgrid-suggest.rst => doc/man/suggest.rst (74%) delete mode 100644 man/labgrid-client.1 delete mode 100644 man/labgrid-client.rst delete mode 100644 man/labgrid-coordinator.1 delete mode 100644 man/labgrid-coordinator.rst delete mode 100644 man/labgrid-device-config.5 delete mode 100644 man/labgrid-device-config.rst delete mode 100644 man/labgrid-exporter.1 delete mode 100644 man/labgrid-exporter.rst delete mode 100644 man/labgrid-pytest.7 delete mode 100644 man/labgrid-suggest.1 diff --git a/doc/conf.py b/doc/conf.py index bfdaa30a8..831ed3f64 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -156,7 +156,19 @@ # (source start file, name, description, authors, manual section). man_pages = [ (master_doc, 'labgrid', 'labgrid Documentation', - [author], 1) + [author], 1), + ('man/client', 'labgrid-client', 'labgrid\'s client interface to control boards', + [author], 1), + ('man/coordinator', 'labgrid-coordinator', 'managing labgrid resources and places', + [author], 1), + ('man/device-config', 'labgrid-device-config', 'test configuration files', + [author], 5), + ('man/exporter', 'labgrid-exporter', 'interface to control boards', + [author], 1), + ('man/pytest', 'labgrid-pytest', 'labgrid integration for pytest', + [author], 7), + ('man/suggest', 'labgrid-suggest', 'generator for YAML config files', + [author], 1), ] @@ -181,7 +193,10 @@ autodoc_mock_imports = ['onewire', 'gi', 'gi.repository', - 'vxi11'] + 'vxi11', + 'pysnmp', + 'kasa', + 'kasa.iot'] # -- Options for autosection ---------------------------------------------- autosectionlabel_prefix_document = True diff --git a/doc/man.rst b/doc/man.rst index e6d6f6360..e8fa6bd88 100644 --- a/doc/man.rst +++ b/doc/man.rst @@ -3,6 +3,8 @@ Manual Pages .. toctree:: man/client + man/coordinator man/device-config man/exporter - man/coordinator + man/pytest + man/suggest diff --git a/doc/man/client.rst b/doc/man/client.rst index bb9ce9f67..53390fe67 100644 --- a/doc/man/client.rst +++ b/doc/man/client.rst @@ -1,2 +1,263 @@ .. _labgrid-client: -.. include:: ../../man/labgrid-client.rst + +================ + labgrid-client +================ + +labgrid-client interface to control boards +========================================== + +SYNOPSIS +-------- + +``labgrid-client`` ``--help`` + +``labgrid-client`` -p + +``labgrid-client`` ``places|resources`` + +DESCRIPTION +----------- +Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. + +This is the client to control a boards status and interface with it on remote machines. + +OPTIONS +------- +-h, --help + display command line help +-p PLACE, --place PLACE + specify the place to operate on +-x ADDRESS, --coordinator ADDRESS + coordinator ``HOST[:PORT]`` to connect to, defaults to ``127.0.0.1:20408`` +-c CONFIG, --config CONFIG + set the configuration file +-s STATE, --state STATE + set an initial state before executing a command, requires a configuration + file and strategy +-i INITIAL_STATE, --initial-state INITIAL_STATE + strategy state to force into before switching to desired state, requires a + desired state (``-s``/``--state``/``LG_STATE``) +-d, --debug + enable debugging +-v, --verbose + increase verbosity +-P PROXY, --proxy PROXY + proxy connections over ssh + +CONFIGURATION FILE +------------------ +The configuration file follows the description in ``labgrid-device-config``\(5). + +ENVIRONMENT VARIABLES +--------------------- +Various labgrid-client commands use the following environment variable: + +LG_PLACE +~~~~~~~~ +This variable can be used to specify a place without using the ``-p`` option, the ``-p`` option overrides it. + +LG_TOKEN +~~~~~~~~ +This variable can be used to specify a reservation for the ``wait`` command and +for the ``+`` place expansion. + +LG_STATE +~~~~~~~~ +This variable can be used to specify a state which the device transitions into +before executing a command. Requires a configuration file and a Strategy +specified for the device. + +LG_INITIAL_STATE +~~~~~~~~~~~~~~~~ +This variable can be used to specify an initial state the device is known to +be in. +This is useful during development. The Strategy used must implement the +``force()`` method. +A desired state must be set using ``LG_STATE`` or ``-s``/``--state``. + +LG_ENV +~~~~~~ +This variable can be used to specify the configuration file to use without +using the ``--config`` option, the ``--config`` option overrides it. + +LG_COORDINATOR +~~~~~~~~~~~~~~ +This variable can be used to set the default coordinator in the format +``HOST[:PORT]`` (instead of using the ``-x`` option). + +LG_PROXY +~~~~~~~~ +This variable can be used to specify a SSH proxy hostname which should be used +to connect to the coordinator and any resources which are normally accessed +directly. + +LG_HOSTNAME +~~~~~~~~~~~ +Override the hostname used when accessing a resource. Typically only useful for +CI pipelines where the hostname may not be consistent between pipeline stages. + +LG_USERNAME +~~~~~~~~~~~ +Override the username used when accessing a resource. Typically only useful for +CI pipelines where the username may not be consistent between pipeline stages. + +LG_SSH_CONNECT_TIMEOUT +~~~~~~~~~~~~~~~~~~~~~~ +Set the connection timeout when using SSH (The ``ConnectTimeout`` option). If +unspecified, defaults to 30 seconds. + +LG_AGENT_PREFIX +~~~~~~~~~~~~~~~~~~~~~~ +Add a prefix to ``.labgrid_agent_{agent_hash}.py`` allowing specification for +where on the exporter it should be uploaded to. + +MATCHES +------- +Match patterns are used to assign a resource to a specific place. The format is: +exporter/group/cls/name, exporter is the name of the exporting machine, group is +a name defined within the exporter, cls is the class of the exported resource +and name is its name. Wild cards in match patterns are explicitly allowed, * +matches anything. + +LABGRID-CLIENT COMMANDS +----------------------- +``monitor`` Monitor events from the coordinator + +``resources (r)`` List available resources + +``places (p)`` List available places + +``who`` List acquired places by user + +``show`` Show a place and related resources + +``create`` Add a new place (name supplied by -p parameter) + +``delete`` Delete an existing place + +``add-alias`` ``[alias]`` Add an alias to a place + +``del-alias`` ``[alias]`` Delete an alias from a place + +``set-comment`` ``[comment]`` Update or set the place comment + +``set-tags`` ``[key=value]`` Set place tags (key=value) + +``add-match`` ``[match]`` Add one (or multiple) match pattern(s) to a place, see MATCHES + +``del-match`` ``[match]`` Delete one (or multiple) match pattern(s) from a place, see MATCHES + +``add-named-match`` ``[match]`` ``[name]`` Add one match pattern with a name to a place + +``acquire (lock)`` Acquire a place + +``allow`` ``[user]`` Allow another user to access a place + +``release (unlock)`` Release a place + +``release-from`` ``[host/user]`` Atomically release a place, but only if acquired by a specific user. + + Note that this command returns success as long + as the specified user no longer owns the place, + meaning it may be acquired by another user or + not at all. + +``env`` Generate a labgrid environment file for a place + +``power (pw)`` ``[action]`` Change (or get) a place's power status, where action is one of get, on, off, cycle + +``io`` ``[action]`` ``[name]`` Interact with GPIO (OneWire, relays, ...) devices, where action is one of high, low, get + +``console (con)`` ``[name]`` Connect to the console + +``dfu`` ``[arg]`` Run dfu commands + +``fastboot`` ``[arg]`` Run fastboot with argument + +``flashscript`` ``[script]`` ``[arg]`` Run arbitrary script with arguments to flash device + +``bootstrap`` ``[filename]`` Start a bootloader + +``sd-mux`` ``[action]`` Switch USB SD Muxer, where action is one of dut (device-under-test), host, off + +``usb-mux`` ``[action]`` Switch USB Muxer, where action is one of off, dut-device, host-dut, host-device, host-dut+host-device + +``ssh`` ``[command]`` Connect via SSH. Additional arguments are passed to ssh. + +``scp`` ``[source]`` ``[destination]`` Transfer file via scp (use ':dir/file' for the remote side) + +``rsync`` ``[source]`` ``[destination]`` Transfer files via rsync (use ':dir/file' for the remote side) + +``sshfs`` ``[remotepath]`` ``[mountpoint]`` Mount a remote path via sshfs + +``forward`` Forward local port to remote target + +``telnet`` Connect via telnet + +``video`` Start a video stream + +``audio`` Start an audio stream + +``tmc`` ``[command]`` Control a USB TMC device + +``write-files`` ``[filename(s)]`` Copy files onto mass storage device + +``write-image`` ``[filename]`` Write images onto block devices (USBSDMux, USB Sticks, …) + +``reserve`` ``[filter]`` Create a reservation + +``cancel-reservation`` ``[token]`` Cancel a pending reservation + +``wait`` ``[token]`` Wait for a reservation to be allocated + +``reservations`` List current reservations + +``export`` ``[filename]`` Export driver information to file (needs environment with drivers) + +``version`` Print the labgrid version + +ADDING NAMED RESOURCES +---------------------- +If a target contains multiple Resources of the same type, named matches need to +be used to address the individual resources. In addition to the `match` taken by +`add-match`, `add-named-match` also takes a name for the resource. The other +client commands support the name as an optional parameter and will inform the +user that a name is required if multiple resources are found, but no name is +given. + +If one of the resources should be used by default when no resource name is +explicitly specified, it can be named ``default``. + +EXAMPLES +-------- + +To retrieve a list of places run: + +.. code-block:: bash + + $ labgrid-client places + +To access a place, it needs to be acquired first, this can be done by running +the ``acquire command`` and passing the placename as a -p parameter: + +.. code-block:: bash + + $ labgrid-client -p acquire + +Open a console to the acquired place: + +.. code-block:: bash + + $ labgrid-client -p console + +Add all resources with the group "example-group" to the place example-place: + +.. code-block:: bash + + $ labgrid-client -p example-place add-match */example-group/*/* + +SEE ALSO +-------- + +``labgrid-exporter``\(1) diff --git a/doc/man/coordinator.rst b/doc/man/coordinator.rst index c1c7afbd7..c89eccad4 100644 --- a/doc/man/coordinator.rst +++ b/doc/man/coordinator.rst @@ -1,2 +1,34 @@ -.. _labgrid-coordinator: -.. include:: ../../man/labgrid-coordinator.rst +===================== + labgrid-coordinator +===================== + +labgrid-coordinator managing labgrid resources and places +========================================================= + +SYNOPSIS +-------- + +``labgrid-coordinator`` ``--help`` + +DESCRIPTION +----------- +Labgrid is a scalable infrastructure and test architecture for embedded (linux) +systems. + +This is the man page for the coordinator. Clients and exporters connect to the +coordinator to publish resources, manage place configuration and handle mutual +exclusion. + +OPTIONS +------- +-h, --help + display command line help +-l ADDRESS, --listen ADDRESS + make coordinator listen on host and port +-d, --debug + enable debug mode + +SEE ALSO +-------- + +``labgrid-client``\(1), ``labgrid-exporter``\(1) diff --git a/doc/man/device-config.rst b/doc/man/device-config.rst index dcf1a4427..bc03b9db5 100644 --- a/doc/man/device-config.rst +++ b/doc/man/device-config.rst @@ -1,2 +1,241 @@ .. _labgrid-device-config: -.. include:: ../../man/labgrid-device-config.rst + +======================= + labgrid-device-config +======================= + +labgrid test configuration files +================================ + +SYNOPSIS +-------- + +``*.yaml`` + +DESCRIPTION +----------- +To integrate a device into a labgrid test, labgrid needs to have a description +of the device and how to access it. + +This manual page is divided into section, each describing one top-level yaml key. + + +TARGETS +------- +The ``targets:`` top key configures a ``target``, it's ``drivers`` and ``resources``. + +The top level key is the name of the target, it needs both a ``resources`` and +``drivers`` subkey. The order of instantiated ``resources`` and ``drivers`` is +important, since they are parsed as an ordered dictionary and may depend on a +previous driver. + +For a list of available resources and drivers refer to +https://labgrid.readthedocs.io/en/latest/configuration.html. + +OPTIONS +------- +The ``options:`` top key configures various options such as the coordinator_address. + +OPTIONS KEYS +~~~~~~~~~~~~ + +``coordinator_address`` + takes as parameter the coordinator ``HOST[:PORT]`` to connect to. + Defaults to ``127.0.0.1:20408``. + +.. _labgrid-device-config-images: + +IMAGES +------ +The ``images:`` top key provides paths to access preconfigured images to flash +onto the board. The image paths can be either relative to the YAML file or +absolute. + +IMAGE KEYS +~~~~~~~~~~ + +The subkeys consist of image names as keys and their paths as values. The +corresponding name can than be used with the appropriate tool found under TOOLS. + +IMAGE EXAMPLE +~~~~~~~~~~~~~~ +Two configured images, one for the root filesystem, one for the bootloader: + +:: + + images: + root: "platform-v7a/images/root.img" + boot: "platform-v7a/images/barebox.img" + +TOOLS +----- +The ``tools:`` top key provides paths to binaries such as fastboot. + +TOOLS KEYS +~~~~~~~~~~ + +``dfu-util`` + Path to the dfu-util binary, used by the DFUDriver. + See: https://dfu-util.sourceforge.net/ + +``dpcmd`` + Path to the dpcmd binary, used by the DediprogFlashDriver. + See: https://github.com/DediProgSW/SF100Linux + +``fastboot`` + Path to the fastboot binary, used by the AndroidFastbootDriver. + See: https://developer.android.com/studio/releases/platform-tools + +``flashrom`` + Path to the flashrom binary, used by the FlashromDriver. + See: https://www.flashrom.org/ + +``imx_usb`` + Path to the imx_usb binary, used by the BDIMXUSBDriver. + See: https://github.com/boundarydevices/imx_usb_loader + +``imx-usb-loader`` + Path to the imx-usb-loader binary, used by the IMXUSBDriver. + See: https://git.pengutronix.de/cgit/barebox/tree/scripts/imx/imx-usb-loader.c + +``jtagconfig`` + Path to the jtagconfig binary, used by the QuartusHPSDriver. + See: https://www.intel.com/content/www/us/en/docs/programmable/683689/current/jtagconfig.html + +``mxs-usb-loader`` + Path to the mxs-usb-loader binary, used by the MXSUSBDriver. + See: https://git.pengutronix.de/cgit/barebox/tree/scripts/mxs-usb-loader.c?h=v2017.03.0 + +``openocd`` + Path to the openocd binary, used by the OpenOCDDriver. + See: https://openocd.org/ + +``quartus_hps`` + Path to the quartus_hps binary, used by the QuartusHPSDriver. + See: https://www.intel.com/content/www/us/en/docs/programmable/683039/22-3/hps-flash-programmer.html + +``rk-usb-loader`` + Path to the rk-usb-loader binary, used by the RKUSBDriver. + See: https://git.pengutronix.de/cgit/barebox/tree/scripts/rk-usb-loader.c + +``rsync`` + Path to the rsync binary, used by the SSHDriver. + See: https://github.com/rsyncproject/rsync + +``scp`` + Path to the scp binary, used by the SSHDriver. + See: https://github.com/openssh/openssh-portable + +``sd-mux-ctrl`` + Path to the sd-mux-ctrl binary, used by the USBSDWireDriver. + See: https://git.tizen.org/cgit/tools/testlab/sd-mux/ + +``sispmctl`` + Path to the sispmctl binary, used by the SiSPMPowerDriver. + See: https://sispmctl.sourceforge.net/ + +``ssh`` + Path to the ssh binary, used by the SSHDriver. + See: https://github.com/openssh/openssh-portable + +``sshfs`` + Path to the sshfs binary, used by the SSHDriver. + See: https://github.com/libfuse/sshfs + +``uhubctl`` + Path to the uhubctl binary, used by the USBPowerDriver. + See: https://github.com/mvp/uhubctl + +``usbmuxctl`` + Path to the usbmuxctl tool, used by the LXAUSBMuxDriver. + https://github.com/linux-automation/usbmuxctl + +``usbsdmux`` + Path to the usbsdmux tool, used by the USBSDMuxDriver. + See: https://github.com/linux-automation/usbsdmux + +``uuu-loader`` + Path to the uuu-loader binary, used by the UUUDriver. + See: https://github.com/nxp-imx/mfgtools + +``ykushcmd`` + Path to the ykushcmd binary, used by the YKUSHPowerDriver. + See: https://github.com/Yepkit/ykush + +The QEMUDriver expects a custom key set via its ``qemu_bin`` argument. +See https://www.qemu.org/ + +TOOLS EXAMPLE +~~~~~~~~~~~~~~ +Configure the tool path for ``imx-usb-loader``: + +:: + + tools: + imx-usb-loader: "/opt/labgrid-helper/imx-usb-loader" + +IMPORTS +------- +The ``imports`` key is a list of files or python modules which +are imported by the environment after loading the configuration. +Paths relative to the configuration file are also supported. +This is useful to load drivers and strategy which are contained in your +testsuite, since the import is done before instantiating the targets. + +IMPORTS EXAMPLE +~~~~~~~~~~~~~~~ +Import a local `myfunctions.py` file: + +:: + + imports: + - myfunctions.py + +EXAMPLES +-------- +A sample configuration with one `main` target, accessible via SerialPort +`/dev/ttyUSB0`, allowing usage of the ShellDriver: + +:: + + targets: + main: + resources: + RawSerialPort: + port: "/dev/ttyUSB0" + drivers: + SerialDriver: {} + ShellDriver: + prompt: 'root@[\w-]+:[^ ]+ ' + login_prompt: ' login: ' + username: 'root' + +A sample configuration with `RemotePlace`, using the tools configuration and +importing the local `mystrategy.py` file. The `MyStrategy` strategy is contained +in the loaded local python file: + +:: + + targets: + main: + resources: + RemotePlace: + name: test-place + drivers: + SerialDriver: {} + ShellDriver: + prompt: 'root@[\w-]+:[^ ]+ ' + login_prompt: ' login: ' + username: 'root' + IMXUSBDriver: {} + MyStrategy: {} + tools: + imx-usb-loader: "/opt/lg-tools/imx-usb-loader" + imports: + - mystrategy.py + +SEE ALSO +-------- + +``labgrid-client``\(1), ``labgrid-exporter``\(1) + diff --git a/doc/man/exporter.rst b/doc/man/exporter.rst index cc995a55f..3ffa03cfe 100644 --- a/doc/man/exporter.rst +++ b/doc/man/exporter.rst @@ -1,2 +1,105 @@ .. _labgrid-exporter: -.. include:: ../../man/labgrid-exporter.rst + +================== + labgrid-exporter +================== + +labgrid-exporter interface to control boards +============================================ + +SYNOPSIS +-------- + +``labgrid-exporter`` ``--help`` + +``labgrid-exporter`` ``*.yaml`` + +DESCRIPTION +----------- +Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. + +This is the man page for the exporter, supporting the export of serial ports, +USB devices and various other controllers. + +OPTIONS +------- +-h, --help + display command line help +-x, --coordinator + coordinator ``HOST[:PORT]`` to connect to, defaults to ``127.0.0.1:20408`` +-i, --isolated + enable isolated mode (always request SSH forwards) +-n, --name + the public name of the exporter +--hostname + hostname (or IP) published for accessing resources +--fqdn + use fully qualified domain name as default for hostname +-d, --debug + enable debug mode + +-i / --isolated +~~~~~~~~~~~~~~~ +This option enables isolated mode, which causes all exported resources being +marked as requiring SSH connection forwarding. +Isolated mode is useful when resources (such as NetworkSerialPorts) are not +directly accessible from the clients. +The client will then use SSH to create a port forward to the resource when +needed. + +-n / --name +~~~~~~~~~~~ +This option is used to configure the exporter name under which resources are +registered with the coordinator, which is useful when running multiple +exporters on the same host. +It defaults to the system hostname. + +--hostname +~~~~~~~~~~ +For resources like USBSerialPort, USBGenericExport or USBSigrokExport, the +exporter needs to provide a host name to set the exported value of the "host" +key. +If the system hostname is not resolvable via DNS, this option can be used to +override this default with another name (or an IP address). + +--fqdn +~~~~~~ +In some networks the fully qualified domain name may be needed to reach resources +on an exporter. This option changes the default to fqdn when no --hostname is +explicitly set. + +CONFIGURATION +------------- +The exporter uses a YAML configuration file which defines groups of related +resources. +See +for more information. + +ENVIRONMENT VARIABLES +--------------------- +The following environment variable can be used to configure labgrid-exporter. + +LG_COORDINATOR +~~~~~~~~~~~~~~ +This variable can be used to set the default coordinator in the format +``HOST[:PORT]`` (instead of using the ``-x`` option). + +EXAMPLES +-------- + +Start the exporter with the configuration file `my-config.yaml`: + +.. code-block:: bash + + $ labgrid-exporter my-config.yaml + +Same as above, but with name ``myname``: + +.. code-block:: bash + + $ labgrid-exporter -n myname my-config.yaml + +SEE ALSO +-------- + +``labgrid-client``\(1), ``labgrid-device-config``\(5) diff --git a/man/labgrid-pytest.rst b/doc/man/pytest.rst similarity index 62% rename from man/labgrid-pytest.rst rename to doc/man/pytest.rst index 04956ca92..5903c482b 100644 --- a/man/labgrid-pytest.rst +++ b/doc/man/pytest.rst @@ -5,17 +5,6 @@ labgrid-pytest labgrid integration for pytest ============================================= -:Author: Rouven Czerwinski -:organization: Labgrid-Project -:Copyright: Copyright (C) 2016-2025 Pengutronix. This library is free software; - you can redistribute it and/or modify it under the terms of the GNU - Lesser General Public License as published by the Free Software - Foundation; either version 2.1 of the License, or (at your option) - any later version. -:Version: 0.0.1 -:Manual section: 7 -:Manual group: embedded testing - SYNOPSIS -------- diff --git a/man/labgrid-suggest.rst b/doc/man/suggest.rst similarity index 74% rename from man/labgrid-suggest.rst rename to doc/man/suggest.rst index dae73b67f..d79055405 100644 --- a/man/labgrid-suggest.rst +++ b/doc/man/suggest.rst @@ -5,19 +5,6 @@ labgrid-suggest generator for YAML config files =============================================== - -:organization: Labgrid-Project -:Copyright: Copyright (C) 2016-2025 Pengutronix. This library is free software; - you can redistribute it and/or modify it under the terms of the GNU - Lesser General Public License as published by the Free Software - Foundation; either version 2.1 of the License, or (at your option) - any later version. -:Version: 0.0.1 -:Manual section: 1 -:Manual group: embedded testing - - - SYNOPSIS -------- @@ -46,7 +33,7 @@ EXAMPLES For a device that has an ``ID_SERIAL_SHORT`` key with a unique ID embedded in the USB-serial converter, ``labgrid-suggest`` shows two alternatives: -.. code-block:: yaml +.. code-block:: === added device === USBSerialPort for /devices/pci0000:00/0000:00:01.3/0000:02:00.0/usb1/1-3/1-3.1/1-3.1:1.0/ttyUSB0/tty/ttyUSB0 diff --git a/man/Makefile b/man/Makefile index 83189ca5c..c683d6ac0 100644 --- a/man/Makefile +++ b/man/Makefile @@ -1,17 +1,19 @@ PAGES := labgrid-client.1 labgrid-coordinator.1 labgrid-exporter.1 labgrid-device-config.5 labgrid-pytest.7 labgrid-suggest.1 COMPRESSED := labgrid-client.1.gz labgrid-coordinator.1.gz labgrid-exporter.1.gz labgrid-device-config.5.gz labgrid-pytest.7.gz labgrid-suggest.1.gz -%.1 %.5 %.7: %.rst - rst2man $< >$@.tmp - mv -f $@.tmp $@ +all: $(PAGES) -%.gz : % - gzip $< +compressed: $(COMPRESSED) +$(PAGES): %: ../doc/.build/man/% + cp $< $@ -all: $(PAGES) +../doc/.build/man/%: + $(MAKE) -C ../doc man + +%.gz : % + gzip $< -compressed: $(COMPRESSED) .PHONY: clean clean: diff --git a/man/labgrid-client.1 b/man/labgrid-client.1 deleted file mode 100644 index 18ce299cd..000000000 --- a/man/labgrid-client.1 +++ /dev/null @@ -1,304 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "LABGRID-CLIENT" "1" "" "0.0.1" "embedded testing" -.SH NAME -labgrid-client \- labgrid-client interface to control boards -.SH SYNOPSIS -.sp -\fBlabgrid\-client\fP \fB\-\-help\fP -.sp -\fBlabgrid\-client\fP \-p -.sp -\fBlabgrid\-client\fP \fBplaces|resources\fP -.SH DESCRIPTION -.sp -Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. -.sp -This is the client to control a boards status and interface with it on remote machines. -.SH OPTIONS -.INDENT 0.0 -.TP -.B \-h\fP,\fB \-\-help -display command line help -.TP -.BI \-p \ PLACE\fR,\fB \ \-\-place \ PLACE -specify the place to operate on -.TP -.BI \-x \ ADDRESS\fR,\fB \ \-\-coordinator \ ADDRESS -coordinator \fBHOST[:PORT]\fP to connect to, defaults to \fB127.0.0.1:20408\fP -.TP -.BI \-c \ CONFIG\fR,\fB \ \-\-config \ CONFIG -set the configuration file -.TP -.BI \-s \ STATE\fR,\fB \ \-\-state \ STATE -set an initial state before executing a command, requires a configuration -file and strategy -.TP -.BI \-i \ INITIAL_STATE\fR,\fB \ \-\-initial\-state \ INITIAL_STATE -strategy state to force into before switching to desired state, requires a -desired state (\fB\-s\fP/\fB\-\-state\fP/\fBLG_STATE\fP) -.TP -.B \-d\fP,\fB \-\-debug -enable debugging -.TP -.B \-v\fP,\fB \-\-verbose -increase verbosity -.TP -.BI \-P \ PROXY\fR,\fB \ \-\-proxy \ PROXY -proxy connections over ssh -.UNINDENT -.SH CONFIGURATION FILE -.sp -The configuration file follows the description in \fBlabgrid\-device\-config\fP(5). -.SH ENVIRONMENT VARIABLES -.sp -Various labgrid\-client commands use the following environment variable: -.SS LG_PLACE -.sp -This variable can be used to specify a place without using the \fB\-p\fP option, the \fB\-p\fP option overrides it. -.SS LG_TOKEN -.sp -This variable can be used to specify a reservation for the \fBwait\fP command and -for the \fB+\fP place expansion. -.SS LG_STATE -.sp -This variable can be used to specify a state which the device transitions into -before executing a command. Requires a configuration file and a Strategy -specified for the device. -.SS LG_INITIAL_STATE -.sp -This variable can be used to specify an initial state the device is known to -be in. -This is useful during development. The Strategy used must implement the -\fBforce()\fP method. -A desired state must be set using \fBLG_STATE\fP or \fB\-s\fP/\fB\-\-state\fP\&. -.SS LG_ENV -.sp -This variable can be used to specify the configuration file to use without -using the \fB\-\-config\fP option, the \fB\-\-config\fP option overrides it. -.SS LG_COORDINATOR -.sp -This variable can be used to set the default coordinator in the format -\fBHOST[:PORT]\fP (instead of using the \fB\-x\fP option). -.SS LG_PROXY -.sp -This variable can be used to specify a SSH proxy hostname which should be used -to connect to the coordinator and any resources which are normally accessed -directly. -.SS LG_HOSTNAME -.sp -Override the hostname used when accessing a resource. Typically only useful for -CI pipelines where the hostname may not be consistent between pipeline stages. -.SS LG_USERNAME -.sp -Override the username used when accessing a resource. Typically only useful for -CI pipelines where the username may not be consistent between pipeline stages. -.SS LG_SSH_CONNECT_TIMEOUT -.sp -Set the connection timeout when using SSH (The \fBConnectTimeout\fP option). If -unspecified, defaults to 30 seconds. -.SS LG_AGENT_PREFIX -.sp -Add a prefix to \fB\&.labgrid_agent_{agent_hash}.py\fP allowing specification for -where on the exporter it should be uploaded to. -.SH MATCHES -.sp -Match patterns are used to assign a resource to a specific place. The format is: -exporter/group/cls/name, exporter is the name of the exporting machine, group is -a name defined within the exporter, cls is the class of the exported resource -and name is its name. Wild cards in match patterns are explicitly allowed, * -matches anything. -.SH LABGRID-CLIENT COMMANDS -.sp -\fBmonitor\fP Monitor events from the coordinator -.sp -\fBresources (r)\fP List available resources -.sp -\fBplaces (p)\fP List available places -.sp -\fBwho\fP List acquired places by user -.sp -\fBshow\fP Show a place and related resources -.sp -\fBcreate\fP Add a new place (name supplied by \-p parameter) -.sp -\fBdelete\fP Delete an existing place -.sp -\fBadd\-alias\fP \fB[alias]\fP Add an alias to a place -.sp -\fBdel\-alias\fP \fB[alias]\fP Delete an alias from a place -.sp -\fBset\-comment\fP \fB[comment]\fP Update or set the place comment -.sp -\fBset\-tags\fP \fB[key=value]\fP Set place tags (key=value) -.sp -\fBadd\-match\fP \fB[match]\fP Add one (or multiple) match pattern(s) to a place, see MATCHES -.sp -\fBdel\-match\fP \fB[match]\fP Delete one (or multiple) match pattern(s) from a place, see MATCHES -.sp -\fBadd\-named\-match\fP \fB[match]\fP \fB[name]\fP Add one match pattern with a name to a place -.sp -\fBacquire (lock)\fP Acquire a place -.sp -\fBallow\fP \fB[user]\fP Allow another user to access a place -.sp -\fBrelease (unlock)\fP Release a place -.sp -\fBrelease\-from\fP \fB[host/user]\fP Atomically release a place, but only if acquired by a specific user. -.INDENT 0.0 -.INDENT 3.5 -Note that this command returns success as long -as the specified user no longer owns the place, -meaning it may be acquired by another user or -not at all. -.UNINDENT -.UNINDENT -.sp -\fBenv\fP Generate a labgrid environment file for a place -.sp -\fBpower (pw)\fP \fB[action]\fP Change (or get) a place\(aqs power status, where action is one of get, on, off, cycle -.sp -\fBio\fP \fB[action]\fP \fB[name]\fP Interact with GPIO (OneWire, relays, ...) devices, where action is one of high, low, get -.sp -\fBconsole (con)\fP \fB[name]\fP Connect to the console -.sp -\fBdfu\fP \fB[arg]\fP Run dfu commands -.sp -\fBfastboot\fP \fB[arg]\fP Run fastboot with argument -.sp -\fBflashscript\fP \fB[script]\fP \fB[arg]\fP Run arbitrary script with arguments to flash device -.sp -\fBbootstrap\fP \fB[filename]\fP Start a bootloader -.sp -\fBsd\-mux\fP \fB[action]\fP Switch USB SD Muxer, where action is one of dut (device\-under\-test), host, off -.sp -\fBusb\-mux\fP \fB[action]\fP Switch USB Muxer, where action is one of off, dut\-device, host\-dut, host\-device, host\-dut+host\-device -.sp -\fBssh\fP \fB[command]\fP Connect via SSH. Additional arguments are passed to ssh. -.sp -\fBscp\fP \fB[source]\fP \fB[destination]\fP Transfer file via scp (use \(aq:dir/file\(aq for the remote side) -.sp -\fBrsync\fP \fB[source]\fP \fB[destination]\fP Transfer files via rsync (use \(aq:dir/file\(aq for the remote side) -.sp -\fBsshfs\fP \fB[remotepath]\fP \fB[mountpoint]\fP Mount a remote path via sshfs -.sp -\fBforward\fP Forward local port to remote target -.sp -\fBtelnet\fP Connect via telnet -.sp -\fBvideo\fP Start a video stream -.sp -\fBaudio\fP Start an audio stream -.sp -\fBtmc\fP \fB[command]\fP Control a USB TMC device -.sp -\fBwrite\-files\fP \fB[filename(s)]\fP Copy files onto mass storage device -.sp -\fBwrite\-image\fP \fB[filename]\fP Write images onto block devices (USBSDMux, USB Sticks, …) -.sp -\fBreserve\fP \fB[filter]\fP Create a reservation -.sp -\fBcancel\-reservation\fP \fB[token]\fP Cancel a pending reservation -.sp -\fBwait\fP \fB[token]\fP Wait for a reservation to be allocated -.sp -\fBreservations\fP List current reservations -.sp -\fBexport\fP \fB[filename]\fP Export driver information to file (needs environment with drivers) -.sp -\fBversion\fP Print the labgrid version -.SH ADDING NAMED RESOURCES -.sp -If a target contains multiple Resources of the same type, named matches need to -be used to address the individual resources. In addition to the \fImatch\fP taken by -\fIadd\-match\fP, \fIadd\-named\-match\fP also takes a name for the resource. The other -client commands support the name as an optional parameter and will inform the -user that a name is required if multiple resources are found, but no name is -given. -.sp -If one of the resources should be used by default when no resource name is -explicitly specified, it can be named \fBdefault\fP\&. -.SH EXAMPLES -.sp -To retrieve a list of places run: -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -$ labgrid\-client places -.EE -.UNINDENT -.UNINDENT -.sp -To access a place, it needs to be acquired first, this can be done by running -the \fBacquire command\fP and passing the placename as a \-p parameter: -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -$ labgrid\-client \-p acquire -.EE -.UNINDENT -.UNINDENT -.sp -Open a console to the acquired place: -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -$ labgrid\-client \-p console -.EE -.UNINDENT -.UNINDENT -.sp -Add all resources with the group \(dqexample\-group\(dq to the place example\-place: -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -$ labgrid\-client \-p example\-place add\-match */example\-group/*/* -.EE -.UNINDENT -.UNINDENT -.SH SEE ALSO -.sp -\fBlabgrid\-exporter\fP(1) -.SH AUTHOR -Rouven Czerwinski - -Organization: Labgrid-Project -.SH COPYRIGHT -Copyright (C) 2016-2025 Pengutronix. This library is free software; -you can redistribute it and/or modify it under the terms of the GNU -Lesser General Public License as published by the Free Software -Foundation; either version 2.1 of the License, or (at your option) -any later version. -.\" Generated by docutils manpage writer. -. diff --git a/man/labgrid-client.rst b/man/labgrid-client.rst deleted file mode 100644 index e20c1d4e2..000000000 --- a/man/labgrid-client.rst +++ /dev/null @@ -1,272 +0,0 @@ -================ - labgrid-client -================ - -labgrid-client interface to control boards -========================================== - -:Author: Rouven Czerwinski -:organization: Labgrid-Project -:Copyright: Copyright (C) 2016-2025 Pengutronix. This library is free software; - you can redistribute it and/or modify it under the terms of the GNU - Lesser General Public License as published by the Free Software - Foundation; either version 2.1 of the License, or (at your option) - any later version. -:Version: 0.0.1 -:Manual section: 1 -:Manual group: embedded testing - -SYNOPSIS --------- - -``labgrid-client`` ``--help`` - -``labgrid-client`` -p - -``labgrid-client`` ``places|resources`` - -DESCRIPTION ------------ -Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. - -This is the client to control a boards status and interface with it on remote machines. - -OPTIONS -------- --h, --help - display command line help --p PLACE, --place PLACE - specify the place to operate on --x ADDRESS, --coordinator ADDRESS - coordinator ``HOST[:PORT]`` to connect to, defaults to ``127.0.0.1:20408`` --c CONFIG, --config CONFIG - set the configuration file --s STATE, --state STATE - set an initial state before executing a command, requires a configuration - file and strategy --i INITIAL_STATE, --initial-state INITIAL_STATE - strategy state to force into before switching to desired state, requires a - desired state (``-s``/``--state``/``LG_STATE``) --d, --debug - enable debugging --v, --verbose - increase verbosity --P PROXY, --proxy PROXY - proxy connections over ssh - -CONFIGURATION FILE ------------------- -The configuration file follows the description in ``labgrid-device-config``\(5). - -ENVIRONMENT VARIABLES ---------------------- -Various labgrid-client commands use the following environment variable: - -LG_PLACE -~~~~~~~~ -This variable can be used to specify a place without using the ``-p`` option, the ``-p`` option overrides it. - -LG_TOKEN -~~~~~~~~ -This variable can be used to specify a reservation for the ``wait`` command and -for the ``+`` place expansion. - -LG_STATE -~~~~~~~~ -This variable can be used to specify a state which the device transitions into -before executing a command. Requires a configuration file and a Strategy -specified for the device. - -LG_INITIAL_STATE -~~~~~~~~~~~~~~~~ -This variable can be used to specify an initial state the device is known to -be in. -This is useful during development. The Strategy used must implement the -``force()`` method. -A desired state must be set using ``LG_STATE`` or ``-s``/``--state``. - -LG_ENV -~~~~~~ -This variable can be used to specify the configuration file to use without -using the ``--config`` option, the ``--config`` option overrides it. - -LG_COORDINATOR -~~~~~~~~~~~~~~ -This variable can be used to set the default coordinator in the format -``HOST[:PORT]`` (instead of using the ``-x`` option). - -LG_PROXY -~~~~~~~~ -This variable can be used to specify a SSH proxy hostname which should be used -to connect to the coordinator and any resources which are normally accessed -directly. - -LG_HOSTNAME -~~~~~~~~~~~ -Override the hostname used when accessing a resource. Typically only useful for -CI pipelines where the hostname may not be consistent between pipeline stages. - -LG_USERNAME -~~~~~~~~~~~ -Override the username used when accessing a resource. Typically only useful for -CI pipelines where the username may not be consistent between pipeline stages. - -LG_SSH_CONNECT_TIMEOUT -~~~~~~~~~~~~~~~~~~~~~~ -Set the connection timeout when using SSH (The ``ConnectTimeout`` option). If -unspecified, defaults to 30 seconds. - -LG_AGENT_PREFIX -~~~~~~~~~~~~~~~~~~~~~~ -Add a prefix to ``.labgrid_agent_{agent_hash}.py`` allowing specification for -where on the exporter it should be uploaded to. - -MATCHES -------- -Match patterns are used to assign a resource to a specific place. The format is: -exporter/group/cls/name, exporter is the name of the exporting machine, group is -a name defined within the exporter, cls is the class of the exported resource -and name is its name. Wild cards in match patterns are explicitly allowed, * -matches anything. - -LABGRID-CLIENT COMMANDS ------------------------ -``monitor`` Monitor events from the coordinator - -``resources (r)`` List available resources - -``places (p)`` List available places - -``who`` List acquired places by user - -``show`` Show a place and related resources - -``create`` Add a new place (name supplied by -p parameter) - -``delete`` Delete an existing place - -``add-alias`` ``[alias]`` Add an alias to a place - -``del-alias`` ``[alias]`` Delete an alias from a place - -``set-comment`` ``[comment]`` Update or set the place comment - -``set-tags`` ``[key=value]`` Set place tags (key=value) - -``add-match`` ``[match]`` Add one (or multiple) match pattern(s) to a place, see MATCHES - -``del-match`` ``[match]`` Delete one (or multiple) match pattern(s) from a place, see MATCHES - -``add-named-match`` ``[match]`` ``[name]`` Add one match pattern with a name to a place - -``acquire (lock)`` Acquire a place - -``allow`` ``[user]`` Allow another user to access a place - -``release (unlock)`` Release a place - -``release-from`` ``[host/user]`` Atomically release a place, but only if acquired by a specific user. - - Note that this command returns success as long - as the specified user no longer owns the place, - meaning it may be acquired by another user or - not at all. - -``env`` Generate a labgrid environment file for a place - -``power (pw)`` ``[action]`` Change (or get) a place's power status, where action is one of get, on, off, cycle - -``io`` ``[action]`` ``[name]`` Interact with GPIO (OneWire, relays, ...) devices, where action is one of high, low, get - -``console (con)`` ``[name]`` Connect to the console - -``dfu`` ``[arg]`` Run dfu commands - -``fastboot`` ``[arg]`` Run fastboot with argument - -``flashscript`` ``[script]`` ``[arg]`` Run arbitrary script with arguments to flash device - -``bootstrap`` ``[filename]`` Start a bootloader - -``sd-mux`` ``[action]`` Switch USB SD Muxer, where action is one of dut (device-under-test), host, off - -``usb-mux`` ``[action]`` Switch USB Muxer, where action is one of off, dut-device, host-dut, host-device, host-dut+host-device - -``ssh`` ``[command]`` Connect via SSH. Additional arguments are passed to ssh. - -``scp`` ``[source]`` ``[destination]`` Transfer file via scp (use ':dir/file' for the remote side) - -``rsync`` ``[source]`` ``[destination]`` Transfer files via rsync (use ':dir/file' for the remote side) - -``sshfs`` ``[remotepath]`` ``[mountpoint]`` Mount a remote path via sshfs - -``forward`` Forward local port to remote target - -``telnet`` Connect via telnet - -``video`` Start a video stream - -``audio`` Start an audio stream - -``tmc`` ``[command]`` Control a USB TMC device - -``write-files`` ``[filename(s)]`` Copy files onto mass storage device - -``write-image`` ``[filename]`` Write images onto block devices (USBSDMux, USB Sticks, …) - -``reserve`` ``[filter]`` Create a reservation - -``cancel-reservation`` ``[token]`` Cancel a pending reservation - -``wait`` ``[token]`` Wait for a reservation to be allocated - -``reservations`` List current reservations - -``export`` ``[filename]`` Export driver information to file (needs environment with drivers) - -``version`` Print the labgrid version - -ADDING NAMED RESOURCES ----------------------- -If a target contains multiple Resources of the same type, named matches need to -be used to address the individual resources. In addition to the `match` taken by -`add-match`, `add-named-match` also takes a name for the resource. The other -client commands support the name as an optional parameter and will inform the -user that a name is required if multiple resources are found, but no name is -given. - -If one of the resources should be used by default when no resource name is -explicitly specified, it can be named ``default``. - -EXAMPLES --------- - -To retrieve a list of places run: - -.. code-block:: bash - - $ labgrid-client places - -To access a place, it needs to be acquired first, this can be done by running -the ``acquire command`` and passing the placename as a -p parameter: - -.. code-block:: bash - - $ labgrid-client -p acquire - -Open a console to the acquired place: - -.. code-block:: bash - - $ labgrid-client -p console - -Add all resources with the group "example-group" to the place example-place: - -.. code-block:: bash - - $ labgrid-client -p example-place add-match */example-group/*/* - -SEE ALSO --------- - -``labgrid-exporter``\(1) diff --git a/man/labgrid-coordinator.1 b/man/labgrid-coordinator.1 deleted file mode 100644 index 0595b3098..000000000 --- a/man/labgrid-coordinator.1 +++ /dev/null @@ -1,70 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "LABGRID-COORDINATOR" "1" "" "0.0.1" "embedded testing" -.SH NAME -labgrid-coordinator \- labgrid-coordinator managing labgrid resources and places -.SH SYNOPSIS -.sp -\fBlabgrid\-coordinator\fP \fB\-\-help\fP -.SH DESCRIPTION -.sp -Labgrid is a scalable infrastructure and test architecture for embedded (linux) -systems. -.sp -This is the man page for the coordinator. Clients and exporters connect to the -coordinator to publish resources, manage place configuration and handle mutual -exclusion. -.SH OPTIONS -.INDENT 0.0 -.TP -.B \-h\fP,\fB \-\-help -display command line help -.TP -.BI \-l \ ADDRESS\fR,\fB \ \-\-listen \ ADDRESS -make coordinator listen on host and port -.TP -.B \-d\fP,\fB \-\-debug -enable debug mode -.UNINDENT -.SH SEE ALSO -.sp -\fBlabgrid\-client\fP(1), \fBlabgrid\-exporter\fP(1) -.SH AUTHOR -Rouven Czerwinski - -Organization: Labgrid-Project -.SH COPYRIGHT -Copyright (C) 2016-2025 Pengutronix. This library is free software; -you can redistribute it and/or modify it under the terms of the GNU -Lesser General Public License as published by the Free Software -Foundation; either version 2.1 of the License, or (at your option) -any later version. -.\" Generated by docutils manpage writer. -. diff --git a/man/labgrid-coordinator.rst b/man/labgrid-coordinator.rst deleted file mode 100644 index 9b651e9e7..000000000 --- a/man/labgrid-coordinator.rst +++ /dev/null @@ -1,48 +0,0 @@ -===================== - labgrid-coordinator -===================== - -labgrid-coordinator managing labgrid resources and places -========================================================= - - -:Author: Rouven Czerwinski -:organization: Labgrid-Project -:Copyright: Copyright (C) 2016-2025 Pengutronix. This library is free software; - you can redistribute it and/or modify it under the terms of the GNU - Lesser General Public License as published by the Free Software - Foundation; either version 2.1 of the License, or (at your option) - any later version. -:Version: 0.0.1 -:Manual section: 1 -:Manual group: embedded testing - - - -SYNOPSIS --------- - -``labgrid-coordinator`` ``--help`` - -DESCRIPTION ------------ -Labgrid is a scalable infrastructure and test architecture for embedded (linux) -systems. - -This is the man page for the coordinator. Clients and exporters connect to the -coordinator to publish resources, manage place configuration and handle mutual -exclusion. - -OPTIONS -------- --h, --help - display command line help --l ADDRESS, --listen ADDRESS - make coordinator listen on host and port --d, --debug - enable debug mode - -SEE ALSO --------- - -``labgrid-client``\(1), ``labgrid-exporter``\(1) diff --git a/man/labgrid-device-config.5 b/man/labgrid-device-config.5 deleted file mode 100644 index 4a5904169..000000000 --- a/man/labgrid-device-config.5 +++ /dev/null @@ -1,277 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "LABGRID-DEVICE-CONFIG" "5" "" "0.0.1" "embedded testing" -.SH NAME -labgrid-device-config \- labgrid test configuration files -.SH SYNOPSIS -.sp -\fB*.yaml\fP -.SH DESCRIPTION -.sp -To integrate a device into a labgrid test, labgrid needs to have a description -of the device and how to access it. -.sp -This manual page is divided into section, each describing one top\-level yaml key. -.SH TARGETS -.sp -The \fBtargets:\fP top key configures a \fBtarget\fP, it\(aqs \fBdrivers\fP and \fBresources\fP\&. -.sp -The top level key is the name of the target, it needs both a \fBresources\fP and -\fBdrivers\fP subkey. The order of instantiated \fBresources\fP and \fBdrivers\fP is -important, since they are parsed as an ordered dictionary and may depend on a -previous driver. -.sp -For a list of available resources and drivers refer to - \&. -.SH OPTIONS -.sp -The \fBoptions:\fP top key configures various options such as the coordinator_address. -.SS OPTIONS KEYS -.INDENT 0.0 -.TP -.B \fBcoordinator_address\fP -takes as parameter the coordinator \fBHOST[:PORT]\fP to connect to. -Defaults to \fB127.0.0.1:20408\fP\&. -.UNINDENT -.SH IMAGES -.sp -The \fBimages:\fP top key provides paths to access preconfigured images to flash -onto the board. The image paths can be either relative to the YAML file or -absolute. -.SS IMAGE KEYS -.sp -The subkeys consist of image names as keys and their paths as values. The -corresponding name can than be used with the appropriate tool found under TOOLS. -.SS IMAGE EXAMPLE -.sp -Two configured images, one for the root filesystem, one for the bootloader: -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -images: - root: \(dqplatform\-v7a/images/root.img\(dq - boot: \(dqplatform\-v7a/images/barebox.img\(dq -.EE -.UNINDENT -.UNINDENT -.SH TOOLS -.sp -The \fBtools:\fP top key provides paths to binaries such as fastboot. -.SS TOOLS KEYS -.INDENT 0.0 -.TP -.B \fBdfu\-util\fP -Path to the dfu\-util binary, used by the DFUDriver. -See: -.TP -.B \fBdpcmd\fP -Path to the dpcmd binary, used by the DediprogFlashDriver. -See: -.TP -.B \fBfastboot\fP -Path to the fastboot binary, used by the AndroidFastbootDriver. -See: -.TP -.B \fBflashrom\fP -Path to the flashrom binary, used by the FlashromDriver. -See: -.TP -.B \fBimx_usb\fP -Path to the imx_usb binary, used by the BDIMXUSBDriver. -See: -.TP -.B \fBimx\-usb\-loader\fP -Path to the imx\-usb\-loader binary, used by the IMXUSBDriver. -See: -.TP -.B \fBjtagconfig\fP -Path to the jtagconfig binary, used by the QuartusHPSDriver. -See: -.TP -.B \fBmxs\-usb\-loader\fP -Path to the mxs\-usb\-loader binary, used by the MXSUSBDriver. -See: -.TP -.B \fBopenocd\fP -Path to the openocd binary, used by the OpenOCDDriver. -See: -.TP -.B \fBquartus_hps\fP -Path to the quartus_hps binary, used by the QuartusHPSDriver. -See: -.TP -.B \fBrk\-usb\-loader\fP -Path to the rk\-usb\-loader binary, used by the RKUSBDriver. -See: -.TP -.B \fBrsync\fP -Path to the rsync binary, used by the SSHDriver. -See: -.TP -.B \fBscp\fP -Path to the scp binary, used by the SSHDriver. -See: -.TP -.B \fBsd\-mux\-ctrl\fP -Path to the sd\-mux\-ctrl binary, used by the USBSDWireDriver. -See: -.TP -.B \fBsispmctl\fP -Path to the sispmctl binary, used by the SiSPMPowerDriver. -See: -.TP -.B \fBssh\fP -Path to the ssh binary, used by the SSHDriver. -See: -.TP -.B \fBsshfs\fP -Path to the sshfs binary, used by the SSHDriver. -See: -.TP -.B \fBuhubctl\fP -Path to the uhubctl binary, used by the USBPowerDriver. -See: -.TP -.B \fBusbmuxctl\fP -Path to the usbmuxctl tool, used by the LXAUSBMuxDriver. - -.TP -.B \fBusbsdmux\fP -Path to the usbsdmux tool, used by the USBSDMuxDriver. -See: -.TP -.B \fBuuu\-loader\fP -Path to the uuu\-loader binary, used by the UUUDriver. -See: -.TP -.B \fBykushcmd\fP -Path to the ykushcmd binary, used by the YKUSHPowerDriver. -See: -.UNINDENT -.sp -The QEMUDriver expects a custom key set via its \fBqemu_bin\fP argument. -See -.SS TOOLS EXAMPLE -.sp -Configure the tool path for \fBimx\-usb\-loader\fP: -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -tools: - imx\-usb\-loader: \(dq/opt/labgrid\-helper/imx\-usb\-loader\(dq -.EE -.UNINDENT -.UNINDENT -.SH IMPORTS -.sp -The \fBimports\fP key is a list of files or python modules which -are imported by the environment after loading the configuration. -Paths relative to the configuration file are also supported. -This is useful to load drivers and strategy which are contained in your -testsuite, since the import is done before instantiating the targets. -.SS IMPORTS EXAMPLE -.sp -Import a local \fImyfunctions.py\fP file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -imports: - \- myfunctions.py -.EE -.UNINDENT -.UNINDENT -.SH EXAMPLES -.sp -A sample configuration with one \fImain\fP target, accessible via SerialPort -\fI/dev/ttyUSB0\fP, allowing usage of the ShellDriver: -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -targets: - main: - resources: - RawSerialPort: - port: \(dq/dev/ttyUSB0\(dq - drivers: - SerialDriver: {} - ShellDriver: - prompt: \(aqroot@[\ew\-]+:[^ ]+ \(aq - login_prompt: \(aq login: \(aq - username: \(aqroot\(aq -.EE -.UNINDENT -.UNINDENT -.sp -A sample configuration with \fIRemotePlace\fP, using the tools configuration and -importing the local \fImystrategy.py\fP file. The \fIMyStrategy\fP strategy is contained -in the loaded local python file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -targets: - main: - resources: - RemotePlace: - name: test\-place - drivers: - SerialDriver: {} - ShellDriver: - prompt: \(aqroot@[\ew\-]+:[^ ]+ \(aq - login_prompt: \(aq login: \(aq - username: \(aqroot\(aq - IMXUSBDriver: {} - MyStrategy: {} -tools: - imx\-usb\-loader: \(dq/opt/lg\-tools/imx\-usb\-loader\(dq -imports: - \- mystrategy.py -.EE -.UNINDENT -.UNINDENT -.SH SEE ALSO -.sp -\fBlabgrid\-client\fP(1), \fBlabgrid\-exporter\fP(1) -.SH AUTHOR -Rouven Czerwinski - -Organization: Labgrid-Project -.SH COPYRIGHT -Copyright (C) 2016-2025 Pengutronix. This library is free software; -you can redistribute it and/or modify it under the terms of the GNU -Lesser General Public License as published by the Free Software -Foundation; either version 2.1 of the License, or (at your option) -any later version. -.\" Generated by docutils manpage writer. -. diff --git a/man/labgrid-device-config.rst b/man/labgrid-device-config.rst deleted file mode 100644 index d2a160231..000000000 --- a/man/labgrid-device-config.rst +++ /dev/null @@ -1,253 +0,0 @@ -======================= - labgrid-device-config -======================= - -labgrid test configuration files -================================ - - -:Author: Rouven Czerwinski -:organization: Labgrid-Project -:Copyright: Copyright (C) 2016-2025 Pengutronix. This library is free software; - you can redistribute it and/or modify it under the terms of the GNU - Lesser General Public License as published by the Free Software - Foundation; either version 2.1 of the License, or (at your option) - any later version. -:Version: 0.0.1 -:Manual section: 5 -:Manual group: embedded testing - - - -SYNOPSIS --------- - -``*.yaml`` - -DESCRIPTION ------------ -To integrate a device into a labgrid test, labgrid needs to have a description -of the device and how to access it. - -This manual page is divided into section, each describing one top-level yaml key. - - -TARGETS -------- -The ``targets:`` top key configures a ``target``, it's ``drivers`` and ``resources``. - -The top level key is the name of the target, it needs both a ``resources`` and -``drivers`` subkey. The order of instantiated ``resources`` and ``drivers`` is -important, since they are parsed as an ordered dictionary and may depend on a -previous driver. - -For a list of available resources and drivers refer to -https://labgrid.readthedocs.io/en/latest/configuration.html. - -OPTIONS -------- -The ``options:`` top key configures various options such as the coordinator_address. - -OPTIONS KEYS -~~~~~~~~~~~~ - -``coordinator_address`` - takes as parameter the coordinator ``HOST[:PORT]`` to connect to. - Defaults to ``127.0.0.1:20408``. - -.. _labgrid-device-config-images: - -IMAGES ------- -The ``images:`` top key provides paths to access preconfigured images to flash -onto the board. The image paths can be either relative to the YAML file or -absolute. - -IMAGE KEYS -~~~~~~~~~~ - -The subkeys consist of image names as keys and their paths as values. The -corresponding name can than be used with the appropriate tool found under TOOLS. - -IMAGE EXAMPLE -~~~~~~~~~~~~~~ -Two configured images, one for the root filesystem, one for the bootloader: - -:: - - images: - root: "platform-v7a/images/root.img" - boot: "platform-v7a/images/barebox.img" - -TOOLS ------ -The ``tools:`` top key provides paths to binaries such as fastboot. - -TOOLS KEYS -~~~~~~~~~~ - -``dfu-util`` - Path to the dfu-util binary, used by the DFUDriver. - See: https://dfu-util.sourceforge.net/ - -``dpcmd`` - Path to the dpcmd binary, used by the DediprogFlashDriver. - See: https://github.com/DediProgSW/SF100Linux - -``fastboot`` - Path to the fastboot binary, used by the AndroidFastbootDriver. - See: https://developer.android.com/studio/releases/platform-tools - -``flashrom`` - Path to the flashrom binary, used by the FlashromDriver. - See: https://www.flashrom.org/ - -``imx_usb`` - Path to the imx_usb binary, used by the BDIMXUSBDriver. - See: https://github.com/boundarydevices/imx_usb_loader - -``imx-usb-loader`` - Path to the imx-usb-loader binary, used by the IMXUSBDriver. - See: https://git.pengutronix.de/cgit/barebox/tree/scripts/imx/imx-usb-loader.c - -``jtagconfig`` - Path to the jtagconfig binary, used by the QuartusHPSDriver. - See: https://www.intel.com/content/www/us/en/docs/programmable/683689/current/jtagconfig.html - -``mxs-usb-loader`` - Path to the mxs-usb-loader binary, used by the MXSUSBDriver. - See: https://git.pengutronix.de/cgit/barebox/tree/scripts/mxs-usb-loader.c?h=v2017.03.0 - -``openocd`` - Path to the openocd binary, used by the OpenOCDDriver. - See: https://openocd.org/ - -``quartus_hps`` - Path to the quartus_hps binary, used by the QuartusHPSDriver. - See: https://www.intel.com/content/www/us/en/docs/programmable/683039/22-3/hps-flash-programmer.html - -``rk-usb-loader`` - Path to the rk-usb-loader binary, used by the RKUSBDriver. - See: https://git.pengutronix.de/cgit/barebox/tree/scripts/rk-usb-loader.c - -``rsync`` - Path to the rsync binary, used by the SSHDriver. - See: https://github.com/rsyncproject/rsync - -``scp`` - Path to the scp binary, used by the SSHDriver. - See: https://github.com/openssh/openssh-portable - -``sd-mux-ctrl`` - Path to the sd-mux-ctrl binary, used by the USBSDWireDriver. - See: https://git.tizen.org/cgit/tools/testlab/sd-mux/ - -``sispmctl`` - Path to the sispmctl binary, used by the SiSPMPowerDriver. - See: https://sispmctl.sourceforge.net/ - -``ssh`` - Path to the ssh binary, used by the SSHDriver. - See: https://github.com/openssh/openssh-portable - -``sshfs`` - Path to the sshfs binary, used by the SSHDriver. - See: https://github.com/libfuse/sshfs - -``uhubctl`` - Path to the uhubctl binary, used by the USBPowerDriver. - See: https://github.com/mvp/uhubctl - -``usbmuxctl`` - Path to the usbmuxctl tool, used by the LXAUSBMuxDriver. - https://github.com/linux-automation/usbmuxctl - -``usbsdmux`` - Path to the usbsdmux tool, used by the USBSDMuxDriver. - See: https://github.com/linux-automation/usbsdmux - -``uuu-loader`` - Path to the uuu-loader binary, used by the UUUDriver. - See: https://github.com/nxp-imx/mfgtools - -``ykushcmd`` - Path to the ykushcmd binary, used by the YKUSHPowerDriver. - See: https://github.com/Yepkit/ykush - -The QEMUDriver expects a custom key set via its ``qemu_bin`` argument. -See https://www.qemu.org/ - -TOOLS EXAMPLE -~~~~~~~~~~~~~~ -Configure the tool path for ``imx-usb-loader``: - -:: - - tools: - imx-usb-loader: "/opt/labgrid-helper/imx-usb-loader" - -IMPORTS -------- -The ``imports`` key is a list of files or python modules which -are imported by the environment after loading the configuration. -Paths relative to the configuration file are also supported. -This is useful to load drivers and strategy which are contained in your -testsuite, since the import is done before instantiating the targets. - -IMPORTS EXAMPLE -~~~~~~~~~~~~~~~ -Import a local `myfunctions.py` file: - -:: - - imports: - - myfunctions.py - -EXAMPLES --------- -A sample configuration with one `main` target, accessible via SerialPort -`/dev/ttyUSB0`, allowing usage of the ShellDriver: - -:: - - targets: - main: - resources: - RawSerialPort: - port: "/dev/ttyUSB0" - drivers: - SerialDriver: {} - ShellDriver: - prompt: 'root@[\w-]+:[^ ]+ ' - login_prompt: ' login: ' - username: 'root' - -A sample configuration with `RemotePlace`, using the tools configuration and -importing the local `mystrategy.py` file. The `MyStrategy` strategy is contained -in the loaded local python file: - -:: - - targets: - main: - resources: - RemotePlace: - name: test-place - drivers: - SerialDriver: {} - ShellDriver: - prompt: 'root@[\w-]+:[^ ]+ ' - login_prompt: ' login: ' - username: 'root' - IMXUSBDriver: {} - MyStrategy: {} - tools: - imx-usb-loader: "/opt/lg-tools/imx-usb-loader" - imports: - - mystrategy.py - -SEE ALSO --------- - -``labgrid-client``\(1), ``labgrid-exporter``\(1) - diff --git a/man/labgrid-exporter.1 b/man/labgrid-exporter.1 deleted file mode 100644 index 7a5bcf953..000000000 --- a/man/labgrid-exporter.1 +++ /dev/null @@ -1,142 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "LABGRID-EXPORTER" "1" "" "0.0.1" "embedded testing" -.SH NAME -labgrid-exporter \- labgrid-exporter interface to control boards -.SH SYNOPSIS -.sp -\fBlabgrid\-exporter\fP \fB\-\-help\fP -.sp -\fBlabgrid\-exporter\fP \fB*.yaml\fP -.SH DESCRIPTION -.sp -Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. -.sp -This is the man page for the exporter, supporting the export of serial ports, -USB devices and various other controllers. -.SH OPTIONS -.INDENT 0.0 -.TP -.B \-h\fP,\fB \-\-help -display command line help -.TP -.B \-x\fP,\fB \-\-coordinator -coordinator \fBHOST[:PORT]\fP to connect to, defaults to \fB127.0.0.1:20408\fP -.TP -.B \-i\fP,\fB \-\-isolated -enable isolated mode (always request SSH forwards) -.TP -.B \-n\fP,\fB \-\-name -the public name of the exporter -.TP -.B \-\-hostname -hostname (or IP) published for accessing resources -.TP -.B \-\-fqdn -use fully qualified domain name as default for hostname -.TP -.B \-d\fP,\fB \-\-debug -enable debug mode -.UNINDENT -.SS \-i / \-\-isolated -.sp -This option enables isolated mode, which causes all exported resources being -marked as requiring SSH connection forwarding. -Isolated mode is useful when resources (such as NetworkSerialPorts) are not -directly accessible from the clients. -The client will then use SSH to create a port forward to the resource when -needed. -.SS \-n / \-\-name -.sp -This option is used to configure the exporter name under which resources are -registered with the coordinator, which is useful when running multiple -exporters on the same host. -It defaults to the system hostname. -.SS \-\-hostname -.sp -For resources like USBSerialPort, USBGenericExport or USBSigrokExport, the -exporter needs to provide a host name to set the exported value of the \(dqhost\(dq -key. -If the system hostname is not resolvable via DNS, this option can be used to -override this default with another name (or an IP address). -.SS \-\-fqdn -.sp -In some networks the fully qualified domain name may be needed to reach resources -on an exporter. This option changes the default to fqdn when no \-\-hostname is -explicitly set. -.SH CONFIGURATION -.sp -The exporter uses a YAML configuration file which defines groups of related -resources. -See < > -for more information. -.SH ENVIRONMENT VARIABLES -.sp -The following environment variable can be used to configure labgrid\-exporter. -.SS LG_COORDINATOR -.sp -This variable can be used to set the default coordinator in the format -\fBHOST[:PORT]\fP (instead of using the \fB\-x\fP option). -.SH EXAMPLES -.sp -Start the exporter with the configuration file \fImy\-config.yaml\fP: -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -$ labgrid\-exporter my\-config.yaml -.EE -.UNINDENT -.UNINDENT -.sp -Same as above, but with name \fBmyname\fP: -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -$ labgrid\-exporter \-n myname my\-config.yaml -.EE -.UNINDENT -.UNINDENT -.SH SEE ALSO -.sp -\fBlabgrid\-client\fP(1), \fBlabgrid\-device\-config\fP(5) -.SH AUTHOR -Rouven Czerwinski - -Organization: Labgrid-Project -.SH COPYRIGHT -Copyright (C) 2016-2025 Pengutronix. This library is free software; -you can redistribute it and/or modify it under the terms of the GNU -Lesser General Public License as published by the Free Software -Foundation; either version 2.1 of the License, or (at your option) -any later version. -.\" Generated by docutils manpage writer. -. diff --git a/man/labgrid-exporter.rst b/man/labgrid-exporter.rst deleted file mode 100644 index 9b80237e7..000000000 --- a/man/labgrid-exporter.rst +++ /dev/null @@ -1,117 +0,0 @@ -================== - labgrid-exporter -================== - -labgrid-exporter interface to control boards -============================================ - - -:Author: Rouven Czerwinski -:organization: Labgrid-Project -:Copyright: Copyright (C) 2016-2025 Pengutronix. This library is free software; - you can redistribute it and/or modify it under the terms of the GNU - Lesser General Public License as published by the Free Software - Foundation; either version 2.1 of the License, or (at your option) - any later version. -:Version: 0.0.1 -:Manual section: 1 -:Manual group: embedded testing - - - -SYNOPSIS --------- - -``labgrid-exporter`` ``--help`` - -``labgrid-exporter`` ``*.yaml`` - -DESCRIPTION ------------ -Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. - -This is the man page for the exporter, supporting the export of serial ports, -USB devices and various other controllers. - -OPTIONS -------- --h, --help - display command line help --x, --coordinator - coordinator ``HOST[:PORT]`` to connect to, defaults to ``127.0.0.1:20408`` --i, --isolated - enable isolated mode (always request SSH forwards) --n, --name - the public name of the exporter ---hostname - hostname (or IP) published for accessing resources ---fqdn - use fully qualified domain name as default for hostname --d, --debug - enable debug mode - --i / --isolated -~~~~~~~~~~~~~~~ -This option enables isolated mode, which causes all exported resources being -marked as requiring SSH connection forwarding. -Isolated mode is useful when resources (such as NetworkSerialPorts) are not -directly accessible from the clients. -The client will then use SSH to create a port forward to the resource when -needed. - --n / --name -~~~~~~~~~~~ -This option is used to configure the exporter name under which resources are -registered with the coordinator, which is useful when running multiple -exporters on the same host. -It defaults to the system hostname. - ---hostname -~~~~~~~~~~ -For resources like USBSerialPort, USBGenericExport or USBSigrokExport, the -exporter needs to provide a host name to set the exported value of the "host" -key. -If the system hostname is not resolvable via DNS, this option can be used to -override this default with another name (or an IP address). - ---fqdn -~~~~~~ -In some networks the fully qualified domain name may be needed to reach resources -on an exporter. This option changes the default to fqdn when no --hostname is -explicitly set. - -CONFIGURATION -------------- -The exporter uses a YAML configuration file which defines groups of related -resources. -See -for more information. - -ENVIRONMENT VARIABLES ---------------------- -The following environment variable can be used to configure labgrid-exporter. - -LG_COORDINATOR -~~~~~~~~~~~~~~ -This variable can be used to set the default coordinator in the format -``HOST[:PORT]`` (instead of using the ``-x`` option). - -EXAMPLES --------- - -Start the exporter with the configuration file `my-config.yaml`: - -.. code-block:: bash - - $ labgrid-exporter my-config.yaml - -Same as above, but with name ``myname``: - -.. code-block:: bash - - $ labgrid-exporter -n myname my-config.yaml - -SEE ALSO --------- - -``labgrid-client``\(1), ``labgrid-device-config``\(5) diff --git a/man/labgrid-pytest.7 b/man/labgrid-pytest.7 deleted file mode 100644 index 0d0c263a5..000000000 --- a/man/labgrid-pytest.7 +++ /dev/null @@ -1,71 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "LABGRID-PYTEST" "7" "" "0.0.1" "embedded testing" -.SH NAME -labgrid-pytest \- labgrid-pytest labgrid integration for pytest -.SH SYNOPSIS -.sp -\fBpytest \-\-lg\-env\fP \fB*.yaml\fP -.SH DESCRIPTION -.sp -Labgrid ships a pytest plugin to integrate with the pytest infrastructure. It is -activated if the \fI\-\-lg\-env\fP parameter is supplied to the pytest command. -.sp -The labgrid plugin parses the supplied configuration yaml file as described in -\fBlabgrid\-device\-config\fP(5) and allows the usage of the target and environment -fixtures. -The complete documentation is available at - \&. -.SH EXAMPLES -.sp -Start tests with \fBmyconfig.yaml\fP and directory \fBtests\fP: -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -$ pytest \-\-lg\-env myconfig.yaml tests -.EE -.UNINDENT -.UNINDENT -.SH SEE ALSO -.sp -\fBlabgrid\-device\-config\fP(5) -.SH AUTHOR -Rouven Czerwinski - -Organization: Labgrid-Project -.SH COPYRIGHT -Copyright (C) 2016-2025 Pengutronix. This library is free software; -you can redistribute it and/or modify it under the terms of the GNU -Lesser General Public License as published by the Free Software -Foundation; either version 2.1 of the License, or (at your option) -any later version. -.\" Generated by docutils manpage writer. -. diff --git a/man/labgrid-suggest.1 b/man/labgrid-suggest.1 deleted file mode 100644 index a4305acca..000000000 --- a/man/labgrid-suggest.1 +++ /dev/null @@ -1,95 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "LABGRID-SUGGEST" "1" "" "0.0.1" "embedded testing" -.SH NAME -labgrid-suggest \- labgrid-suggest generator for YAML config files -.SH SYNOPSIS -.sp -\fBlabgrid\-suggest\fP \fB\-\-help\fP -.sp -\fBlabgrid\-suggest\fP \fB\-\-debug\fP -.SH DESCRIPTION -.sp -Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. -.sp -This is the man page for a helper tool which will output the proper YAML formatted -snippets for udev scanned devices. -The snippets can be added under the resource key in an environment configuration. -.SH OPTIONS -.INDENT 0.0 -.TP -.B \-h\fP,\fB \-\-help -display command line help -.TP -.B \-d\fP,\fB \-\-debug -enable debug mode -.UNINDENT -.SH EXAMPLES -.sp -For a device that has an \fBID_SERIAL_SHORT\fP key with a unique ID embedded -in the USB\-serial converter, \fBlabgrid\-suggest\fP shows two alternatives: -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -=== added device === -USBSerialPort for /devices/pci0000:00/0000:00:01.3/0000:02:00.0/usb1/1\-3/1\-3.1/1\-3.1:1.0/ttyUSB0/tty/ttyUSB0 -=== device properties === -device node: /dev/ttyUSB0 -udev tags: , systemd -vendor: Silicon_Labs -vendor (DB): Advanced Micro Devices, Inc. [AMD] -model: CP2102_USB_to_UART_Bridge_Controller -revision: 0100 -=== suggested matches === -USBSerialPort: - match: - ID_PATH: pci\-0000:02:00.0\-usb\-0:3.1:1.0 -\-\-\- -USBSerialPort: - match: - ID_SERIAL_SHORT: P\-00\-03564 -\-\-\- -.EE -.UNINDENT -.UNINDENT -.SH SEE ALSO -.sp -\fBlabgrid\-device\-config\fP(5) - -Organization: Labgrid-Project -.SH COPYRIGHT -Copyright (C) 2016-2025 Pengutronix. This library is free software; -you can redistribute it and/or modify it under the terms of the GNU -Lesser General Public License as published by the Free Software -Foundation; either version 2.1 of the License, or (at your option) -any later version. -.\" Generated by docutils manpage writer. -. From 2ebf3b0d1b827155ddf693eb5b853ed83b40c5e2 Mon Sep 17 00:00:00 2001 From: Jonas Rebmann Date: Fri, 25 Jul 2025 11:06:53 +0200 Subject: [PATCH 2/7] remote/client: separate ArgumentParser() definition This is an idiomatic way of setting up argument parsers and allows the parser to be re-used for manpage/documentation generation. Signed-off-by: Jonas Rebmann --- labgrid/remote/client.py | 71 ++++++++++++++++++++++++++-------------- 1 file changed, 46 insertions(+), 25 deletions(-) diff --git a/labgrid/remote/client.py b/labgrid/remote/client.py index 27108a7b4..13fd52728 100755 --- a/labgrid/remote/client.py +++ b/labgrid/remote/client.py @@ -1705,23 +1705,7 @@ def __str__(self): return self.value -def main(): - basicConfig( - level=logging.WARNING, - stream=sys.stderr, - ) - - StepLogger.start() - processwrapper.enable_logging() - - # Support both legacy variables and properly namespaced ones - place = os.environ.get("PLACE", None) - place = os.environ.get("LG_PLACE", place) - state = os.environ.get("STATE", None) - state = os.environ.get("LG_STATE", state) - initial_state = os.environ.get("LG_INITIAL_STATE", None) - token = os.environ.get("LG_TOKEN", None) - +def get_parser() -> argparse.ArgumentParser: parser = argparse.ArgumentParser() parser.add_argument( "-x", @@ -1734,24 +1718,19 @@ def main(): "-c", "--config", type=str, - default=os.environ.get("LG_ENV"), help="env config file (default: value from env variable LG_ENV)", ) - parser.add_argument( - "-p", "--place", type=str, default=place, help="place name/alias (default: value from env variable LG_PLACE)" - ) + parser.add_argument("-p", "--place", type=str, help="place name/alias (default: value from env variable LG_PLACE)") parser.add_argument( "-s", "--state", type=str, - default=state, help="strategy state to switch into before command (default: value from env varibale LG_STATE)", ) parser.add_argument( "-i", "--initial-state", type=str, - default=initial_state, help="strategy state to force into before switching to desired state", ) parser.add_argument( @@ -2065,11 +2044,11 @@ def main(): subparser.set_defaults(func=ClientSession.create_reservation) subparser = subparsers.add_parser("cancel-reservation", help="cancel a reservation") - subparser.add_argument("token", type=str, default=token, nargs="?" if token else None) + subparser.add_argument("token", type=str, nargs="?") subparser.set_defaults(func=ClientSession.cancel_reservation) subparser = subparsers.add_parser("wait", help="wait for a reservation to be allocated") - subparser.add_argument("token", type=str, default=token, nargs="?" if token else None) + subparser.add_argument("token", type=str, nargs="?") subparser.set_defaults(func=ClientSession.wait_reservation) subparser = subparsers.add_parser("reservations", help="list current reservations") @@ -2092,6 +2071,28 @@ def main(): subparser = subparsers.add_parser("version", help="show version") subparser.set_defaults(func=ClientSession.print_version) + return parser + + +def main(): + basicConfig( + level=logging.WARNING, + stream=sys.stderr, + ) + + StepLogger.start() + processwrapper.enable_logging() + + # Support both legacy variables and properly namespaced ones + place = os.environ.get("PLACE", None) + place = os.environ.get("LG_PLACE", place) + state = os.environ.get("STATE", None) + state = os.environ.get("LG_STATE", state) + initial_state = os.environ.get("LG_INITIAL_STATE", None) + token = os.environ.get("LG_TOKEN", None) + + parser = get_parser() + # make any leftover arguments available for some commands args, leftover = parser.parse_known_args() if args.command not in ["ssh", "rsync", "forward"]: @@ -2099,6 +2100,26 @@ def main(): else: args.leftover = leftover + # handle dynamic defaults + if args.config is None: + args.config = os.environ.get("LG_ENV") + + if args.place is None: + args.place = place + + if args.state is None: + args.state = state + + if args.initial_state is None: + args.initial_state = initial_state + + if args.command in ["cancel-reservation", "wait"] and args.token is None: + if token: + args.token = token + else: + print("Please provide a token", file=sys.stderr) + exit(1) + if args.verbose: logging.getLogger().setLevel(logging.INFO) if args.verbose > 1: From 999f33c4d2e6eaee7cbce5bfaa821815d5e9bc7b Mon Sep 17 00:00:00 2001 From: Jonas Rebmann Date: Fri, 25 Jul 2025 13:30:22 +0200 Subject: [PATCH 3/7] doc: man: Generate labgrid-client manpage using sphinx-argparse The old process was to manually duplicate information between the argparse struct in labgrid/remote/client.py and man/labgrid-client.rst which would then be translated to a manpage in man/labgrid-client.1 using rst2man and also tracked in version control. The man/labgrid-client.rst file was also sourced in doc/man/client.rst for sphinx to build html documentation of the labgrid-client cli documentation. Due to this duplication, labgrid-client command documentation was incomplete and inconsistend with argparse documentation accessible via the -h switch. Use sphinx-argparse to generate usage info from the argparse struct returned by get_parser() in labgrid/remote/client.py as part of doc/man/client.rst. Move documentation missing from the argparse struct from man/labgrid-client.1 to doc/man/client.rst. Generate both html cli documentation as well as the manpage from that. Future changes in subcommands and arguments of labgrid-client need only be documented in the argparse struct but more expansive documentation that includes markup can be added to the manpage, even to specific subcommands via the rst in doc/man. Signed-off-by: Jonas Rebmann --- doc/conf.py | 8 ++- doc/man/client.rst | 164 +++++++-------------------------------------- pyproject.toml | 1 + 3 files changed, 32 insertions(+), 141 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 831ed3f64..37aba682f 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -40,9 +40,14 @@ 'sphinx.ext.napoleon', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', + 'sphinxarg.ext', # sphinx-argparse 'sphinx.ext.autosectionlabel', 'sphinx_rtd_theme'] +# Required. Otherwise pages using sphinx-argparse will produce many warnings +# (duplicate labels due to duplicate headings such as "named arguments") +autosectionlabel_maxdepth = 3 + # Add any paths that contain templates here, relative to this directory. templates_path = ['.templates'] @@ -196,7 +201,8 @@ 'vxi11', 'pysnmp', 'kasa', - 'kasa.iot'] + 'kasa.iot', + ] # -- Options for autosection ---------------------------------------------- autosectionlabel_prefix_document = True diff --git a/doc/man/client.rst b/doc/man/client.rst index 53390fe67..671fee87d 100644 --- a/doc/man/client.rst +++ b/doc/man/client.rst @@ -1,55 +1,36 @@ .. _labgrid-client: -================ - labgrid-client -================ +labgrid-client +============== -labgrid-client interface to control boards -========================================== +Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. -SYNOPSIS --------- +This is the client to control a boards status and interface with it on remote machines. -``labgrid-client`` ``--help`` +.. currentmodule:: labgrid.remote.client -``labgrid-client`` -p -``labgrid-client`` ``places|resources`` +.. argparse:: + :module: labgrid.remote.client + :func: get_parser + :prog: labgrid-client -DESCRIPTION ------------ -Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. -This is the client to control a boards status and interface with it on remote machines. + help : @skip + skip. -OPTIONS -------- --h, --help - display command line help --p PLACE, --place PLACE - specify the place to operate on --x ADDRESS, --coordinator ADDRESS - coordinator ``HOST[:PORT]`` to connect to, defaults to ``127.0.0.1:20408`` --c CONFIG, --config CONFIG - set the configuration file --s STATE, --state STATE - set an initial state before executing a command, requires a configuration - file and strategy --i INITIAL_STATE, --initial-state INITIAL_STATE - strategy state to force into before switching to desired state, requires a - desired state (``-s``/``--state``/``LG_STATE``) --d, --debug - enable debugging --v, --verbose - increase verbosity --P PROXY, --proxy PROXY - proxy connections over ssh - -CONFIGURATION FILE + complete : @skip + skip. + + available subcommands : @skip + skip. + + +Configuration File ------------------ The configuration file follows the description in ``labgrid-device-config``\(5). -ENVIRONMENT VARIABLES +Environment Variables --------------------- Various labgrid-client commands use the following environment variable: @@ -112,7 +93,7 @@ LG_AGENT_PREFIX Add a prefix to ``.labgrid_agent_{agent_hash}.py`` allowing specification for where on the exporter it should be uploaded to. -MATCHES +Matches ------- Match patterns are used to assign a resource to a specific place. The format is: exporter/group/cls/name, exporter is the name of the exporting machine, group is @@ -120,104 +101,7 @@ a name defined within the exporter, cls is the class of the exported resource and name is its name. Wild cards in match patterns are explicitly allowed, * matches anything. -LABGRID-CLIENT COMMANDS ------------------------ -``monitor`` Monitor events from the coordinator - -``resources (r)`` List available resources - -``places (p)`` List available places - -``who`` List acquired places by user - -``show`` Show a place and related resources - -``create`` Add a new place (name supplied by -p parameter) - -``delete`` Delete an existing place - -``add-alias`` ``[alias]`` Add an alias to a place - -``del-alias`` ``[alias]`` Delete an alias from a place - -``set-comment`` ``[comment]`` Update or set the place comment - -``set-tags`` ``[key=value]`` Set place tags (key=value) - -``add-match`` ``[match]`` Add one (or multiple) match pattern(s) to a place, see MATCHES - -``del-match`` ``[match]`` Delete one (or multiple) match pattern(s) from a place, see MATCHES - -``add-named-match`` ``[match]`` ``[name]`` Add one match pattern with a name to a place - -``acquire (lock)`` Acquire a place - -``allow`` ``[user]`` Allow another user to access a place - -``release (unlock)`` Release a place - -``release-from`` ``[host/user]`` Atomically release a place, but only if acquired by a specific user. - - Note that this command returns success as long - as the specified user no longer owns the place, - meaning it may be acquired by another user or - not at all. - -``env`` Generate a labgrid environment file for a place - -``power (pw)`` ``[action]`` Change (or get) a place's power status, where action is one of get, on, off, cycle - -``io`` ``[action]`` ``[name]`` Interact with GPIO (OneWire, relays, ...) devices, where action is one of high, low, get - -``console (con)`` ``[name]`` Connect to the console - -``dfu`` ``[arg]`` Run dfu commands - -``fastboot`` ``[arg]`` Run fastboot with argument - -``flashscript`` ``[script]`` ``[arg]`` Run arbitrary script with arguments to flash device - -``bootstrap`` ``[filename]`` Start a bootloader - -``sd-mux`` ``[action]`` Switch USB SD Muxer, where action is one of dut (device-under-test), host, off - -``usb-mux`` ``[action]`` Switch USB Muxer, where action is one of off, dut-device, host-dut, host-device, host-dut+host-device - -``ssh`` ``[command]`` Connect via SSH. Additional arguments are passed to ssh. - -``scp`` ``[source]`` ``[destination]`` Transfer file via scp (use ':dir/file' for the remote side) - -``rsync`` ``[source]`` ``[destination]`` Transfer files via rsync (use ':dir/file' for the remote side) - -``sshfs`` ``[remotepath]`` ``[mountpoint]`` Mount a remote path via sshfs - -``forward`` Forward local port to remote target - -``telnet`` Connect via telnet - -``video`` Start a video stream - -``audio`` Start an audio stream - -``tmc`` ``[command]`` Control a USB TMC device - -``write-files`` ``[filename(s)]`` Copy files onto mass storage device - -``write-image`` ``[filename]`` Write images onto block devices (USBSDMux, USB Sticks, …) - -``reserve`` ``[filter]`` Create a reservation - -``cancel-reservation`` ``[token]`` Cancel a pending reservation - -``wait`` ``[token]`` Wait for a reservation to be allocated - -``reservations`` List current reservations - -``export`` ``[filename]`` Export driver information to file (needs environment with drivers) - -``version`` Print the labgrid version - -ADDING NAMED RESOURCES +Adding Named Resources ---------------------- If a target contains multiple Resources of the same type, named matches need to be used to address the individual resources. In addition to the `match` taken by @@ -229,7 +113,7 @@ given. If one of the resources should be used by default when no resource name is explicitly specified, it can be named ``default``. -EXAMPLES +Examples -------- To retrieve a list of places run: @@ -257,7 +141,7 @@ Add all resources with the group "example-group" to the place example-place: $ labgrid-client -p example-place add-match */example-group/*/* -SEE ALSO +See Also -------- ``labgrid-exporter``\(1) diff --git a/pyproject.toml b/pyproject.toml index 33caa6f31..eea48f80d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -56,6 +56,7 @@ dynamic = ["version"] # via setuptools_scm doc = [ "sphinx_rtd_theme>=1.0.0", "Sphinx>=2.0.0", + "sphinx-argparse", ] docker = ["docker>=5.0.2"] graph = ["graphviz>=0.17.0"] From e86cc61b468252674aebff2d6f13fd475ae70933 Mon Sep 17 00:00:00 2001 From: Jonas Rebmann Date: Mon, 28 Jul 2025 16:40:44 +0200 Subject: [PATCH 4/7] doc: Limit toc depth to 2 on manpage overview Doesn't look good if every Arguments list of every subcommand of every command is listed here for the manpages generated from argparse. Signed-off-by: Jonas Rebmann --- doc/man.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/man.rst b/doc/man.rst index e8fa6bd88..201a7960e 100644 --- a/doc/man.rst +++ b/doc/man.rst @@ -2,6 +2,8 @@ Manual Pages ============ .. toctree:: + :maxdepth: 2 + man/client man/coordinator man/device-config From 9d54210daba4f6d2c1fd2b605ae698d4fdfad827 Mon Sep 17 00:00:00 2001 From: Jonas Rebmann Date: Mon, 28 Jul 2025 17:09:52 +0200 Subject: [PATCH 5/7] doc: man: Add some details to subcommands The subcommands descriptions for create, release-from and flashscript had some extra details in the old rst manpages, not available in the argparse/cli help. Migrate these descriptions from the old to the new manpage by overwriting the subcommand descriptions. Keep the argparse help texts short and concise. Signed-off-by: Jonas Rebmann --- doc/man/client.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/doc/man/client.rst b/doc/man/client.rst index 671fee87d..a2b311f06 100644 --- a/doc/man/client.rst +++ b/doc/man/client.rst @@ -25,6 +25,20 @@ This is the client to control a boards status and interface with it on remote ma available subcommands : @skip skip. + create : @replace + add a new place with the name specified via ``--place`` or the + ``LG_PLACE`` environment variable. + + release-from : @replace + Atomically release a place, but only if acquired by a specific user. + + Note that this command returns success as long as the specified user no + longer owns the place, meaning it may be acquired by another user or + not at all. + + flashscript : @replace + Run arbitrary script with arguments to flash device + Configuration File ------------------ From 783c3f46c21e8c4b48fb8f5c3994fb24b83eb261 Mon Sep 17 00:00:00 2001 From: Jonas Rebmann Date: Fri, 25 Jul 2025 17:35:25 +0200 Subject: [PATCH 6/7] remote/client: sphinx-argparse 0.5.2 workarounds Hide intentionally undocumented subcommands and overlong lists of choices. PRs to fix the ineffective @skip we have for those sections and to display ranges properly are open and these workarounds should be removed once the fixes made it into a release. Signed-off-by: Jonas Rebmann --- labgrid/remote/client.py | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/labgrid/remote/client.py b/labgrid/remote/client.py index 13fd52728..202134b3b 100755 --- a/labgrid/remote/client.py +++ b/labgrid/remote/client.py @@ -1705,7 +1705,7 @@ def __str__(self): return self.value -def get_parser() -> argparse.ArgumentParser: +def get_parser(include_undocumented=False) -> argparse.ArgumentParser: parser = argparse.ArgumentParser() parser.add_argument( "-x", @@ -1744,11 +1744,12 @@ def get_parser() -> argparse.ArgumentParser: metavar="COMMAND", ) - subparser = subparsers.add_parser("help") + if include_undocumented: + subparser = subparsers.add_parser("help") - subparser = subparsers.add_parser("complete") - subparser.add_argument("type", choices=["resources", "places", "matches", "match-names"]) - subparser.set_defaults(func=ClientSession.complete) + subparser = subparsers.add_parser("complete") + subparser.add_argument("type", choices=["resources", "places", "matches", "match-names"]) + subparser.set_defaults(func=ClientSession.complete) subparser = subparsers.add_parser("monitor", help="monitor events from the coordinator") subparser.set_defaults(func=ClientSession.do_monitor) @@ -1997,7 +1998,7 @@ def get_parser() -> argparse.ArgumentParser: "-p", "--partition", type=int, - choices=range(0, 256), + choices=(range(0, 256) if include_undocumented else None), metavar="0-255", default=1, help="partition number to mount or 0 to mount whole disk (default: %(default)s)", @@ -2091,7 +2092,7 @@ def main(): initial_state = os.environ.get("LG_INITIAL_STATE", None) token = os.environ.get("LG_TOKEN", None) - parser = get_parser() + parser = get_parser(include_undocumented=True) # make any leftover arguments available for some commands args, leftover = parser.parse_known_args() From d2f2131b3aadd97e5d67ba6d05b08bd7a2af8a7e Mon Sep 17 00:00:00 2001 From: Jonas Rebmann Date: Tue, 29 Jul 2025 16:05:55 +0200 Subject: [PATCH 7/7] doc: man: disable printing default values via sphinx-argparse Since the defaults are mentioned in the help text where they're relevant, don't let sphinx-argparse print them again. Signed-off-by: Jonas Rebmann --- doc/man/client.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/man/client.rst b/doc/man/client.rst index a2b311f06..2362e2729 100644 --- a/doc/man/client.rst +++ b/doc/man/client.rst @@ -14,6 +14,7 @@ This is the client to control a boards status and interface with it on remote ma :module: labgrid.remote.client :func: get_parser :prog: labgrid-client + :nodefault: help : @skip