update ebc9984

antmicro · Jul 24, 2024 · 983cc2c · 983cc2c
commit 983cc2c
Show file tree

Hide file tree

Showing 225 changed files with 5,522 additions and 0 deletions.
diff --git a/.buildinfo b/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: bdc9fe5f9af8f48270429efb5837bccc
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/.nojekyll b/.nojekyll
diff --git a/_sources/index.md.txt b/_sources/index.md.txt
@@ -0,0 +1,11 @@
+# {{project}}
+
+```{toctree}
+:maxdepth: 2
+
+introduction
+readme
+protoplaster
+report
+system_report
+```
diff --git a/_sources/introduction.md.txt b/_sources/introduction.md.txt
@@ -0,0 +1,8 @@
+# Introduction
+
+This documentation serves as an example of how individual projects documentation can look like.
+
+The second chapter contains information from the README file.
+
+The last chapter is generated from the sample ``test.yml`` file which can be found in the README.
+Its purpose is to demonstrate the documentation generated to describe test procedures used in a project.
diff --git a/_sources/protoplaster.md.txt b/_sources/protoplaster.md.txt
@@ -0,0 +1,62 @@
+Protoplaster tests
+==================
+
+```{note}
+   This page has been autogenerated from a Protoplaster tests definition file.
+```
+
+To perform hardware/BSP tests and open-source [Protoplaster](https://github.com/antmicro/protoplaster)  framework has been used.
+
+Running Protoplaster runs the tests described in the following chapters:
+
+I2C devices tests
+-----------------
+
+This module provides tests dedicated to i2c devices on specific buses:
+
+* /dev/i2c-0:
+
+  * detection test for *Sensor name* on address: `0x3c`
+
+
+* /dev/i2c-0:
+
+  * detection test for *I2C-bus multiplexer* on address: `0x70`
+
+
+
+Camera sensor tests
+-------------------
+
+This module provides tests dedicated to V4L devices on specific video node:
+
+* /dev/video0:
+
+  * try to capture frame
+
+  * check if the camera sensor name is `vivid`
+
+  * check if the camera sensor driver name is `vivid`
+
+
+* /dev/video2:
+
+  * try to capture frameand store it to `frame.raw` file
+
+  * check if the camera sensor name is `vivid`
+
+  * check if the camera sensor driver name is `vivid`
+
+
+
+GPIOs tests
+-----------
+
+This module provides tests dedicated to GPIO on specific pin number
+
+* /sys/class/gpio/gpio20:
+
+  * write `1` and read back to confirm
+
+
+
diff --git a/_sources/readme.md.txt b/_sources/readme.md.txt
@@ -0,0 +1,258 @@
+# Protoplaster
+
+Copyright (c) 2022-2024 [Antmicro](https://www.antmicro.com)
+
+An automated framework for platform testing (Hardware and BSPs).
+
+Currently includes tests for:
+
+* I2C
+* GPIO
+* Camera
+* FPGA
+
+## Installation
+```bash
+pip install git+https://github.com/antmicro/protoplaster.git
+```
+
+## Usage
+
+```
+usage: protoplaster [-h] [-t TEST_FILE] [-g GROUP] [--list-groups] [-o OUTPUT] [--csv CSV] [--csv-columns CSV_COLUMNS] [--generate-docs] [-c CUSTOM_TESTS]
+
+options:
+  -h, --help            show this help message and exit
+  -t TEST_FILE, --test-file TEST_FILE
+                        Path to the test yaml description
+  -g GROUP, --group GROUP
+                        Group to execute
+  --list-groups         List possible groups to execute
+  -o OUTPUT, --output OUTPUT
+                        A junit-xml style report of the tests results
+  --csv CSV             Generate a CSV report of the tests results
+  --csv-columns CSV_COLUMNS
+                        Comma-separated list of columns to be included in generated CSV
+  --generate-docs       Generate documentation
+  -c CUSTOM_TESTS, --custom-tests CUSTOM_TESTS
+                        Path to the custom tests sources
+  --report-output REPORT_OUTPUT
+                        Proplaster report archive
+  --system-report-config SYSTEM_REPORT_CONFIG
+                        Path to the system report yaml config file
+  --sudo                Run as sudo
+```
+
+Protoplaster expects a yaml file describing tests as an input. The yaml file should have a structure specified as follows:
+
+<!-- name="example" -->
+```yaml
+base:                # A group specifier
+  i2c:               # A module specifier
+  - bus: 0           # An interface specifier
+    devices:         # Multiple instances of devices can be defined in one module
+    - name: "Sensor name"
+      address: 0x3c  # The given device parameters determine which tests will be run for the module
+  - bus: 0
+    devices:
+    - name: "I2C-bus multiplexer"
+      address: 0x70
+  camera:
+  - device: "/dev/video0"
+    camera_name: "vivid"
+    driver_name: "vivid"
+  - device: "/dev/video2"
+    camera_name: "vivid"
+    driver_name: "vivid"
+    save_file: "frame.raw"
+additional:
+  gpio:
+  - number: 20
+    value: 1
+```
+
+### Groups
+In the YAML file, you can define different groups of tests to run them for different use cases. 
+In the YAML file example, there are two groups defined: base and additional. 
+Protoplaster, when run without a defined group, will execute every test in each group. 
+When the group is specified with the parameter `-g` or `--group`, only the tests in the specified group are going to be run. 
+You can also list existing groups in the YAML file, simply run `protoplaster --list-groups test.yaml`.
+
+## Base modules parameters
+Each base module requires parameters for test initialization. 
+These parameters describe the tests and are passed to the test class as its attributes.
+
+### I2C
+Required parameters:
+
+* `bus` - i2c bus to be checked
+* `name` - name of device to be detected
+* `address` - address of the device to be detected on the indicated bus
+
+### GPIO
+Required parameters:
+
+* `number` - GPIO pin number
+* `value` - value written to that pin
+
+Optional parameters:
+
+* `gpio_name` - name of the sysfs GPIO interface after exporting
+
+### Cameras
+Required parameters:
+
+* `device` - path to the camera device (eg. /dev/video0)
+* `camera_name` - expected camera name
+* `driver_name` - expected driver name
+
+Optional parameters:
+
+* `save_file` - a path which the tested frame is saved to (the frame is saved only if this parameter is present)
+
+### FPGA
+Required parameters:
+
+* `sysfs_interface` - path to a sysfs interface for flashing the bitstream to the FPGA
+* `bitstream_path` - path to a test bitstream that is going to be flashed
+
+## Writing additional modules
+Apart from base modules available in Protoplaster, you can provide your own extended modules. 
+The module should contain a `test.py` file in the root path. 
+This file should contain a test class that is decorated with `ModuleName("")` from the `protoplaster.conf.module` package.
+This decorator tells Protoplaster what the name of the module is. 
+With this information, Protoplaster can correctly initialize the test parameters. 
+The test class should contain a `name()` method. Its return value is used for the `device_name` field in CSV output.
+
+The description of the external module should be added to the YAML file as for other tests. 
+By default, external modules are expected in the `/etc/protoplaster` directory. 
+If you want to store them in a different path, use the `--custom-tests` argument to set your own path. 
+Individual tests run by Protoplaster should be present in the main class in the `test.py` file. 
+The class's name should start with `Test`, and every test's name in this class should also start with `test`. 
+An example of an extended module test:
+
+```python
+from protoplaster.conf.module import ModuleName
+
+@ModuleName("additional_camera")
+class TestAdditionalCamera:
+    """
+    {% macro TestAdditionalCamera(prefix) -%}
+    Additional camera tests
+    -----------------------
+    {% do prefix.append('') %}
+    This module provides tests dedicated to camera sensors on specific video node:
+    {%- endmacro %}
+    """
+
+    def test_exists(self):
+        """
+        {% macro test_exists(device) -%}
+          check if the path exists
+        {%- endmacro %}
+        """
+        assert self.path == "/dev/video0"
+```
+
+And a YAML definition:
+
+```yaml
+---
+base:
+  additional_camera:
+    - path: "/dev/video0"
+    - path: "/dev/video1"
+```
+
+## Protoplaster test report
+Protoplaster provides `protoplaster-test-report`, a tool to convert test CSV output into a HTML or Markdown table.
+```
+usage: protoplaster-test-report [-h] [-i INPUT_FILE] -t {md,html} [-o OUTPUT_FILE]
+
+options:
+  -h, --help            show this help message and exit
+  -i INPUT_FILE, --input-file INPUT_FILE
+                        Path to the csv file
+  -t {md,html}, --type {md,html}
+                        Output type
+  -o OUTPUT_FILE, --output-file OUTPUT_FILE
+                        Path to the output file
+```
+
+
+## System report
+Protoplaster provides `protoplaster-system-report`, a tool for obtaining information about system state and configuration.
+It executes a list of commands and saves their outputs. 
+The outputs are stored in a single zip archive along with an HTML summary.
+
+### Usage
+```
+usage: protoplaster-system-report [-h] [-o OUTPUT_FILE] [-c CONFIG] [--sudo]
+
+options:
+  -h, --help            show this help message and exit
+  -o OUTPUT_FILE, --output-file OUTPUT_FILE
+                        Path to the output file
+  -c CONFIG, --config CONFIG
+                        Path to the YAML config file
+  --sudo                Run as sudo
+```
+
+The YAML config contains a list of actions to perform. A single action is described as follows:
+
+```yaml
+report_item_name:
+  run: script
+  summary:
+    - title: summary_title
+      run: summary_script
+  output: script_output_file
+  superuser: required | preferred
+  on-fail: ...
+```
+
+* `run` - command to be run
+* `summary` – a list of summary generators, each one with fields:
+  * `title` – summary title
+  * `run` – command that generates the summary. This command gets the output of the original command as stdin. This field is optional; if not specified, the output is placed in the report as-is.
+* `output` - output file for the output of `run`.
+* `superuser` – optional, should be specified if the command requires elevated privileges to run. Possible values:
+  * `required` – `protoplaster-system-report` will terminate if the privilege requirement is not met
+  * `preferred` – if the privilege requirement is not met, a warning will be issued and this particular item won't be included in the report
+* `on-fail` – optional description of an item to run in case of failure. It can be used to run an alternative command when the original one fails or is not available.
+
+Example config file:
+<!-- name="system-report-example" -->
+```yaml
+uname:
+  run: uname -a
+  summary:
+    - title: os info
+      run: cat
+  output: uname.out
+dmesg:
+  run: dmesg
+  summary: 
+    - title: usb
+      run: grep usb
+    - title: v4l
+      run: grep v4l
+  output: dmesg.out
+  superuser: required
+ip:
+  run: ip a
+  summary:
+    - title: Network interfaces state
+      run: python3 $PROTOPLASTER_SCRIPTS/generate_ip_table.py "$(cat)"
+  output: ip.out
+  on-fail:
+    run: ifconfig -a
+    summary:
+      - title: Network interfaces state
+        run: python3 $PROTOPLASTER_SCRIPTS/generate_ifconfig_table.py "$(cat)"
+    output: ifconfig.out
+```
+
+### Running as root
+By default, `sudo` doesn't preserve `PATH`. 
+To run `protoplaster-system-report` installed by a non-root user as root, invoke `protoplaster-system-report --sudo`
diff --git a/_sources/report.md.txt b/_sources/report.md.txt
@@ -0,0 +1,13 @@
+Protoplaster tests report
+==================
+|device name|test name|module|duration|message|status|
+|---|---|---|---|---|---|
+|/dev/i2c-0|addresses|test.py::TestI2C::test_addresses|9ms 238us||<span style='color:green'>passed|
+|/dev/i2c-0|addresses|test.py::TestI2C::test_addresses|8ms 561us||<span style='color:green'>passed|
+|/dev/video0|frame|test.py::TestCamera::test_frame|232ms 469us||<span style='color:green'>passed|
+|/dev/video0|device_name|test.py::TestCamera::test_device_name|206ms 263us||<span style='color:green'>passed|
+|/dev/video0|driver_name|test.py::TestCamera::test_driver_name|221ms 888us||<span style='color:green'>passed|
+|/dev/video2|frame|test.py::TestCamera::test_frame|254ms 4us||<span style='color:green'>passed|
+|/dev/video2|device_name|test.py::TestCamera::test_device_name|205ms 782us||<span style='color:green'>passed|
+|/dev/video2|driver_name|test.py::TestCamera::test_driver_name|204ms 726us||<span style='color:green'>passed|
+|/sys/class/gpio/20|read_write|test.py::TestGPIO::test_read_write|12ms 390us||<span style='color:green'>passed|
diff --git a/_sources/system_report.md.txt b/_sources/system_report.md.txt
@@ -0,0 +1,7 @@
+Protoplaster system report
+==================
+Protoplaster provides `protoplaster-system-report`, a tool to obtain information about system state and configuration. It executes a list of commands and saves their outputs. The outputs are stored in a single zip archive together with an HTML summary. An example summary can be found <a href="_static/system_report_summary.html">here</a>.
+
+The following config was used to generate the example:
+```{include} system-report-example.yml
+```