Skip to content
Permalink
Browse files

doc: fix and clarify several paragraphs

Clarify overly complicated sentences. Also fix grammatically wrong
sentences.

Use "bootloader" spelling across project, which seems to be the wider
used alternative (as opposed to "boot loader").

Signed-off-by: Bastian Krause <bst@pengutronix.de>
  • Loading branch information
Bastian-Krause authored and jluebbe committed Jan 6, 2020
1 parent 9aa92e6 commit 6fecb4f29bbb1ebcd073fd3433affd155b2ca28f
Showing with 46 additions and 45 deletions.
  1. +24 −25 doc/configuration.rst
  2. +10 −7 doc/development.rst
  3. +2 −2 doc/overview.rst
  4. +8 −9 doc/usage.rst
  5. +2 −2 examples/usbpower/README.rst
@@ -358,7 +358,7 @@ Used by:

USBEthernetInterface
~~~~~~~~~~~~~~~~~~~~
A USBEthernetInterface resource describes a USB device Ethernet adapter.
A USBEthernetInterface resource describes a USB ethernet adapter.

.. code-block:: yaml
@@ -558,8 +558,8 @@ A NetworkFlashrom descibes an `Flashrom`_ available on a remote computer.

XenaManager
~~~~~~~~~~~
A XenaManager resource describe a Xena Manager instance which is the instance the
Xena Driver must connect to in order to configure a Xena chassis.
A XenaManager resource describes a Xena Manager instance which is the instance the
`XenaDriver`_ must connect to in order to configure a Xena chassis.

.. code-block:: yaml
@@ -887,32 +887,31 @@ SmallUBootDriver
A SmallUBootDriver interfaces with stripped-down UBoot variants that are
sometimes used in cheap consumer electronics.

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

- The UBoot does not have a real password-prompt but can be activated by
entering a "secret" after a message was displayed.
- The command line is does not have a build-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 can not return the exit code of the command.
- 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:

- The UBoot must not have real password prompt. Instead it must be
keyword activated.
- The UBoot 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>

- The UBoot 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 UBoot 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.

Binds to:
- :any:`ConsoleProtocol` (see `SerialDriver`_)
@@ -1208,8 +1207,8 @@ SerialPortDigitalOutputDriver
The SerialPortDigitalOutputDriver makes it possible to use a UART
as a 1-Bit general-purpose digital output.

This driver sits on top of a SerialDriver and uses the it's pyserial-
port to control the flow control lines.
This driver acts on top of a SerialDriver and uses the its pyserial port to
control the flow control lines.

Implements:
- :any:`DigitalOutputProtocol`
@@ -1481,7 +1480,7 @@ The qemudriver also requires the specification of:

SigrokDriver
~~~~~~~~~~~~
The SigrokDriver uses a SigrokDevice Resource to record samples and provides
The SigrokDriver uses a SigrokDevice resource to record samples and provides
them during test runs.

Binds to:
@@ -1498,7 +1497,7 @@ The driver can be used in test cases by calling the `capture`, `stop` and

SigrokPowerDriver
~~~~~~~~~~~~~~~~~
The SigrokPowerDriver uses a `SigrokUSBSerialDevice`_ Resource to control a
The SigrokPowerDriver uses a `SigrokUSBSerialDevice`_ resource to control a
programmable power supply.

Binds to:
@@ -1601,8 +1600,8 @@ installed flashrom utility.

XenaDriver
~~~~~~~~~~
The XenaDriver allows to use Xena networking tests equipment. Using the xenavalkyrie library
a full API to control the tester is available.
The XenaDriver allows to use Xena networking test equipment.
Using the `xenavalkyrie` library a full API to control the tester is available.

Binds to:
xena_manager:
@@ -1651,7 +1650,7 @@ Strategies
----------

Strategies are used to ensure that the device is in a certain state during a test.
Such a state could be the boot loader or a booted Linux kernel with shell.
Such a state could be the bootloader or a booted Linux kernel with shell.

BareboxStrategy
~~~~~~~~~~~~~~~
@@ -1672,7 +1671,7 @@ to transition to the shell state:
s.transition("shell")


this command would transition from the boot loader into a Linux shell and
this command would transition from the bootloader into a Linux shell and
activate the shelldriver.

ShellStrategy
@@ -1715,7 +1714,7 @@ to transition to the shell state:
s.transition("shell")


this command would transition from the boot loader into a Linux shell and
this command would transition from the bootloader into a Linux shell and
activate the shelldriver.

DockerShellStrategy
@@ -1897,7 +1896,7 @@ To bind the correct driver to the correct resource, explicit ``name`` and
port: 'bar'
The property name for the binding (e.g. `port` in the example above) is
documented for each individual driver under this chapter.
documented for each individual driver in this chapter.

The YAML configuration file also supports templating for some substitutions,
these are:
@@ -159,7 +159,7 @@ Writing a Resource
-------------------

