Skip to content
Permalink
Browse files

doc: use consistent spelling variants of proper names

Use "labgrid", "QEMU", "SSH", "U-Boot" spellings consistently across
documentation.

Signed-off-by: Bastian Krause <bst@pengutronix.de>
  • Loading branch information
Bastian-Krause authored and jluebbe committed Jan 6, 2020
1 parent 6fecb4f commit c753af3094ef2d6ce4d5571ffdbb70c9fa8c621a
@@ -853,7 +853,7 @@ Arguments:

UBootDriver
~~~~~~~~~~~
A UBootDriver interfaces with a u-boot boot loader via a `ConsoleProtocol`.
A UBootDriver interfaces with a U-Boot bootloader via a `ConsoleProtocol`.

Binds to:
console:
@@ -868,50 +868,50 @@ Implements:
prompt: 'Uboot> '
Arguments:
- prompt (regex): u-boot prompt to match
- prompt (regex): U-Boot prompt to match
- autoboot (regex, default="stop autoboot"): autoboot message to match
- password (str): optional, u-boot unlock password
- password (str): optional, U-Boot unlock password
- interrupt (str, default="\\n"): string to interrupt autoboot (use "\\x03" for CTRL-C)
- init_commands (tuple): tuple of commands to execute after matching the
prompt
- password_prompt (str): optional, regex to match the uboot password prompt,
- password_prompt (str): optional, regex to match the U-Boot password prompt,
defaults to "enter Password: "
- boot_expression (str): optional, regex to match the uboot start string
- boot_expression (str): optional, regex to match the U-Boot start string
defaults to "U-Boot 20\d+"
- bootstring (str): optional, regex to match on Linux Kernel boot
- login_timeout (int): optional, timeout for login prompt detection in
seconds (default 60)

SmallUBootDriver
~~~~~~~~~~~~~~~~
A SmallUBootDriver interfaces with stripped-down UBoot variants that are
A SmallUBootDriver interfaces with stripped-down U-Boot variants that are
sometimes used in cheap consumer electronics.

SmallUBootDriver is meant as a driver for UBoot with only little functionality
compared to a standard UBoot.
SmallUBootDriver is meant as a driver for U-Boot with only little functionality
compared to a standard U-Boot.
Especially is copes with the following limitations:

- The UBoot does not have a real password-prompt but can be activated by
- The U-Boot does not have a real password-prompt but can be activated by
entering a "secret" after a message was displayed.
- The command line does not have a built-in echo command.
Thus this driver uses 'Unknown Command' messages as marker before and after
the output of a command.
- Since there is no echo we cannot return the exit code of the command.
Commands will always return 0 unless the command was not found.

This driver needs the following features activated in UBoot to work:
This driver needs the following features activated in U-Boot to work:

- The UBoot must not have a real password prompt. Instead it must be keyword
- The U-Boot must not have a real password prompt. Instead it must be keyword
activated.
For example it should be activated by a dialog like the following:

- UBoot: "Autobooting in 1s..."
- Labgrid: "secret"
- UBoot: <switching to console>
- U-Boot: "Autobooting in 1s..."
- labgrid: "secret"
- U-Boot: <switching to console>

- The UBoot must be able to parse multiple commands in a single line separated
- The U-Boot must be able to parse multiple commands in a single line separated
by ";".
- The UBoot must support the "bootm" command to boot from a memory location.
- The U-Boot must support the "bootm" command to boot from a memory location.

Binds to:
- :any:`ConsoleProtocol` (see `SerialDriver`_)
@@ -927,10 +927,10 @@ Implements:
boot_secret: "tpl"
Arguments:
- prompt (regex): u-boot prompt to match
- prompt (regex): U-Boot prompt to match
- init_commands (tuple): tuple of commands to execute after matching the
prompt
- boot_expression (str): optional, regex to match the uboot start string
- boot_expression (str): optional, regex to match the U-Boot start string
defaults to "U-Boot 20\d+"
- login_timeout (str): optional, timeout for the password/login detection

@@ -1042,7 +1042,7 @@ Arguments:
- image (str): filename of image to flash QSPI

The driver can be used in test cases by calling the `flash` function. An
example strategy is included in Labgrid.
example strategy is included in labgrid.

ManualPowerDriver
~~~~~~~~~~~~~~~~~
@@ -1422,7 +1422,7 @@ Arguments:

