docs: media: add usage documentation for the VDA/VEA unittests

This document used to be maintained as a Google Docs, but having it
available in the Chromium repository makes it much easier to access for
partners.

BUG=None
TEST=Generated and checked HTML using Markdown.

Change-Id: I790504be2720150cebee151a585a2435ac35a494
Reviewed-on: https://chromium-review.googlesource.com/c/1322174
Commit-Queue: Alexandre Courbot <acourbot@chromium.org>
Reviewed-by: Hirokazu Honda <hiroh@chromium.org>
Cr-Commit-Position: refs/heads/master@{#606390}

docs/README.md

@@ -282,6 +282,8 @@ used when committed.
 *   [Autoplay of HTMLMediaElements](media/autoplay.md) - How HTMLMediaElements
     are autoplayed.
 *   [Piranha Plant](piranha_plant.md) - Future architecture of MediaStreams
+*   [Video Decode/Encode Accelerator Tests](media/gpu/vdatest_usage.md) - How to
+    use the accelerated video decoder/encoder test programs.
 
 ### Accessibility
 *   [Accessibility Overview](accessibility/overview.md) - Overview of

docs/media/gpu/vdatest_usage.md

+# Using the Video Decode/Encode Accelerator Unittests Manually
+
+VDAtest (or `video_decode_accelerator_unittest`) and VEAtest (or
+`video_encode_accelerator_unittest`) are unit tests that embeds the Chrome video
+decoding/encoding stack without requiring the whole browser, meaning they can
+work in a headless environment. They includes a variety of tests to validate the
+decoding and encoding stacks with h264, vp8 and vp9.
+
+Running these tests manually can be very useful when bringing up a new codec, or
+in order to make sure that new code does not break hardware decoding and/or
+encoding. This document is a walk though the prerequisites for running these
+programs, as well as their most common options.
+
+## Prerequisites
+
+The required kernel drivers should be loaded, and there should exist a
+`/dev/video-dec0` symbolic link pointing to the decoder device node (e.g.
+`/dev/video-dec0` → `/dev/video0`). Similarly, a `/dev/video-enc0` symbolic
+link should point to the encoder device node.
+
+The unittests can be built by specifying the `video_decode_accelerator_unittest`
+and `video_encode_accelerator_unittest` targets to `ninja`. If you are building
+for an ARM board that is not yet supported by the
+[simplechrome](https://chromium.googlesource.com/chromiumos/docs/+/master/simple_chrome_workflow.md)
+workflow, use `arm-generic` as the board. It should work across all ARM targets.
+
+For unlisted Intel boards, any other Intel target (preferably with the same
+chipset) should be usable with libva. AMD targets can use `amd64-generic`.
+
+## Basic VDA usage
+
+The `media/test/data` folder in Chromium's source tree contains files with
+encoded video data (`test-25fps.h264`, `test-25fps.vp8` and `test-25fps.vp9`).
+Each of these files also has a `.md5` counterpart, which contains the md5
+checksums of valid thumbnails.
+
+Running the VDAtest can be done as follows:
+
+    ./video_decode_accelerator_unittest --disable_rendering --single-process-tests --test_video_data=test_video
+
+Where test_video is of the form
+
+    filename:width:height:numframes:numfragments:minFPSwithRender:minFPSnoRender:profile
+
+The correct value of test_video for each test file follows:
+
+* __H264__: `test-25fps.h264:320:240:250:258:35:150:1`
+* __VP8__: `test-25fps.vp8:320:240:250:250:35:150:11`
+* __VP9__: `test-25fps.vp9:320:240:250:250:35:150:12`
+
+So in order to run all h264 tests, one would invoke
+
+    ./video_decode_accelerator_unittest --disable_rendering --single-process-tests --test_video_data=test-25fps.h264:320:240:250:258:35:150:1
+
+## Test filtering options
+
+`./video_decode_accelerator_unittest --help` will list all valid options.
+
+The list of available tests can be retrieved using the `--gtest_list_tests`
+option.
+
+By default, all tests are run, which can be a bit too much, especially when
+bringing up a new codec. The `--gtest_filter` option can be used to specify a
+pattern of test names to run. For instance, to only run the
+`TestDecodeTimeMedian` test, one can specify
+`--gtest_filter="*TestDecodeTimeMedian*"`.
+
+So the complete command line to test vp9 decoding with the
+`TestDecodeTimeMedian` test only (a good starting point for bringup) would be
+
+    ./video_decode_accelerator_unittest --disable_rendering --single-process-tests --test_video_data=test-25fps.vp9:320:240:250:250:35:150:12 --gtest_filter="*TestDecodeTimeMedian*"
+
+## Verbosity options
+
+The `--vmodule` options allows to specify a set of source files that should be
+more verbose about what they are doing. For basic usage, a useful set of vmodule
+options could be:
+
+    --vmodule=*/media/gpu/*=4
+
+## Testing performance
+
+Use the `--disable_rendering --rendering_fps=0 --gtest_filter="DecodeVariations/*/0"`
+options to max the decoder output and measure its performance.
+
+## Testing parallel decoding
+
+Use `--gtest_filter="ResourceExhaustion*/0"` to run 3 decoders in parallel, and
+`--gtest_filter="ResourceExhaustion*/1"` to run 4 decoders in parallel.
+
+## Wrap-up
+
+Using all these options together, we can invoke VDAtest in the following way for
+a verbose H264 decoding test:
+
+    ./video_decode_accelerator_unittest --single-process-tests --disable_rendering --gtest_filter="*TestDecodeTimeMedian*" --vmodule=*/media/gpu/*=4 --test_video_data=test-25fps.h264:320:240:250:258:35:150:1
+
+## Basic VEA usage
+
+The VEA works in a similar fashion to the VDA, taking raw YUV files in I420
+format as input and producing e.g. a H.264 Annex-B byte stream. Sample raw YUV
+files can be found at the following locations:
+
+* [1080 Crowd YUV](http://commondatastorage.googleapis.com/chromiumos-test-assets-public/crowd/crowd1080-96f60dd6ff87ba8b129301a0f36efc58.yuv)
+* [320x180 Bear YUV](http://commondatastorage.googleapis.com/chromiumos-test-assets-public/bear/bear-320x180-c60a86c52ba93fa7c5ae4bb3156dfc2a.yuv)
+
+It is recommended to rename these files after downloading them to e.g.
+`crowd1080.yuv` and `bear-320x180.yuv`.
+
+The VEA can then be tested as follows:
+
+    ./video_encode_accelerator_unittest --single-process-tests --disable_flush --gtest_filter=SimpleEncode/VideoEncodeAcceleratorTest.TestSimpleEncode/0 --test_stream_data=bear-320x180.yuv:320:180:1:bear.mp4:100000:30
+
+for the `bear` file, and
+
+    ./video_encode_accelerator_unittest --single-process-tests --disable_flush --gtest_filter=SimpleEncode/VideoEncodeAcceleratorTest.TestSimpleEncode/0 --test_stream_data=crowd1080.yuv:1920:1080:1:crowd.mp4:4000000:30
+
+for the larger `crowd` file. These commands will put the encoded output into
+`bear.mp4` and `crowd.mp4` respectively. They can then be copied on the host and
+played with `mplayer -fps 25`.
+
+## Source code
+
+The VDAtest's source code can be consulted here: [https://cs.chromium.org/chromium/src/media/gpu/video_decode_accelerator_unittest.cc](https://cs.chromium.org/chromium/src/media/gpu/video_decode_accelerator_unittest.cc).
+
+V4L2 support: [https://cs.chromium.org/chromium/src/media/gpu/v4l2/](https://cs.chromium.org/chromium/src/media/gpu/v4l2/).
+
+VAAPI support: [https://cs.chromium.org/chromium/src/media/gpu/vaapi/](https://cs.chromium.org/chromium/src/media/gpu/vaapi/).