diff --git a/doc/conf.py b/doc/conf.py index bfdaa30a8..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'] @@ -156,7 +161,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 +198,11 @@ 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..201a7960e 100644 --- a/doc/man.rst +++ b/doc/man.rst @@ -2,7 +2,11 @@ Manual Pages ============ .. toctree:: + :maxdepth: 2 + 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..2362e2729 100644 --- a/doc/man/client.rst +++ b/doc/man/client.rst @@ -1,2 +1,162 @@ .. _labgrid-client: -.. include:: ../../man/labgrid-client.rst + +labgrid-client +============== + +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 + + +.. argparse:: + :module: labgrid.remote.client + :func: get_parser + :prog: labgrid-client + :nodefault: + + + help : @skip + skip. + + complete : @skip + skip. + + 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 +------------------ +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..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/labgrid/remote/client.py b/labgrid/remote/client.py index 27108a7b4..202134b3b 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(include_undocumented=False) -> 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( @@ -1765,11 +1744,12 @@ def main(): 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) @@ -2018,7 +1998,7 @@ def main(): "-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)", @@ -2065,11 +2045,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 +2072,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(include_undocumented=True) + # make any leftover arguments available for some commands args, leftover = parser.parse_known_args() if args.command not in ["ssh", "rsync", "forward"]: @@ -2099,6 +2101,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 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. -. 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"]