diff --git a/README.md b/README.md index 6abbaf8..df67dfd 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,93 @@ # rt-validation -Containers to validate real-time (PREEMPT_RT) support in TorizonCore +Containers to validate real-time (`PREEMPT_RT`) support in TorizonCore. + +The `stress-tests` container will run stress tests (CPU, memory, I/O) in the device. + +The `rt-tests` container will run `cyclictest` and generate a report of the measured latency. -# Build containers (on target machine) +# Prepare the device for the tests -For armhf: +Make sure you are running a `PREEMPT_RT` version of TorizonCore: ``` -docker build -t torizon/rt-validation-stress stress-tests -docker build -t torizon/rt-validation-rt rt-tests +$ cat /etc/os-release | grep PREEMPT_RT +NAME="Torizoncore Upstream with PREEMPT_RT" +PRETTY_NAME="Torizoncore Upstream with PREEMPT_RT 5.1.0-devel-20201216+build.152 (dunfell)" ``` -For arm64: +Make sure the device is connected to the internet (needed to generate network load): + ``` -docker build --build-arg IMAGE_ARCH=linux/arm64 -t torizon/rt-validation-stress stress-tests -docker build --build-arg IMAGE_ARCH=linux/arm64 -t torizon/rt-validation-rt rt-tests +$ ping -c 3 8.8.8.8 +PING 8.8.8.8 (8.8.8.8): 56 data bytes +64 bytes from 8.8.8.8: seq=0 ttl=118 time=12.344 ms +64 bytes from 8.8.8.8: seq=1 ttl=118 time=10.730 ms +64 bytes from 8.8.8.8: seq=2 ttl=118 time=12.080 ms +``` + +Mount a pendrive in `/mnt/pendrive` and make sure it has an archive file called `file.tar` (needed to generate USB read/write): + +``` +$ sudo mkdir -p /mnt/pendrive +$ sudo mount /dev/sda1 /mnt/pendrive +$ ls /mnt/pendrive/file.tar +-rw-rw-r-- 1 torizon torizon 1011353600 Dec 8 19:30 /mnt/pendrive/file.tar ``` -# Run the tests (on target machine) +# Run the stress-tests container + +Run the following command to execute the `stress-tests` container: + ``` -docker run --rm -it --privileged -v /dev:/dev -v /tmp:/tmp -v /media/$USER/YOUR-USB-DISK-MOUNTPOINT:/mnt/pendrive torizon/rt-validation-stress -docker run --rm -it --privileged -v /dev:/dev -v /tmp:/tmp torizon/rt-validation-rt +$ docker run --rm -d --name stress-tests --privileged -v /dev:/dev -v /tmp:/tmp -v /mnt/pendrive/:/mnt/pendrive torizon/stress-tests:$CT_TAG_STRESS_TESTS ``` + +Check if the stress tests started successfully: + +``` +$ docker logs stress-tests +Setting up stress tests... +RT stress tests started successfully! +``` + + +# Run the rt-tests container + +Run the following command to execute the `rt-tests` container and start measuring the latency: + +``` +$ docker run --rm -it --name rt-tests --cap-add=sys_nice --cap-add=ipc_lock --cap-add=sys_rawio --ulimit rtprio=99 --device-cgroup-rule='c 10:62 rmw' -v /dev:/dev -v /tmp:/tmp torizon/rt-tests:$CT_TAG_RT_TESTS +``` + +The tests will run for at most 12 hours, but can be interrupted at any time by pressing CTRL-C. + +After the tests are finished, stop the `stress-tests` container: + +``` +$ docker stop stress-tests +``` + + +# Analysing the results + +A summary of latency measurements will be available in `/tmp/latency-summary.log`: + +``` +$ cat /tmp/latency-summary.log +# /dev/cpu_dma_latency set to 0us +# Histogram +# Total: 000297214 000297199 000297189 000297179 +# Min Latencies: 00005 00005 00005 00005 +# Avg Latencies: 00023 00026 00023 00021 +# Max Latencies: 00081 00085 00077 00076 +# Histogram Overflows: 00000 00000 00000 00000 +# Histogram Overflow at cycle number: +# Thread 0: +# Thread 1: +# Thread 2: +# Thread 3: +``` + +A latency plot from cyclictest histogram data will be available in `/tmp/latency-plot.png`.