Skip to content

A
angle
Commit a833f200 by Cody Northrop Committed by Commit Bot
Options

Docs: Update ANGLE trace creation steps

Bug: angleproject:5677 Change-Id: I76ff3991f2124b27cd5c0cd9bad3754ae875cfc4 Reviewed-on: https://chromium-review.googlesource.com/c/angle/angle/+/2717102Reviewed-by: 's avatarJamie Madill <jmadill@chromium.org> Reviewed-by: 's avatarPaul Thomson <paulthomson@google.com> Reviewed-by: 's avatarTim Van Patten <timvp@google.com> Commit-Queue: Cody Northrop <cnorthrop@google.com>
parent 49babcbc
Showing with 222 additions and 52 deletions
src/tests/restricted_traces/README.md
...@@ -4,7 +4,7 @@ The files in this directory are traces of real applications. We host them ...@@ -4,7 +4,7 @@ The files in this directory are traces of real applications. We host them
internally because they may contain third party IP which we don't want internally because they may contain third party IP which we don't want
to share publicly. to share publicly.
## Setup ## Accessing the traces
In order to compile and run with these, you must be granted access by Google, In order to compile and run with these, you must be granted access by Google,
then authenticate with the cloud with your @google account: then authenticate with the cloud with your @google account:
...@@ -22,82 +22,252 @@ Then use gclient to pull down binary files from a cloud storage bucket. ...@@ -22,82 +22,252 @@ Then use gclient to pull down binary files from a cloud storage bucket.
``` ```
gclient runhooks gclient runhooks
``` ```
To build the tests, add the following GN argument: This should result in a number of directories created in `src/tests/restricted_traces` that contain
the trace files listed in [restricted_traces.json](restricted_traces.json):
```
$ ls -d src/tests/restricted_traces/*/
src/tests/restricted_traces/aliexpress/
src/tests/restricted_traces/angry_birds_2_1500/
src/tests/restricted_traces/arena_of_valor/
src/tests/restricted_traces/asphalt_8/
src/tests/restricted_traces/brawl_stars/
src/tests/restricted_traces/bus_simulator_indonesia/
src/tests/restricted_traces/candy_crush_500/
src/tests/restricted_traces/clash_of_clans/
src/tests/restricted_traces/clash_royale/
src/tests/restricted_traces/cod_mobile/
...
```
## Building the trace tests
To build for Android, follow the steps in [DevSetupAndroid.md](../../../doc/DevSetupAndroid.md)
(Recommend using the [`Performance`](../../../doc/DevSetupAndroid.md#performance-config) arguments
for best performance)
To build for Desktop, follow the steps in [DevSetup.md](../../../doc/DevSetup.md)
When that is working, add the following GN arg to your setup:
``` ```
build_angle_trace_perf_tests = true build_angle_trace_perf_tests = true
``` ```
Build the angle_perftests: To build the angle_perftests:
``` ```
autoninja -C out/Release angle_perftests autoninja -C out/<config> angle_perftests
``` ```
Run them like so: Run them like so:
``` ```
out/Release/angle_perftests --gtest_filter=TracePerfTest* out/<config>/angle_perftests --gtest_filter=TracePerfTest*
``` ```
## Updating traces # Adding new Android traces
Generally we want to use a Debug setup for recording new traces. That allows us to see asserts and
errors if the tracer needs to be improved.
Add the following GN arg to your Debug setup:
```
angle_with_capture_by_default = true
```
The GFXBench traces were captured on Windows after building gfxbench from source. We run capture commands in git bash. After [building](../../../doc/DevSetupAndroid.md#building-angle-for-android) and
[installing](../../../doc/DevSetupAndroid.md#install-the-angle-apk) the APK with the above arg,
we're ready to start capturing.
### Windows prep ## Determine the target app
We first need to identify which application we want to trace. That can generally be done by
looking at the web-based Play Store entry for your app. For instance, Angry Birds 2 is listed
here: https://play.google.com/store/apps/details?id=com.rovio.baba
Launch git bash via the 'git bash' command or via the start menu. Then run: If there is no Play Store entry for your app, there are a couple of ways you can determine the
app's name.
If you have a userdebug build of Android, you can check logcat when you launch the application.
You should see an entry like this:
``` ```
export PLATFORM=vs2019-x64 GraphicsEnvironment: ANGLE Developer option for 'com.rovio.baba' set to: 'default'
export TFW_PACKAGE_DIR=../../../build/vs2019-x64/testfw/tfw-dev
export ANGLE_DEFAULT_PLATFORM=vulkan
``` ```
If you just have an APK, you can use the following command to find the package name:
### Linux prep
``` ```
export PLATFORM=linux $ aapt dump badging angry_birds_2.apk | grep package
export LD_LIBRARY_PATH=. package: name='com.rovio.baba' versionCode='24900001' versionName='2.49.1' platformBuildVersionName=''
export TFW_PACKAGE_DIR=../../../build/linux/testfw_Release/tfw-dev
export ANGLE_DEFAULT_PLATFORM=vulkan
``` ```
You can also just guess at the package name, then check your device to see if it is installed. Keep
### Capturing from gfxbench trying combinations until you find it:
First start from the gfxbench source directory.
``` ```
cd out/install/$PLATFORM/lib $ adb shell pm list packages | grep rovio
python ../../../../scripts/refresh_angle_libs.py package:com.rovio.baba
```
# TRex Track the package name for use in later steps:
mkdir -p ../../../../../angle/src/tests/restricted_traces/trex_200 ```
ANGLE_CAPTURE_OUT_DIR=../../../../../angle/src/tests/restricted_traces/trex_200 ANGLE_CAPTURE_FRAME_START=200 ANGLE_CAPTURE_FRAME_END=210 ANGLE_CAPTURE_LABEL=trex_200 ../bin/testfw_app -b $TFW_PACKAGE_DIR --gfx egl -w 1920 -h 1080 -t gl_trex --ei -frame_step_time=40 export PACKAGE_NAME=com.rovio.baba
```
## Choose a trace label
Next, we need to chose a label for the trace. This is a style based choice, but we want to choose
something simple that identifies the app, then use snake case. This will end up being the name of
the trace, including the directory it is written to. Changing this value later is possible, but
tedious, since it will appear in all source files for the trace:
```
export LABEL=angry_birds_2
```
## Opt the application into ANGLE
Next, opt the application into using your ANGLE with capture enabled by default:
```
adb shell settings put global angle_debug_package org.chromium.angle
adb shell settings put global angle_gl_driver_selection_pkgs $PACKAGE_NAME
adb shell settings put global angle_gl_driver_selection_values angle
```
## Set up some Capture/Replay properties
We also need to set some debug properties used by the tracer.
# Manhattan Ensure frame capture is enabled. This might be redundant, but ensure the property isn't set to
mkdir -p ../../../../../angle/src/tests/restricted_traces/manhattan_10 zero, which disables frame capture.
ANGLE_CAPTURE_OUT_DIR=../../../../../angle/src/tests/restricted_traces/manhattan_10 ANGLE_CAPTURE_FRAME_START=10 ANGLE_CAPTURE_FRAME_END=20 ANGLE_CAPTURE_LABEL=manhattan_10 ../bin/testfw_app -b $TFW_PACKAGE_DIR --gfx egl -w 1920 -h 1080 -t gl_manhattan --ei -frame_step_time=40 ```
adb shell setprop debug.angle.capture.enabled 1
```
Empty the start and end frames. Again, this might be redundant, but it is less confusing.
```
adb shell setprop debug.angle.capture.frame_start '""'
adb shell setprop debug.angle.capture.frame_end '""'
```
Set the label to be used in the trace files
```
adb shell setprop debug.angle.capture.label $LABEL
```
Set a trigger value to be used by the tracer. This should be set to the *number of frames* you want
to capture. We typically use 10 to get an idea of how a scene is running, but some workloads
require more. Use your discretion here:
```
adb shell setprop debug.angle.capture.trigger 10
```
## Create output location
We need to write out the trace file in a location accessible by the app. We use the app's data
storage on sdcard, but create a subfolder to isolate ANGLE's files:
```
adb shell mkdir -p /sdcard/Android/data/$PACKAGE_NAME/angle_capture
```
## Start the target app
From here, you can start the application. You should see logcat entries like the following,
indicating that we've succesfully turned on capturing:
```
ANGLE : INFO: Capture trigger detected, disabling capture start/end frame.
ANGLE : INFO: Limiting binary format support count to zero while FrameCapture enabled
ANGLE : INFO: Limiting image unit count to 8 while FrameCapture enabled
ANGLE : INFO: Setting uniform buffer offset alignment to 256 while FrameCapture enabled
ANGLE : INFO: Disabling GL_EXT_map_buffer_range and GL_OES_mapbuffer during capture, which are not supported on some native drivers
ANGLE : INFO: Disabling GL_CHROMIUM_bind_uniform_location during capture, which is not supported on native drivers
ANGLE : INFO: Disabling GL_NV_shader_noperspective_interpolation during capture, which is not supported on some native drivers
ANGLE : INFO: Limiting draw buffer count to 4 while FrameCapture enabled
```
## Trigger the capture
When you have reached the content in your application that you want to record, set the trigger
value to zero:
```
adb shell setprop debug.angle.capture.trigger 0
```
In logcat we'll see another entry corresponding to this:
```
ANGLE : INFO: Capture triggered after frame 30440 for 10 frames
```
The app may pause briefly when the capture is completing. You can check its progress by looking at
the file system:
```
adb shell ls -la /sdcard/Android/data/$PACKAGE_NAME/angle_capture
```
Allow the app to run until the “*angledata.gz” file is non-zero and no longer growing. The app
should continue rendering after that:
```
$ adb shell ls -s -w 1 /sdcard/Android/data/$PACKAGE_NAME/angle_capture
30528 angry_birds_2_capture_context1.angledata.gz
8 angry_birds_2_capture_context1.cpp
4 angry_birds_2_capture_context1_files.txt
768 angry_birds_2_capture_context1_frame001.cpp
100 angry_birds_2_capture_context1_frame002.cpp
100 angry_birds_2_capture_context1_frame003.cpp
100 angry_birds_2_capture_context1_frame004.cpp
100 angry_birds_2_capture_context1_frame005.cpp
104 angry_birds_2_capture_context1_frame006.cpp
100 angry_birds_2_capture_context1_frame007.cpp
100 angry_birds_2_capture_context1_frame008.cpp
100 angry_birds_2_capture_context1_frame009.cpp
100 angry_birds_2_capture_context1_frame010.cpp
120 angry_birds_2_capture_context1_frame011.cpp
8 angry_birds_2_capture_context1.h
```
Note, you may see multiple contexts captured in the output. When this happens, look at the size of
the files. The larger files should be the context you care about it. You should move or delete the
other context files.
## Pull the trace files
Next, we want to pull those files over to the host and run some scripts.
```
cd $CHROMIUM_SRC/third_party/angle/src/tests/restricted_traces
mkdir -p $LABEL
adb pull /sdcard/Android/data/$PACKAGE_NAME/angle_capture/. $LABEL/
```
## Add the new trace to our list
The list of traces is tracked in [restricted_traces.json](restricted_traces.json).
# Egypt For simplicity, we use a tool called `jq` to update the list. This ensures we get them in
mkdir -p ../../../../../angle/src/tests/restricted_traces/egypt_1500 alphabetical order with no duplicates. It can also be done by hand if you are unable to install it,
ANGLE_CAPTURE_OUT_DIR=../../../../../angle/src/tests/restricted_traces/egypt_1500 ANGLE_CAPTURE_FRAME_START=1500 ANGLE_CAPTURE_FRAME_END=1510 ANGLE_CAPTURE_LABEL=egypt_1500 ../bin/testfw_app -b $TFW_PACKAGE_DIR --gfx egl -w 1920 -h 1080 -t gl_egypt --ei -frame_step_time=40 for some reason.
```
sudo apt-get install jq
```
Then run the following command:
```
jq ".traces = (.traces + [\"$LABEL\"] | unique)" restricted_traces.json \ | sponge restricted_traces.json
```
## Generate a sha1
For local testing, we must first create an empty sha1. This is to satisfy GN dependencies elsewhere
in the build. It will be overwritten with a real value if/when you upload the trace to our cloud
bucket:
```
touch ${LABEL}.tar.gz.sha1
``` ```
## Autogen the wrappers
We use two scripts to update the test harness so it will compile and run the new trace:
```
python ./gen_restricted_traces.py
cd ../../..
python ./scripts/run_code_generation.py
```
After this you should be able to `git diff` and see your new trace added to the harness files:
```
$ git diff --stat
scripts/code_generation_hashes/restricted_traces.json | 12 +++++++-----
src/tests/restricted_traces/.gitignore | 2 ++
src/tests/restricted_traces/restricted_traces.json | 1 +
src/tests/restricted_traces/restricted_traces_autogen.cpp | 19 +++++++++++++++++++
src/tests/restricted_traces/restricted_traces_autogen.gni | 1 +
src/tests/restricted_traces/restricted_traces_autogen.h | 1 +
6 files changed, 31 insertions(+), 5 deletions(-)
```
Note the absence of the traces themselves listed above. They are automatically .gitignored since
they won't be checked in directly to the repo.
## Upload to the cloud ## Upload to the cloud
Once you feel good about your trace, you can upload it to our collection of traces. Again, this
requires special access granted by Google.
Starting from you ANGLE root directory: Starting from your ANGLE root directory:
``` ```
cd src/tests/restricted_traces cd src/tests/restricted_traces
upload_to_google_storage.py --bucket chrome-angle-capture-binaries --archive trex_200 upload_to_google_storage.py --bucket chrome-angle-capture-binaries --archive $LABEL
upload_to_google_storage.py --bucket chrome-angle-capture-binaries --archive manhattan_10
upload_to_google_storage.py --bucket chrome-angle-capture-binaries --archive egypt_1500
``` ```
After uploading, the sha1 file you touched above will be populated.
After uploading, add the sha1 files created by the upload and submit them with your changes. ## Upload your CL
Before you can submit, you'll need to re-run the last code generation script to track the new sha1:
## Adding new tests ```
cd ../../..
After you capture and upload a set of frames from an application using the steps above you'll need to: python ./scripts/run_code_generation.py
```
* Add the new traces to [`restricted_traces/restricted_traces.json`](restricted_traces.json). The additional diff to reflect the new sha1 should be quite small:
* Re-run code generation with [`scripts/run_code_generation.py`][run_code_generation]. ```
* Update your CL to include the new generated code. Your trace tests should now be turned on. $ git diff --stat
scripts/code_generation_hashes/restricted_traces.json | 2 +-
[run_code_generation]: ../../../../scripts/run_code_generation.py src/tests/restricted_traces/angry_birds_2.tar.gz.sha1 | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
```
Add those to your CL and upload away!
```
git cl upload
```
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment