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}
This commit is contained in:

committed by
Commit Bot

parent
ae644809e5
commit
2cad5de594
docs
@ -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
|
||||
|
128
docs/media/gpu/vdatest_usage.md
Normal file
128
docs/media/gpu/vdatest_usage.md
Normal file
@ -0,0 +1,128 @@
|
||||
# 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/).
|
Reference in New Issue
Block a user