QEMUDriver
~~~~~~~~~~
The QEMUDriver allows the usage of a qemu instance as a target. It requires
The QEMUDriver allows the usage of a QEMU instance as a target. It requires
several arguments, listed below.
The kernel, flash, rootfs and dtb arguments refer to images and paths declared
in the environment configuration.
@@ -1471,9 +1471,9 @@ Arguments:
- rootfs (str): optional, reference to the paths key for use as the virtio-9p filesystem
- dtb (str): optional, reference to the image key for the device tree

The qemudriver also requires the specification of:
The QEMUDriver also requires the specification of:

- a tool key, this contains the path to the qemu binary
- a tool key, this contains the path to the QEMU binary
- an image key, the path to the kernel image and optionally the dtb key to
specify the build device tree
- a path key, this is the path to the rootfs
@@ -1737,10 +1737,10 @@ To transition to the shell state:

These commands would activate the docker driver which creates and starts
a docker container. This will subsequently make `NetworkService`_ instance(s)
available which can be used for e.g. ssh access.
available which can be used for e.g. SSH access.

Note: Transitioning to the "off" state will make any `NetworkService`_
instance(s) unresponsive - which may in turn invalidate ssh connection
instance(s) unresponsive - which may in turn invalidate SSH connection
sharing. Therefore, during automated test suites, refrain from transitioning
to the "off" state.

@@ -24,7 +24,7 @@ Our reasons for this are:
Test Infrastructure
~~~~~~~~~~~~~~~~~~~

Labgrid does not include a test framework.
labgrid does not include a test framework.

The main reason is that with `pytest <https://docs.pytest.org/>`_ we already
have a test framework which:
@@ -51,7 +51,7 @@ If you are unsure about a new protocol's API, just use the driver directly from
the client code, as deciding on a good API will be much easier when another
similar driver is added.

Labgrid uses the `attrs library <https://attrs.readthedocs.io>`_ for internal
labgrid uses the `attrs library <https://attrs.readthedocs.io>`_ for internal
classes.
First of all import attr, the protocol and the common driver class
into your new driver file.
@@ -205,7 +205,7 @@ validators, see the `attrs documentation <https://attrs.readthedocs.io/en/stable
Writing a Strategy
------------------

Labgrid only offers two basic strategies, for complex use cases a customized
labgrid only offers two basic strategies, for complex use cases a customized
strategy is required.
Start by creating a strategy skeleton:

@@ -408,7 +408,7 @@ had been incremental.
SSHManager
----------

Labgrid provides a SSHManager to allow connection reuse with control sockets.
labgrid provides a SSHManager to allow connection reuse with control sockets.
To use the SSHManager in your code, import it from `labgrid.util.ssh`:

.. code-block:: python
@@ -540,7 +540,7 @@ Run Tests
Developer's Certificate of Origin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Labgrid uses the `Developer's Certificate of Origin 1.1
labgrid uses the `Developer's Certificate of Origin 1.1
<https://developercertificate.org/>`_ with the same `process
<https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin>`_
as used for the Linux kernel:
@@ -39,7 +39,7 @@ requirements from the `requirements.txt` file:
Consequently we now recommend using pinned versions from the
`requirements.txt` file for most use cases.

Labgrid also supports the installation as a library via pip, but we only
labgrid also supports the installation as a library via pip, but we only
test against library versions specified in the requirements.txt file.
Thus when installing directly from pip you have to test compatibility
yourself.
@@ -74,7 +74,7 @@ successful so far, proceed to the next section:

Optional Requirements
~~~~~~~~~~~~~~~~~~~~~
Labgrid provides optional features which are not included in the default
labgrid provides optional features which are not included in the default
`requirements.txt`. The tested library version for each feature is included in a
seperate requirements file. An example for snmp support is:

@@ -316,13 +316,13 @@ man page.
udev Matching
-------------

Labgrid allows the exporter (or the client-side environment) to match resources
labgrid allows the exporter (or the client-side environment) to match resources
via udev rules.
The udev resources become available to the test/exporter as soon es they are
plugged into the computer, e.g. allowing an exporter to export all USB ports on
a specific hub and making a ``NetworkSerialPort`` available as soon as it is
plugged into one of the hub's ports.
Labgrid also provides a small utility called ``labgrid-suggest`` which will
labgrid also provides a small utility called ``labgrid-suggest`` which will
output the proper YAML formatted snippets for you.
The information udev has on a device can be viewed by executing:

@@ -380,7 +380,7 @@ to a shell. They have a few requirements:
- A driver implementing the ``CommandProtocol``, usually a ``ShellDriver`` with
a ``SerialDriver`` below it.