To add a new resource to labgrid, we import attr into our new resource file.
Additionally we need the :any:`target_factory` and the common Resource class.
Additionally we need the :any:`target_factory` and the common ``Resource`` class.

::

@@ -245,7 +245,7 @@ Start by creating a strategy skeleton:


The ``bindings`` variable needs to declare the drivers necessary for the
strategy, usually one for power, boot loader and shell.
strategy, usually one for power, bootloader and shell.
It is possible to reference drivers via their protocol, e.g.
``ConsoleProtocol``.
Note that drivers which implement multiple protocols must not be referenced
@@ -254,7 +254,8 @@ The ``Status`` class needs to be extended to cover the states of your strategy,
then for each state an ``elif`` entry in the transition function needs to be
added.

Lets take a look at the builtin `BareboxStrategy`. The Status enum for Barebox:
Lets take a look at the builtin `BareboxStrategy`.
The Status enum for the BareboxStrategy:

::

@@ -460,15 +461,17 @@ To use it in conjunction with a `Resource` and a file:
path = mf.get_remote_path()
Unless constructed with `ManagedFile(..., detect_nfs=False)`, ManagedFile
employs the following heuristic to check if a file is on NFS and if so, foregoes
the transfer and `get_remote_path()` just returns the local path (which is
identical to the remote path in this case):
employs the following heuristic to check if a file is stored on a NFS share
available both locally and remotely via the same path:

- check if GNU coreutils stat(1) with option --format exists on local and
remote system
- check if inode number, total size and birth/modification timestamps match
on local and remote system

If this is the case the actual file transfer in ``sync_to_resource`` is
skipped.

ProxyManager
------------
The proxymanager is used to open connections across proxies via an attribute in
@@ -597,7 +600,7 @@ Step Tracing
~~~~~~~~~~~~

The Step infrastructure already collects timing and nesting information on
executed commands, but is currently only used for in pytest or via the
executed commands, but is currently only used in the pytest plugin or via the
standalone StepReporter.
By writing these events to a file (or sqlite database) as a trace, we can
collect data over multiple runs for later analysis.
@@ -275,7 +275,7 @@ exporter1/hub1-port1/\*
(such as a USB ROM-Loader interface, Android fastboot and a USB serial gadget
in Linux).

To avoid conflicting access to the same resources, a place must be `aquired`
To avoid conflicting access to the same resources, a place must be `acquired`
before it is used and the coordinator also keeps track of which user on which
client host has currently acquired the place.
The resource matches are only evaluated while a place is being acquired and cannot be
@@ -353,7 +353,7 @@ connections to remote resources made available by this exporter need to be
tunneled using a SSH connection.
On the other hand, clients may need to access the remote infrastrucure using a
SSH tunnel. In this case the :code:`LG_PROXY` environment variable needs to be
set to the remote host which should tunnel the connections. The client than
set to the remote host which should tunnel the connections. The client then
forwards all network traffic through SSH, even the coordinator connection is
forwarded. This means that with :code:`LG_PROXY` and :code:`LG_CROSSBAR` labgrid can be used
fully remotely with only a SSH connection as a requirement.
@@ -7,7 +7,7 @@ Remote Access
-------------

As described in :ref:`remote-resources-and-places`, one of labgrid's main
features is making access to boards connected to other hosts transparent for
features is granting access to boards connected to other hosts transparent for
the client.
To get started with remote access, take a look at
:ref:`remote-getting-started`.
@@ -517,16 +517,16 @@ 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.
They will be concatenated and compared to a pytest mark on the test to decide
whether the test can run with the available features.::
Adding a ``@pytest.mark.lg_feature`` decorator to a test ensures it is only
executed if the desired feature is available::

import pytest

@pytest.mark.lg_feature("camera")
def test_camera(target):
[...]

together with an example environment configuration:
Here's an example environment configuration:

.. code-block:: yaml
@@ -537,7 +537,7 @@ together with an example environment configuration:
resources: {}
drivers: {}
would run the above test, however the following configuration would skip the
This would run the above test, however the following configuration would skip the
test because of the missing feature:

.. code-block:: yaml
@@ -549,10 +549,9 @@ test because of the missing feature:
resources: {}
drivers: {}
This is also reported in the pytest execution as a skipped test with the reason
being the missing feature.
pytest will record the missing feature as the skip reason.

For tests with multiple required features, pass them as a list to pytest:::
For tests with multiple required features, pass them as a list to pytest::

import pytest

@@ -574,7 +573,7 @@ features key:
resources: {}
drivers: {}
This yaml would combine both the global and the target features.
This YAML configuration would combine both the global and the target features.


Test Reports
@@ -16,8 +16,8 @@ examplestrategy.py
Custom strategy which controls the USB-SD-Mux and the USB port power.

test_example.py
Testsuite (based on pytest) to run a simple command in Barebox, Shell and
Barebox again.
Testsuite (based on pytest) to run a simple command in barebox, shell and
barebox again.

exports.yaml
Configuration file for labgrid-exporter to export these resources over the

0 comments on commit 6fecb4f

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