diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index cfcdc7503..58484d536 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -33,7 +33,7 @@ Did you test the change locally? If yes, best to mention how you did it in the d ---> - [ ] PR has been tested - [ ] Man pages have been regenerated diff --git a/README.rst b/README.rst index 2ae9aafda..5cf33889b 100644 --- a/README.rst +++ b/README.rst @@ -135,6 +135,11 @@ Tests can now run via: venv $ python -m pytest --lg-env +To install sphinx and the dependencies needed for generating man pages and documentation run: + +.. code-block:: bash + + venv $ pip install '.[doc]' .. |license| image:: https://img.shields.io/badge/license-LGPLv2.1-blue.svg :alt: LGPLv2.1 diff --git a/doc/conf.py b/doc/conf.py index 29ff581b9..9cfa65022 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -21,7 +21,7 @@ import sys sys.path.insert(0, os.path.abspath('..')) -from importlib.metadata import version +from importlib import metadata # Import read_the_docs theme import sphinx_rtd_theme @@ -40,6 +40,7 @@ 'sphinx.ext.napoleon', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', + 'sphinxcontrib.autoprogram', 'sphinx.ext.autosectionlabel', 'sphinx_rtd_theme'] @@ -65,7 +66,7 @@ # built documents. # # The full version, including alpha/beta/rc tags. -release = version('labgrid') +release = metadata.version('labgrid') # The short X.Y version. version = '.'.join(release.split('.')[:2]) @@ -156,7 +157,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), ] @@ -185,7 +198,11 @@ autodoc_mock_imports = ['onewire', 'gi', 'gi.repository', - 'vxi11'] + 'vxi11', + 'pysnmp', + 'kasa', + 'kasa.iot', + ] # -- Options for autosection ---------------------------------------------- autosectionlabel_prefix_document = True @@ -203,6 +220,10 @@ def run_apidoc(app): main(cmd) def setup(app): + # Make version and date stable when generating manpages as they will be tracked in git + if app.outdir.parts[-1] == "man": + app.config.version = "" + app.config.today_fmt = "%Y" app.connect('builder-inited', run_apidoc) app.connect('doctree-read', write_literal_blocks) diff --git a/doc/man.rst b/doc/man.rst index e6d6f6360..86984cd4c 100644 --- a/doc/man.rst +++ b/doc/man.rst @@ -2,7 +2,10 @@ Manual Pages ============ .. toctree:: + :maxdepth: 2 + man/client + man/coordinator man/device-config man/exporter - man/coordinator + man/suggest diff --git a/doc/man/client.rst b/doc/man/client.rst index bb9ce9f67..309e36365 100644 --- a/doc/man/client.rst +++ b/doc/man/client.rst @@ -1,2 +1,134 @@ .. _labgrid-client: -.. include:: ../../man/labgrid-client.rst + +labgrid-client CLI +================== + +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. + +.. currentmodule:: labgrid.remote.client + + +.. autoprogram:: labgrid.remote.client:get_parser(auto_doc_mode=True) + :prog: labgrid-client + +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. + +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..d0e5ff914 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..c30ca3180 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..69bda443c 100644 --- a/man/labgrid-pytest.rst +++ b/doc/man/pytest.rst @@ -1,3 +1,5 @@ +:orphan: + ================ labgrid-pytest ================ @@ -5,17 +7,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/labgrid/remote/client.py b/labgrid/remote/client.py index 9b6e602da..576e172fc 100755 --- a/labgrid/remote/client.py +++ b/labgrid/remote/client.py @@ -1758,26 +1758,58 @@ def __str__(self): return self.value -def main(): - import inspect +class AutoProgramArgumentParser(argparse.ArgumentParser): + """Works around sphinxcontrib.autoprogram shortcomings.""" - basicConfig( - level=logging.WARNING, - stream=sys.stderr, - ) + class _ActionWrapper: + """ + Wraps argparse's special private action object registered for "parsers", see: + https://docs.python.org/3.14/library/argparse.html#argparse.ArgumentParser.add_subparsers + https://docs.python.org/3.13/library/argparse.html#argparse.ArgumentParser.register + """ - StepLogger.start() - processwrapper.enable_logging() + def __init__(self, action): + self.action = action - # 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 add_parser(self, name, **kwargs): + # aliases are not supported by autoprogram, they lead to duplicate entries, so + # show them as "command subcommand|alias --option" instead + aliases = kwargs.pop("aliases", []) + if aliases: + name = "|".join([name] + list(aliases)) + + # "help" text is ignored by autoprogram, move to "description" instead + if "description" not in kwargs and "help" in kwargs: + kwargs["description"] = kwargs.pop("help") + + # add_parser() is the only part of the action object that's not an implementation detail + return self.action.add_parser(name, **kwargs) + + def __init__(self, *args, **kwargs): + # print help texts in fixed width + os.environ["COLUMNS"] = "80" + + # hide --help, -h + kwargs.setdefault("add_help", False) + + super().__init__(*args, **kwargs) + + def add_subparsers(self, **kwargs): + action = super().add_subparsers(**kwargs) + return self._ActionWrapper(action) + + def add_argument(self, *args, **kwargs): + # do not show ranges + if isinstance(kwargs.get("choices"), range): + del kwargs["choices"] + + return super().add_argument(*args, **kwargs) + + +def get_parser(auto_doc_mode=False) -> "argparse.ArgumentParser | AutoProgramArgumentParser": + # use custom parser for sphinxcontrib.autoprogram + parser = AutoProgramArgumentParser() if auto_doc_mode else argparse.ArgumentParser() - parser = argparse.ArgumentParser() parser.add_argument( "-x", "--coordinator", @@ -1789,24 +1821,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( @@ -1820,11 +1847,13 @@ def main(): metavar="COMMAND", ) - subparser = subparsers.add_parser("help") + # if the argparse object is to be used for manpage generation, hide some subcommands + if not auto_doc_mode: + 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) @@ -1855,7 +1884,10 @@ def main(): subparser = subparsers.add_parser("show", help="show a place and related resources") subparser.set_defaults(func=ClientSession.print_place) - subparser = subparsers.add_parser("create", help="add a new place") + subparser = subparsers.add_parser( + "create", + help="add a new place with the name specified via --place or the LG_PLACE environment variable", + ) subparser.set_defaults(func=ClientSession.add_place) subparser = subparsers.add_parser("delete", help="delete an existing place") @@ -1903,7 +1935,10 @@ def main(): subparser.set_defaults(func=ClientSession.release) subparser = subparsers.add_parser( - "release-from", help="atomically release a place, but only if locked by a specific user" + "release-from", + help="atomically release a place, but only if locked by a specific user", + epilog="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.", ) subparser.add_argument("acquired", metavar="HOST/USER", help="User and host to match against when releasing") subparser.set_defaults(func=ClientSession.release_from) @@ -1953,7 +1988,7 @@ def main(): subparser.add_argument("--name", "-n", help="optional resource name") subparser.set_defaults(func=ClientSession.fastboot) - subparser = subparsers.add_parser("flashscript", help="run flash script") + subparser = subparsers.add_parser("flashscript", help="Run arbitrary script with arguments to flash device") subparser.add_argument("script", help="Flashing script") subparser.add_argument("script_args", metavar="ARG", nargs=argparse.REMAINDER, help="script arguments") subparser.add_argument("--name", "-n", help="optional resource name") @@ -2120,11 +2155,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") @@ -2147,6 +2182,30 @@ def main(): subparser = subparsers.add_parser("version", help="show version") subparser.set_defaults(func=ClientSession.print_version) + return parser + + +def main(): + import inspect + + 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"]: @@ -2154,6 +2213,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: 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 index 630511c34..fdc62be72 100644 --- a/man/labgrid-client.1 +++ b/man/labgrid-client.1 @@ -27,52 +27,1056 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" 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" +.TH "LABGRID-CLIENT" "1" "2025" "" "labgrid" .SH NAME -labgrid-client \- labgrid-client interface to control boards -.SH SYNOPSIS +labgrid-client \- labgrid's client interface to control boards .sp -\fBlabgrid\-client\fP \fB\-\-help\fP +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 LABGRID-CLIENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client [\-x ADDRESS] [\-c CONFIG] [\-p PLACE] [\-s STATE] + [\-i INITIAL_STATE] [\-d] [\-v] [\-P PROXY] + COMMAND ... +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-x
, \-\-coordinator
+coordinator HOST[:PORT] (default: value from env variable LG_COORDINATOR, otherwise 127.0.0.1:20408) +.UNINDENT +.INDENT 0.0 +.TP +.B \-c , \-\-config +env config file (default: value from env variable LG_ENV) +.UNINDENT +.INDENT 0.0 +.TP +.B \-p , \-\-place +place name/alias (default: value from env variable LG_PLACE) +.UNINDENT +.INDENT 0.0 +.TP +.B \-s , \-\-state +strategy state to switch into before command (default: value from env varibale LG_STATE) +.UNINDENT +.INDENT 0.0 +.TP +.B \-i , \-\-initial\-state +strategy state to force into before switching to desired state +.UNINDENT +.INDENT 0.0 +.TP +.B \-d, \-\-debug +enable debug mode (show python tracebacks) +.UNINDENT +.INDENT 0.0 +.TP +.B \-v, \-\-verbose +.UNINDENT +.INDENT 0.0 +.TP +.B \-P , \-\-proxy +proxy connections via given ssh host +.UNINDENT +.SS labgrid\-client acquire|lock +.sp +acquire a place +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client acquire|lock [\-\-allow\-unmatched] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-allow\-unmatched +allow missing resources for matches when locking the place +.UNINDENT +.SS labgrid\-client add\-alias +.sp +add an alias to a place +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client add\-alias alias +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B alias +.UNINDENT +.SS labgrid\-client add\-match +.sp +add one (or multiple) match pattern(s) to a place +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client add\-match PATTERN [PATTERN ...] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B pattern +.UNINDENT +.SS labgrid\-client add\-named\-match +.sp +add one match pattern with a name to a place +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client add\-named\-match PATTERN NAME +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B pattern +.UNINDENT +.INDENT 0.0 +.TP +.B name +.UNINDENT +.SS labgrid\-client allow +.sp +allow another user to access a place +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client allow user +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B user +/ +.UNINDENT +.SS labgrid\-client audio +.sp +start a audio stream +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client audio [\-\-name NAME] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client bootstrap +.sp +start a bootloader +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client bootstrap [\-w WAIT] [\-\-name NAME] filename ... +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B filename +filename to boot on the target +.UNINDENT +.INDENT 0.0 +.TP +.B arg +extra bootstrap arguments +.UNINDENT +.INDENT 0.0 +.TP +.B \-w , \-\-wait +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client cancel\-reservation +.sp +cancel a reservation +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client cancel\-reservation [token] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B token +.UNINDENT +.SS labgrid\-client console|con +.sp +connect to the console +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client console|con [\-l] [\-o] [\-\-logfile FILE] [name] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B name +optional resource name +.UNINDENT +.INDENT 0.0 +.TP +.B \-l, \-\-loop +keep trying to connect if the console is unavailable +.UNINDENT +.INDENT 0.0 +.TP +.B \-o, \-\-listenonly +do not modify local terminal, do not send input from stdin +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-logfile +Log output to FILE +.UNINDENT +.SS labgrid\-client create +.sp +add a new place with the name specified via \-\-place or the LG_PLACE environment variable +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client create +.EE +.UNINDENT +.UNINDENT +.SS labgrid\-client del\-alias +.sp +delete an alias from a place +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client del\-alias alias +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B alias +.UNINDENT +.SS labgrid\-client del\-match +.sp +delete one (or multiple) match pattern(s) from a place +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client del\-match PATTERN [PATTERN ...] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B pattern +.UNINDENT +.SS labgrid\-client delete +.sp +delete an existing place +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client delete +.EE +.UNINDENT +.UNINDENT +.SS labgrid\-client dfu +.sp +communicate with device in DFU mode +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client dfu [\-\-wait WAIT] [\-\-name NAME] + {download,detach,list} [altsetting] [filename] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B action +action +.UNINDENT +.INDENT 0.0 +.TP +.B altsetting +altsetting name or number (download, detach only) +.UNINDENT +.INDENT 0.0 +.TP +.B filename +file to write into device (download only) +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-wait +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client env +.sp +generate a labgrid environment file for a place +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client env +.EE +.UNINDENT +.UNINDENT +.SS labgrid\-client export +.sp +export driver information to a file (needs environment with drivers) +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client export [\-\-format {shell,shell\-export,json}] filename +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B filename +output filename +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-format {shell,shell\-export,json} +output format (default: shell\-export) +.UNINDENT +.SS labgrid\-client fastboot +.sp +run fastboot +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client fastboot [\-\-wait WAIT] [\-\-name NAME] ... +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B arg +fastboot arguments +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-wait +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client flashscript +.sp +Run arbitrary script with arguments to flash device +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client flashscript [\-\-name NAME] script ... +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B script +Flashing script +.UNINDENT +.INDENT 0.0 +.TP +.B arg +script arguments +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client forward +.sp +forward local port to remote target +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client forward [\-\-name NAME] [\-\-local [LOCAL:]REMOTE] + [\-\-remote REMOTE:LOCAL] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-local, \-L +Forward local port LOCAL to remote port REMOTE. If LOCAL is unspecified, an arbitrary port will be chosen +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-remote, \-R +Forward remote port REMOTE to local port LOCAL +.UNINDENT +.SS labgrid\-client io +.sp +change (or get) a digital IO status +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client io {high,low,get} [name] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B action +action +.UNINDENT +.INDENT 0.0 +.TP +.B name +optional resource name +.UNINDENT +.SS labgrid\-client monitor +.sp +monitor events from the coordinator +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client monitor +.EE +.UNINDENT +.UNINDENT +.SS labgrid\-client places|p +.sp +list available places +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client places|p [\-a] [\-r] [\-\-sort\-last\-changed] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-a, \-\-acquired +.UNINDENT +.INDENT 0.0 +.TP +.B \-r, \-\-released +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-sort\-last\-changed +sort by last changed date (oldest first) +.UNINDENT +.SS labgrid\-client power|pw +.sp +change (or get) a place\(aqs power status +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client power|pw [\-t DELAY] [\-\-name NAME] {on,off,cycle,get} +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B action +.UNINDENT +.INDENT 0.0 +.TP +.B \-t , \-\-delay +wait time in seconds between off and on during cycle +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client release\-from +.sp +atomically release a place, but only if locked by a specific user +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client release\-from HOST/USER +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B host/user +User and host to match against when releasing +.UNINDENT +.sp +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. +.SS labgrid\-client release|unlock +.sp +release a place +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client release|unlock [\-k] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-k, \-\-kick +release a place even if it is acquired by a different user +.UNINDENT +.SS labgrid\-client reservations +.sp +list current reservations +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client reservations +.EE +.UNINDENT +.UNINDENT +.SS labgrid\-client reserve +.sp +create a reservation +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client reserve [\-\-wait] [\-\-shell] [\-\-prio PRIO] + KEY=VALUE [KEY=VALUE ...] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B key=value +required tags +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-wait +wait until the reservation is allocated +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-shell +format output as shell variables +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-prio +priority relative to other reservations (default 0) +.UNINDENT +.SS labgrid\-client resources|r +.sp +list available resources +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client resources|r [\-a] [\-e EXPORTER] + [\-\-sort\-by\-matched\-place\-change] + [match] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B match +.UNINDENT +.INDENT 0.0 +.TP +.B \-a, \-\-acquired +.UNINDENT +.INDENT 0.0 +.TP +.B \-e , \-\-exporter +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-sort\-by\-matched\-place\-change +sort by matched place\(aqs changed date (oldest first) and show place and date +.UNINDENT +.SS labgrid\-client rsync +.sp +transfer files via rsync +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client rsync [\-\-name NAME] src dst +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B src +source path (use :dir/file for remote side) +.UNINDENT +.INDENT 0.0 +.TP +.B dst +destination path (use :dir/file for remote side) +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.sp +Additional arguments are passed to the rsync subprocess. +.SS labgrid\-client scp +.sp +transfer file via scp +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client scp [\-\-name NAME] src dst +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B src +source path (use :dir/file for remote side) +.UNINDENT +.INDENT 0.0 +.TP +.B dst +destination path (use :dir/file for remote side) +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client sd\-mux +.sp +switch USB SD Muxer or get current mode +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client sd\-mux [\-\-name NAME] {dut,host,off,client,get} +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B action +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client set\-comment +.sp +update the place comment +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client set\-comment comment [comment ...] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B comment +.UNINDENT +.SS labgrid\-client set\-tags +.sp +update the place tags +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client set\-tags KEY=VALUE [KEY=VALUE ...] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B key=value +use an empty value for deletion +.UNINDENT +.SS labgrid\-client show +.sp +show a place and related resources +.INDENT 0.0 +.INDENT 3.5 .sp -\fBlabgrid\-client\fP \-p +.EX +usage: labgrid\-client show +.EE +.UNINDENT +.UNINDENT +.SS labgrid\-client ssh .sp -\fBlabgrid\-client\fP \fBplaces|resources\fP -.SH DESCRIPTION +connect via ssh (with optional arguments) +.INDENT 0.0 +.INDENT 3.5 .sp -Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. +.EX +usage: labgrid\-client ssh [\-\-name NAME] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT .sp -This is the client to control a boards status and interface with it on remote machines. -.SH OPTIONS +Additional arguments are passed to the ssh subprocess. +.SS labgrid\-client sshfs +.sp +mount via sshfs (blocking) +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client sshfs [\-\-name NAME] path mountpoint +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B path +remote path on the target +.UNINDENT +.INDENT 0.0 +.TP +.B mountpoint +local path +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client telnet +.sp +connect via telnet +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client telnet +.EE +.UNINDENT +.UNINDENT +.SS labgrid\-client tmc +.sp +control a USB TMC device +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client tmc [\-\-name NAME] SUBCOMMAND ... +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client tmc channel +.sp +use a channel +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client tmc channel channel {info,values} +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B channel +.UNINDENT +.INDENT 0.0 +.TP +.B action +.UNINDENT +.SS labgrid\-client tmc cmd|c +.sp +execute raw command +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client tmc cmd|c command [command ...] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B command +.UNINDENT +.SS labgrid\-client tmc query|q +.sp +execute raw query +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client tmc query|q query [query ...] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B query +.UNINDENT +.SS labgrid\-client tmc screen +.sp +show or save a screenshot +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client tmc screen {show,save} +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B action +.UNINDENT +.SS labgrid\-client usb\-mux +.sp +switch USB Muxer +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client usb\-mux [\-\-name NAME] + {off,dut\-device,host\-dut,host\-device,host\-dut+host\-device} +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B links +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client version +.sp +show version +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client version +.EE +.UNINDENT +.UNINDENT +.SS labgrid\-client video +.sp +start a video stream +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client video [\-q QUALITY] [\-c CONTROLS] [\-\-name NAME] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-q , \-\-quality +select a video quality (use \(aqlist\(aq to show options) +.UNINDENT +.INDENT 0.0 +.TP +.B \-c , \-\-controls +configure v4l controls (such as \(aqfocus_auto=0,focus_absolute=40\(aq) +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client wait +.sp +wait for a reservation to be allocated +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client wait [token] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B token +.UNINDENT +.SS labgrid\-client who +.sp +list acquired places by user +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client who [\-e] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-e, \-\-show\-exporters +show exporters currently used by each place +.UNINDENT +.SS labgrid\-client write\-files +.sp +copy files onto mass storage device +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client write\-files [OPTION]... \-T SOURCE DEST + labgrid\-client write\-files [OPTION]... [\-t DIRECTORY] SOURCE... +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B source +source file(s) to copy +.UNINDENT +.INDENT 0.0 +.TP +.B dest +destination file name for SOURCE +.UNINDENT +.INDENT 0.0 +.TP +.B \-w , \-\-wait +storage poll timeout in seconds +.UNINDENT +.INDENT 0.0 +.TP +.B \-p <0\-255>, \-\-partition <0\-255> +partition number to mount or 0 to mount whole disk (default: 1) +.UNINDENT .INDENT 0.0 .TP -.B \-h\fP,\fB \-\-help -display command line help +.B \-t , \-\-target\-directory +copy all SOURCE files into DIRECTORY (default: partition root) +.UNINDENT +.INDENT 0.0 +.TP +.B \-T +copy SOURCE file and rename to DEST +.UNINDENT +.INDENT 0.0 .TP -.BI \-p \ PLACE\fR,\fB \ \-\-place \ PLACE -specify the place to operate on +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client write\-image +.sp +write an image onto mass storage +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client write\-image [\-w WAIT] [\-p PARTITION] [\-\-skip SKIP] + [\-\-seek SEEK] [\-\-mode {dd,bmaptool}] + [\-\-name NAME] + filename +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 .TP -.BI \-x \ ADDRESS\fR,\fB \ \-\-coordinator \ ADDRESS -coordinator \fBHOST[:PORT]\fP to connect to, defaults to \fB127.0.0.1:20408\fP +.B filename +filename to boot on the target +.UNINDENT +.INDENT 0.0 .TP -.BI \-c \ CONFIG\fR,\fB \ \-\-config \ CONFIG -set the configuration file +.B \-w , \-\-wait +.UNINDENT +.INDENT 0.0 .TP -.BI \-s \ STATE\fR,\fB \ \-\-state \ STATE -set an initial state before executing a command, requires a configuration -file and strategy +.B \-p , \-\-partition +partition number to write to +.UNINDENT +.INDENT 0.0 .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) +.B \-\-skip +skip n 512\-sized blocks at start of input +.UNINDENT +.INDENT 0.0 .TP -.B \-d\fP,\fB \-\-debug -enable debugging +.B \-\-seek +skip n 512\-sized blocks at start of output +.UNINDENT +.INDENT 0.0 .TP -.B \-v\fP,\fB \-\-verbose -increase verbosity +.B \-\-mode {dd,bmaptool} +Choose tool for writing images (default: dd) +.UNINDENT +.INDENT 0.0 .TP -.BI \-P \ PROXY\fR,\fB \ \-\-proxy \ PROXY -proxy connections over ssh +.B \-\-name , \-n +optional resource name .UNINDENT .SH CONFIGURATION FILE .sp @@ -135,105 +1139,6 @@ 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 @@ -291,14 +1196,8 @@ $ labgrid\-client \-p example\-place add\-match */example\-group/*/* .sp \fBlabgrid\-exporter\fP(1) .SH AUTHOR -Rouven Czerwinski - -Organization: Labgrid-Project +Jan Luebbe, Rouven Czerwinski .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. +2016-2025 Pengutronix, Jan Luebbe and Rouven Czerwinski .\" Generated by docutils manpage writer. . diff --git a/man/labgrid-client.rst b/man/labgrid-client.rst deleted file mode 100644 index 59f43c5a6..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 index 0595b3098..e99c30f93 100644 --- a/man/labgrid-coordinator.1 +++ b/man/labgrid-coordinator.1 @@ -27,13 +27,14 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" 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" +.TH "LABGRID-COORDINATOR" "1" "2025" "" "labgrid" .SH NAME -labgrid-coordinator \- labgrid-coordinator managing labgrid resources and places -.SH SYNOPSIS +labgrid-coordinator \- managing labgrid resources and places +.SH LABGRID-COORDINATOR MANAGING LABGRID RESOURCES AND PLACES +.SS SYNOPSIS .sp \fBlabgrid\-coordinator\fP \fB\-\-help\fP -.SH DESCRIPTION +.SS DESCRIPTION .sp Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. @@ -41,7 +42,7 @@ 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. -.SH OPTIONS +.SS OPTIONS .INDENT 0.0 .TP .B \-h\fP,\fB \-\-help @@ -53,18 +54,12 @@ make coordinator listen on host and port .B \-d\fP,\fB \-\-debug enable debug mode .UNINDENT -.SH SEE ALSO +.SS SEE ALSO .sp \fBlabgrid\-client\fP(1), \fBlabgrid\-exporter\fP(1) .SH AUTHOR -Rouven Czerwinski - -Organization: Labgrid-Project +Jan Luebbe, Rouven Czerwinski .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. +2016-2025 Pengutronix, Jan Luebbe and Rouven Czerwinski .\" 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 index 459756b9c..0755927de 100644 --- a/man/labgrid-device-config.5 +++ b/man/labgrid-device-config.5 @@ -27,19 +27,20 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" 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" +.TH "LABGRID-DEVICE-CONFIG" "5" "2025" "" "labgrid" .SH NAME -labgrid-device-config \- labgrid test configuration files -.SH SYNOPSIS +labgrid-device-config \- test configuration files +.SH LABGRID TEST CONFIGURATION FILES +.SS SYNOPSIS .sp \fB*.yaml\fP -.SH DESCRIPTION +.SS 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 +.SS TARGETS .sp The \fBtargets:\fP top key configures a \fBtarget\fP, it\(aqs \fBdrivers\fP and \fBresources\fP\&. .sp @@ -49,8 +50,8 @@ 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 +\X'tty: link https://labgrid.readthedocs.io/en/latest/configuration.html'\fI\%https://labgrid.readthedocs.io/en/latest/configuration.html\fP\X'tty: link'\&. +.SS OPTIONS .sp The \fBoptions:\fP top key configures various options such as the coordinator_address. .SS OPTIONS KEYS @@ -60,7 +61,7 @@ The \fBoptions:\fP top key configures various options such as the coordinator_ad takes as parameter the coordinator \fBHOST[:PORT]\fP to connect to. Defaults to \fB127.0.0.1:20408\fP\&. .UNINDENT -.SH IMAGES +.SS 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 @@ -82,7 +83,7 @@ images: .EE .UNINDENT .UNINDENT -.SH TOOLS +.SS TOOLS .sp The \fBtools:\fP top key provides paths to binaries such as fastboot. .SS TOOLS KEYS @@ -90,95 +91,95 @@ The \fBtools:\fP top key provides paths to binaries such as fastboot. .TP .B \fBdfu\-util\fP Path to the dfu\-util binary, used by the DFUDriver. -See: +See: \X'tty: link https://dfu-util.sourceforge.net/'\fI\%https://dfu\-util.sourceforge.net/\fP\X'tty: link' .TP .B \fBdpcmd\fP Path to the dpcmd binary, used by the DediprogFlashDriver. -See: +See: \X'tty: link https://github.com/DediProgSW/SF100Linux'\fI\%https://github.com/DediProgSW/SF100Linux\fP\X'tty: link' .TP .B \fBfastboot\fP Path to the fastboot binary, used by the AndroidFastbootDriver. -See: +See: \X'tty: link https://developer.android.com/studio/releases/platform-tools'\fI\%https://developer.android.com/studio/releases/platform\-tools\fP\X'tty: link' .TP .B \fBflashrom\fP Path to the flashrom binary, used by the FlashromDriver. -See: +See: \X'tty: link https://www.flashrom.org/'\fI\%https://www.flashrom.org/\fP\X'tty: link' .TP .B \fBimx_usb\fP Path to the imx_usb binary, used by the BDIMXUSBDriver. -See: +See: \X'tty: link https://github.com/boundarydevices/imx_usb_loader'\fI\%https://github.com/boundarydevices/imx_usb_loader\fP\X'tty: link' .TP .B \fBimx\-usb\-loader\fP Path to the imx\-usb\-loader binary, used by the IMXUSBDriver. -See: +See: \X'tty: link https://git.pengutronix.de/cgit/barebox/tree/scripts/imx/imx-usb-loader.c'\fI\%https://git.pengutronix.de/cgit/barebox/tree/scripts/imx/imx\-usb\-loader.c\fP\X'tty: link' .TP .B \fBjtagconfig\fP Path to the jtagconfig binary, used by the QuartusHPSDriver. -See: +See: \X'tty: link https://www.intel.com/content/www/us/en/docs/programmable/683689/current/jtagconfig.html'\fI\%https://www.intel.com/content/www/us/en/docs/programmable/683689/current/jtagconfig.html\fP\X'tty: link' .TP .B \fBmxs\-usb\-loader\fP Path to the mxs\-usb\-loader binary, used by the MXSUSBDriver. -See: +See: \X'tty: link https://git.pengutronix.de/cgit/barebox/tree/scripts/mxs-usb-loader.c?h=v2017.03.0'\fI\%https://git.pengutronix.de/cgit/barebox/tree/scripts/mxs\-usb\-loader.c?h=v2017.03.0\fP\X'tty: link' .TP .B \fBopenocd\fP Path to the openocd binary, used by the OpenOCDDriver. -See: +See: \X'tty: link https://openocd.org/'\fI\%https://openocd.org/\fP\X'tty: link' .TP .B \fBquartus_hps\fP Path to the quartus_hps binary, used by the QuartusHPSDriver. -See: +See: \X'tty: link https://www.intel.com/content/www/us/en/docs/programmable/683039/22-3/hps-flash-programmer.html'\fI\%https://www.intel.com/content/www/us/en/docs/programmable/683039/22\-3/hps\-flash\-programmer.html\fP\X'tty: link' .TP .B \fBrk\-usb\-loader\fP Path to the rk\-usb\-loader binary, used by the RKUSBDriver. -See: +See: \X'tty: link https://git.pengutronix.de/cgit/barebox/tree/scripts/rk-usb-loader.c'\fI\%https://git.pengutronix.de/cgit/barebox/tree/scripts/rk\-usb\-loader.c\fP\X'tty: link' .TP .B \fBrsync\fP Path to the rsync binary, used by the SSHDriver. -See: +See: \X'tty: link https://github.com/rsyncproject/rsync'\fI\%https://github.com/rsyncproject/rsync\fP\X'tty: link' .TP .B \fBscp\fP Path to the scp binary, used by the SSHDriver. -See: +See: \X'tty: link https://github.com/openssh/openssh-portable'\fI\%https://github.com/openssh/openssh\-portable\fP\X'tty: link' .TP .B \fBsd\-mux\-ctrl\fP Path to the sd\-mux\-ctrl binary, used by the USBSDWireDriver. -See: +See: \X'tty: link https://git.tizen.org/cgit/tools/testlab/sd-mux/'\fI\%https://git.tizen.org/cgit/tools/testlab/sd\-mux/\fP\X'tty: link' .TP .B \fBsispmctl\fP Path to the sispmctl binary, used by the SiSPMPowerDriver. -See: +See: \X'tty: link https://sispmctl.sourceforge.net/'\fI\%https://sispmctl.sourceforge.net/\fP\X'tty: link' .TP .B \fBssh\fP Path to the ssh binary, used by the SSHDriver. -See: +See: \X'tty: link https://github.com/openssh/openssh-portable'\fI\%https://github.com/openssh/openssh\-portable\fP\X'tty: link' .TP .B \fBsshfs\fP Path to the sshfs binary, used by the SSHDriver. -See: +See: \X'tty: link https://github.com/libfuse/sshfs'\fI\%https://github.com/libfuse/sshfs\fP\X'tty: link' .TP .B \fBuhubctl\fP Path to the uhubctl binary, used by the USBPowerDriver. -See: +See: \X'tty: link https://github.com/mvp/uhubctl'\fI\%https://github.com/mvp/uhubctl\fP\X'tty: link' .TP .B \fBusbmuxctl\fP Path to the usbmuxctl tool, used by the LXAUSBMuxDriver. - +\X'tty: link https://github.com/linux-automation/usbmuxctl'\fI\%https://github.com/linux\-automation/usbmuxctl\fP\X'tty: link' .TP .B \fBusbsdmux\fP Path to the usbsdmux tool, used by the USBSDMuxDriver. -See: +See: \X'tty: link https://github.com/linux-automation/usbsdmux'\fI\%https://github.com/linux\-automation/usbsdmux\fP\X'tty: link' .TP .B \fBuuu\-loader\fP Path to the uuu\-loader binary, used by the UUUDriver. -See: +See: \X'tty: link https://github.com/nxp-imx/mfgtools'\fI\%https://github.com/nxp\-imx/mfgtools\fP\X'tty: link' .TP .B \fBykushcmd\fP Path to the ykushcmd binary, used by the YKUSHPowerDriver. -See: +See: \X'tty: link https://github.com/Yepkit/ykush'\fI\%https://github.com/Yepkit/ykush\fP\X'tty: link' .UNINDENT .sp The QEMUDriver expects a custom key set via its \fBqemu_bin\fP argument. -See +See \X'tty: link https://www.qemu.org/'\fI\%https://www.qemu.org/\fP\X'tty: link' .SS TOOLS EXAMPLE .sp Configure the tool path for \fBimx\-usb\-loader\fP: @@ -191,7 +192,7 @@ tools: .EE .UNINDENT .UNINDENT -.SH IMPORTS +.SS IMPORTS .sp The \fBimports\fP key is a list of files or python modules which are imported by the environment after loading the configuration. @@ -210,7 +211,7 @@ imports: .EE .UNINDENT .UNINDENT -.SH EXAMPLES +.SS EXAMPLES .sp A sample configuration with one \fBmain\fP target, accessible via SerialPort \fB/dev/ttyUSB0\fP, allowing usage of the ShellDriver: @@ -260,18 +261,12 @@ imports: .EE .UNINDENT .UNINDENT -.SH SEE ALSO +.SS SEE ALSO .sp \fBlabgrid\-client\fP(1), \fBlabgrid\-exporter\fP(1) .SH AUTHOR -Rouven Czerwinski - -Organization: Labgrid-Project +Jan Luebbe, Rouven Czerwinski .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. +2016-2025 Pengutronix, Jan Luebbe and Rouven Czerwinski .\" Generated by docutils manpage writer. . diff --git a/man/labgrid-device-config.rst b/man/labgrid-device-config.rst deleted file mode 100644 index aad5bb402..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 index 074b51db2..92619f4d1 100644 --- a/man/labgrid-exporter.1 +++ b/man/labgrid-exporter.1 @@ -27,21 +27,22 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" 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" +.TH "LABGRID-EXPORTER" "1" "2025" "" "labgrid" .SH NAME -labgrid-exporter \- labgrid-exporter interface to control boards -.SH SYNOPSIS +labgrid-exporter \- interface to control boards +.SH LABGRID-EXPORTER INTERFACE TO CONTROL BOARDS +.SS SYNOPSIS .sp \fBlabgrid\-exporter\fP \fB\-\-help\fP .sp \fBlabgrid\-exporter\fP \fB*.yaml\fP -.SH DESCRIPTION +.SS 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 +.SS OPTIONS .INDENT 0.0 .TP .B \-h\fP,\fB \-\-help @@ -91,20 +92,20 @@ override this default with another name (or an IP address). 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 +.SS CONFIGURATION .sp The exporter uses a YAML configuration file which defines groups of related resources. -See < > +See <\X'tty: link https://labgrid.readthedocs.io/en/latest/configuration.html#exporter-configuration'\fI\%https://labgrid.readthedocs.io/en/latest/configuration.html#exporter\-configuration\fP\X'tty: link'> for more information. -.SH ENVIRONMENT VARIABLES +.SS 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 +.SS EXAMPLES .sp Start the exporter with the configuration file \fBmy\-config.yaml\fP: .INDENT 0.0 @@ -125,18 +126,12 @@ $ labgrid\-exporter \-n myname my\-config.yaml .EE .UNINDENT .UNINDENT -.SH SEE ALSO +.SS SEE ALSO .sp \fBlabgrid\-client\fP(1), \fBlabgrid\-device\-config\fP(5) .SH AUTHOR -Rouven Czerwinski - -Organization: Labgrid-Project +Jan Luebbe, Rouven Czerwinski .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. +2016-2025 Pengutronix, Jan Luebbe and Rouven Czerwinski .\" Generated by docutils manpage writer. . diff --git a/man/labgrid-exporter.rst b/man/labgrid-exporter.rst deleted file mode 100644 index 72b08fcd7..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 index 0d0c263a5..8b62ad8ce 100644 --- a/man/labgrid-pytest.7 +++ b/man/labgrid-pytest.7 @@ -27,13 +27,14 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" 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" +.TH "LABGRID-PYTEST" "7" "2025" "" "labgrid" .SH NAME -labgrid-pytest \- labgrid-pytest labgrid integration for pytest -.SH SYNOPSIS +labgrid-pytest \- labgrid integration for pytest +.SH LABGRID-PYTEST LABGRID INTEGRATION FOR PYTEST +.SS SYNOPSIS .sp \fBpytest \-\-lg\-env\fP \fB*.yaml\fP -.SH DESCRIPTION +.SS 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. @@ -42,8 +43,8 @@ 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 +\X'tty: link https://labgrid.readthedocs.io/en/latest/usage.html#pytest-plugin'\fI\%https://labgrid.readthedocs.io/en/latest/usage.html#pytest\-plugin\fP\X'tty: link'\&. +.SS EXAMPLES .sp Start tests with \fBmyconfig.yaml\fP and directory \fBtests\fP: .INDENT 0.0 @@ -54,18 +55,12 @@ $ pytest \-\-lg\-env myconfig.yaml tests .EE .UNINDENT .UNINDENT -.SH SEE ALSO +.SS SEE ALSO .sp \fBlabgrid\-device\-config\fP(5) .SH AUTHOR -Rouven Czerwinski - -Organization: Labgrid-Project +Jan Luebbe, Rouven Czerwinski .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. +2016-2025 Pengutronix, Jan Luebbe and Rouven Czerwinski .\" Generated by docutils manpage writer. . diff --git a/man/labgrid-suggest.1 b/man/labgrid-suggest.1 index a4305acca..e37d84fd2 100644 --- a/man/labgrid-suggest.1 +++ b/man/labgrid-suggest.1 @@ -27,22 +27,23 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" 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" +.TH "LABGRID-SUGGEST" "1" "2025" "" "labgrid" .SH NAME -labgrid-suggest \- labgrid-suggest generator for YAML config files -.SH SYNOPSIS +labgrid-suggest \- generator for YAML config files +.SH LABGRID-SUGGEST GENERATOR FOR YAML CONFIG FILES +.SS SYNOPSIS .sp \fBlabgrid\-suggest\fP \fB\-\-help\fP .sp \fBlabgrid\-suggest\fP \fB\-\-debug\fP -.SH DESCRIPTION +.SS 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 +.SS OPTIONS .INDENT 0.0 .TP .B \-h\fP,\fB \-\-help @@ -51,7 +52,7 @@ display command line help .B \-d\fP,\fB \-\-debug enable debug mode .UNINDENT -.SH EXAMPLES +.SS 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: @@ -80,16 +81,12 @@ USBSerialPort: .EE .UNINDENT .UNINDENT -.SH SEE ALSO +.SS SEE ALSO .sp \fBlabgrid\-device\-config\fP(5) - -Organization: Labgrid-Project +.SH AUTHOR +Jan Luebbe, Rouven Czerwinski .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. +2016-2025 Pengutronix, Jan Luebbe and Rouven Czerwinski .\" Generated by docutils manpage writer. . diff --git a/pyproject.toml b/pyproject.toml index bf43cada4..476808f3b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -58,6 +58,7 @@ dynamic = ["version"] # via setuptools_scm doc = [ "sphinx_rtd_theme>=1.0.0", "Sphinx>=2.0.0", + "sphinxcontrib-autoprogram>=0.1.9", ] docker = ["docker>=5.0.2"] graph = ["graphviz>=0.17.0"]