Labgrid ships with two builtin strategies, ``BareboxStrategy`` and
labgrid ships with two builtin strategies, ``BareboxStrategy`` and
``UBootStrategy``. These can be used as a reference example for simple
strategies, more complex tests usually require the implementation of your own
strategies.
@@ -1,14 +1,14 @@
Welcome to labgrid's documentation!
===================================

Labgrid is a embedded board control python library with a focus on testing, development
labgrid is a embedded board control python library with a focus on testing, development
and general automation.
It includes a remote control layer to control boards connected to other hosts.

The idea behind labgrid is to create an abstraction of the hardware control
layer needed for testing of embedded systems, automatic software installation
and automation during development.
Labgrid itself is *not* a testing framework, but is intended to be combined with
labgrid itself is *not* a testing framework, but is intended to be combined with
`pytest <https://docs.pytest.org>`_ (and additional pytest plugins).
Please see :doc:`design_decisions` for more background information.

@@ -4,7 +4,7 @@ Overview
Architecture
------------

Labgrid can be used in several ways:
labgrid can be used in several ways:

- on the command line to control individual embedded systems during development
("board farm")
@@ -173,7 +173,7 @@ Especially when using labgrid from pytest, explicitly controlling the board's
boot process can distract from the individual test case.
Each :any:`Strategy` implements the board- or project-specific actions necessary to
transition from one state to another.
Labgrid includes the :any:`BareboxStrategy` and the :any:`UBootStrategy`, which
labgrid includes the :any:`BareboxStrategy` and the :any:`UBootStrategy`, which
can be used as-is for simple cases or serve as an example for implementing a
custom strategy.

@@ -192,7 +192,7 @@ For more information on the reasons behind labgrid's architecture, see
Remote Resources and Places
---------------------------

Labgrid contains components for accessing resources which are not directly
labgrid contains components for accessing resources which are not directly
accessible on the local machine.
The main parts of this are:

@@ -168,7 +168,7 @@ used by locked places.

Library
-------
Labgrid can be used directly as a Python library, without the infrastructure
labgrid can be used directly as a Python library, without the infrastructure
provided by the pytest plugin.

Creating and Configuring Targets
@@ -270,7 +270,7 @@ multiple drivers, see :ref:`configuration:Environment Configuration`.

pytest Plugin
-------------
Labgrid includes a `pytest <http://pytest.org>`_ plugin to simplify writing tests which
labgrid includes a `pytest <http://pytest.org>`_ plugin to simplify writing tests which
involve embedded boards.
The plugin is configured by providing an environment config file
(via the --lg-env pytest option, or the LG_ENV environment variable)
@@ -516,7 +516,7 @@ For this example, you should get a report similar to this:
Feature Flags
~~~~~~~~~~~~~
Labgrid includes support for feature flags on a global and target scope.
labgrid includes support for feature flags on a global and target scope.
Adding a ``@pytest.mark.lg_feature`` decorator to a test ensures it is only
executed if the desired feature is available::

@@ -605,7 +605,7 @@ They can also be converted to other formats, such as HTML with `junit2html tool
$ junit2html report.xml
Labgrid adds additional xml properties to a test run, these are:
labgrid adds additional xml properties to a test run, these are:

- ENV_CONFIG: Name of the configuration file
- TARGETS: List of target names
@@ -621,14 +621,14 @@ Labgrid adds additional xml properties to a test run, these are:
Command-Line
------------

Labgrid contains some command line tools which are used for remote access to
labgrid contains some command line tools which are used for remote access to
resources.
See :doc:`man/client`, :doc:`man/device-config` and :doc:`man/exporter` for
more information.

USB stick emulation
--------------------
Labgrid makes it posible to use a target as an emulated USB stick, allowing
labgrid makes it posible to use a target as an emulated USB stick, allowing
upload, modification, plug and unplug events.
To use a target as an emulated USB stick, several requirements have to be met:

@@ -656,7 +656,7 @@ the emulated USB stick in and out.
hawkBit management API
----------------------

Labgrid provides an interface to the hawkbit management API.
labgrid provides an interface to the hawkbit management API.
This allows a labgrid test to create targets, rollouts and manage deployments.

::
@@ -64,8 +64,8 @@ enable debug mode
.UNINDENT
.SS \-i / \-\-isolated
.sp
This option enables isolated mode, which causes all exported resources marked
as requiring SSH connection forwarding.
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
@@ -51,8 +51,8 @@ OPTIONS

-i / --isolated
~~~~~~~~~~~~~~~
This option enables isolated mode, which causes all exported resources marked
as requiring SSH connection forwarding.
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

0 comments on commit c753af3

Please sign in to comment.
You can’t perform that action at this time.