doc: Tidy up the hooks documentation
Now that these files are within the repo, link the documentation to the normal U-Boot documentation. Update directory paths and convert it to rST format. Signed-off-by: Simon Glass <sjg@chromium.org>
This commit is contained in:
Simon Glass
@@ -85,6 +85,7 @@ Testing
|
||||
tests_writing
|
||||
tests_sandbox
|
||||
binman_tests
|
||||
test_hooks
|
||||
|
||||
Refactoring
|
||||
-----------
|
||||
|
||||
@@ -314,6 +314,8 @@ via `$PATH`. These scripts implement certain actions on behalf of the test
|
||||
suite. This keeps the test suite simple and isolated from system variances
|
||||
unrelated to U-Boot features.
|
||||
|
||||
For more details see :doc:`test_hooks`.
|
||||
|
||||
Hook scripts
|
||||
~~~~~~~~~~~~
|
||||
|
||||
@@ -404,9 +406,9 @@ saving wear on the flash chip(s).
|
||||
Examples
|
||||
''''''''
|
||||
|
||||
https://source.denx.de/u-boot/u-boot-test-hooks contains some working example hook
|
||||
The directory `test/hooks` contains some working example hook
|
||||
scripts, and may be useful as a reference when implementing hook scripts for
|
||||
your platform. These scripts are not considered part of U-Boot itself.
|
||||
your platform. These scripts are considered part of U-Boot itself.
|
||||
|
||||
Board-type-specific configuration
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@@ -469,16 +471,16 @@ instances of:
|
||||
Complete invocation example
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Assuming that you have installed the hook scripts into $HOME/ubtest/bin, and
|
||||
any required environment configuration Python modules into $HOME/ubtest/py,
|
||||
then you would likely invoke the test script as follows:
|
||||
Assuming that you have installed U-Boot `$UBOOT`, any new hooks into
|
||||
`$UBOOT/test/hooks/bin` and any new configuration Python modules into
|
||||
`$UBOOT/test/hooks/py`, then you would likely invoke the test script as follows:
|
||||
|
||||
If U-Boot has already been built:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
PATH=$HOME/ubtest/bin:$PATH \
|
||||
PYTHONPATH=${HOME}/ubtest/py/${HOSTNAME}:${PYTHONPATH} \
|
||||
PATH=$UBOOT/test/hooks/bin:$PATH \
|
||||
PYTHONPATH=$UBOOT/test/hooks/py/${HOSTNAME}:${PYTHONPATH} \
|
||||
./test/py/test.py --bd seaboard
|
||||
|
||||
If you want the test script to compile U-Boot for you too, then you likely
|
||||
@@ -488,7 +490,7 @@ follows:
|
||||
.. code-block:: bash
|
||||
|
||||
CROSS_COMPILE=arm-none-eabi- \
|
||||
PATH=$HOME/ubtest/bin:$PATH \
|
||||
PATH=$UBOOT/test/hooks/bin:$PATH \
|
||||
PYTHONPATH=${HOME}/ubtest/py/${HOSTNAME}:${PYTHONPATH} \
|
||||
./test/py/test.py --bd seaboard --build
|
||||
|
||||
@@ -496,8 +498,8 @@ or, using buildman to handle it:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
PATH=$HOME/ubtest/bin:$PATH \
|
||||
PYTHONPATH=${HOME}/ubtest/py/${HOSTNAME}:${PYTHONPATH} \
|
||||
PATH=$UBOOT/test/hooks/bin:$PATH \
|
||||
PYTHONPATH=$UBOOT/test/hooks/py/${HOSTNAME}:${PYTHONPATH} \
|
||||
./test/py/test.py --bd seaboard --build --buildman
|
||||
|
||||
Writing tests
|
||||
|
||||
@@ -1,17 +1,20 @@
|
||||
# Introduction
|
||||
Hardware testing
|
||||
================
|
||||
|
||||
This repository contains working example support ("hook") scripts for U-Boot's
|
||||
The ``test/hooks`` directory contains support ("hook") scripts for U-Boot's
|
||||
built-in test framework. That framework is located in the `test/py/` directory
|
||||
in the U-Boot source tree.
|
||||
|
||||
You may use these examples as a reference when creating your own hook scripts,
|
||||
or even derive your own scripts directly from the files in this repository.
|
||||
or even derive your own scripts directly from the files in ``test/hooks``.
|
||||
|
||||
# Contributing
|
||||
Contributing
|
||||
------------
|
||||
|
||||
See [Contributing.md](Contributing.md).
|
||||
Please send a patch to the U-Boot as per :doc:`process`
|
||||
|
||||
# Flashing Philosophy
|
||||
Flashing Philosophy
|
||||
-------------------
|
||||
|
||||
U-Boot may be installed onto a target device either by:
|
||||
|
||||
@@ -22,14 +25,15 @@ U-Boot may be installed onto a target device either by:
|
||||
download needs to happen every time the target board is reset, since the
|
||||
desired binary is not permanently stored on the system.
|
||||
|
||||
The example scripts in this repository take the second approach. This approach
|
||||
The example scripts in ``test/hooks`` take the second approach. This approach
|
||||
avoids modifying the device's flash memory for each U-Boot binary to be tested,
|
||||
which should increase longevity of the device. This does mean that the
|
||||
implementation of the `test/py/` hook scripts is slightly inconsistent with
|
||||
their naming; `u-boot-test-flash` does nothing whereas `u-boot-test-reset`
|
||||
downloads U-Boot into RAM rather than only performing a simple system reset.
|
||||
|
||||
# USB Port Paths
|
||||
USB Port Paths
|
||||
--------------
|
||||
|
||||
When multiple USB devices of the same type are attached to the same system, some
|
||||
mechanism for differentiating between them is required, in order for software to
|
||||
@@ -52,7 +56,7 @@ numbers form the balance of the USB port path.
|
||||
Linux uses the format `${bus}-${port}.${port}.${port}...` to represent the USB
|
||||
port path.
|
||||
|
||||
For example:
|
||||
For example::
|
||||
|
||||
+--------------+
|
||||
| PC |
|
||||
@@ -78,7 +82,7 @@ experimentation using tools such as `picocom` or `mount` and `ls`.
|
||||
|
||||
Once a device node has been identified, use udevadm to query all known
|
||||
information about the device, then find an entry with `SUBSYSTEMS=="usb"` and a
|
||||
`KERNELS` value in the format of a USB port path:
|
||||
`KERNELS` value in the format of a USB port path::
|
||||
|
||||
$ udevadm info -a /dev/ttyUSB2
|
||||
...
|
||||
@@ -109,7 +113,7 @@ information about the device, then find an entry with `SUBSYSTEMS=="usb"` and a
|
||||
|
||||
Here, the USB port path is "`3-6`".
|
||||
|
||||
or:
|
||||
or::
|
||||
|
||||
$ udevadm info -a /dev/bus/usb/003/086
|
||||
....
|
||||
@@ -120,9 +124,10 @@ or:
|
||||
|
||||
Here, the USB port path is "`3-10.4`".
|
||||
|
||||
# udev Rules
|
||||
udev Rules
|
||||
----------
|
||||
|
||||
See the `udev/` directory in this repository.
|
||||
See the `test/hooks/udev/` directory.
|
||||
|
||||
Testing should be performed as a non-root user. This requires that the relevant
|
||||
device nodes have non-default permissions. udev rules may be used to achieve
|
||||
@@ -145,9 +150,10 @@ path.
|
||||
|
||||
The example udev rules demonstrate both of these types of rules.
|
||||
|
||||
# Scripts and Binaries
|
||||
Scripts and Binaries
|
||||
--------------------
|
||||
|
||||
See the `bin/` directory in this repository.
|
||||
See the `test/hooks/bin/` directory.
|
||||
|
||||
Scripts exist to power on, power off, flash, and reset Tegra boards, and access
|
||||
their serial console. The U-Boot test framework expects these scripts to exist
|
||||
@@ -175,10 +181,11 @@ more than include a board-specific configuration file, and then include another
|
||||
file specific to implementation the desired action.
|
||||
|
||||
Board configuration files are located in
|
||||
`bin/${hostname}/conf.${board_type}_${board_identity}`. These files are
|
||||
segregated by hostname so that the repository can be used directly across
|
||||
`test/hooks/bin/${hostname}/conf.${board_type}_${board_identity}`. These files
|
||||
are segregated by hostname so that the repository can be used directly across
|
||||
multiple different test machines, without the need for host-specific branches or
|
||||
post-checkout configuration.
|
||||
post-checkout configuration. Your scripts can also exist outside the U-Boot
|
||||
repo if that is helpful.
|
||||
|
||||
The board configuration file defines which mechanism is used for each possible
|
||||
action, and any parameters associated with it. For example, downloading U-Boot
|
||||
@@ -187,8 +194,8 @@ T124 or earlier, or L4T's `exec-uboot.sh` for boards containing T210 or newer.
|
||||
These scripts. In each case, the directory name where the tool is installed must
|
||||
be defined.
|
||||
|
||||
Each action is implemented in a script fragment directly in the `bin/` directory,
|
||||
with filename `${action_type}.${implementation_name}`.
|
||||
Each action is implemented in a script fragment directly in the`test/hooks/bin/`
|
||||
directory, with filename `${action_type}.${implementation_name}`.
|
||||
|
||||
If using these scripts directly for testing Tegra devices, it is likely that
|
||||
you will not need to create new `download.*` implementations, but will need to
|
||||
@@ -199,7 +206,8 @@ scripts must be replicated once per board instance, or their actions somehow
|
||||
serialized, since they copy files into their own directories when executing, and
|
||||
hence parallel execution would cause incorrect operation.
|
||||
|
||||
## Labgrid Integration
|
||||
Labgrid Integration
|
||||
-------------------
|
||||
|
||||
Labgrid is a python library for embedded-board-control. It includes a client
|
||||
program which is used to integrate with the U-Boot pytests.
|
||||
@@ -208,9 +216,9 @@ Since Labgrid has all the information necessary to build and boot on a lab,
|
||||
there is no per-board configuration required. The various flash.xxx and
|
||||
recovery.xxx scripts are not used. To set it up, one implementation is:
|
||||
|
||||
- In your bin/$hostname directory, create an executable file
|
||||
- In the test/hooks/bin/$hostname directory, create an executable file
|
||||
`common-labgrid-sjg` and set your crossbar and environment information, for
|
||||
example:
|
||||
example::
|
||||
|
||||
# Hostname and port for the gRPC coordinator
|
||||
export LG_COORDINATOR=kea:20408
|
||||
@@ -219,7 +227,7 @@ recovery.xxx scripts are not used. To set it up, one implementation is:
|
||||
export LG_ENV="/path/to/kea_env.cfg"
|
||||
|
||||
# Location of the U-Boot test hooks
|
||||
export UB_TEST_HOOKS=/path/to/u-boot-test-hooks
|
||||
export UB_TEST_HOOKS=/path/to/u-boot/test/hooks
|
||||
|
||||
# Make sure only one buildman can run at a time, since it uses all CPUs
|
||||
export BUILDMAN_PROCESS_LIMIT=1
|
||||
@@ -258,10 +266,11 @@ variables must be set as per your lab:
|
||||
- `LG_ENV` must point at the labgrid yaml file that describes your lab.
|
||||
|
||||
In order for a given platform to be tested, it must be acquired before starting
|
||||
tests and then released once complete. See the bin/konsulko-labgrid directory
|
||||
for example boards using this method.
|
||||
tests and then released once complete. See the `test/hooks/bin/konsulko-labgrid`
|
||||
directory for example boards using this method.
|
||||
|
||||
## Dependencies
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
The example scripts depend on various external tools, the installation location
|
||||
of which must be specified in the board configuration files:
|
||||
@@ -280,9 +289,10 @@ of which must be specified in the board configuration files:
|
||||
U-Boot's test framework also requires a `dfu-util` that supports the -p
|
||||
command-line option. Most distros provide this nowadays.
|
||||
|
||||
# Python Modules
|
||||
Python Modules
|
||||
--------------
|
||||
|
||||
See the `py/` directory in this repository.
|
||||
See the `test/hooks/py/` directory.
|
||||
|
||||
A Python module exists for each board and defines numerous parameters used by
|
||||
the U-Boot test framework. The framework expects to simply import these modules
|
||||
@@ -292,5 +302,5 @@ These modules are again located in a separate directory for each host, so that
|
||||
the repository may be shared across hosts.
|
||||
|
||||
For complete details re: the required content of these Python modules, please
|
||||
see `test/py/README.md` in the U-boot source tree, and also the comments in some
|
||||
individual test files in `test/py/tests/test_*.py`.
|
||||
see :doc:`py_testing` and also the comments in some individual test files in
|
||||
`test/py/tests/test_*.py`.
|
||||
Reference in New Issue
Block a user