diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Android.markdown | 45 | ||||
| -rw-r--r-- | docs/BUGS.markdown | 215 | ||||
| -rw-r--r-- | docs/FORMAT.markdown | 128 | ||||
| -rw-r--r-- | docs/HACKING.markdown | 245 | ||||
| -rw-r--r-- | docs/INSTALL.markdown | 204 | ||||
| -rw-r--r-- | docs/NEWS.markdown | 102 | ||||
| -rw-r--r-- | docs/TODO.markdown | 1 | ||||
| -rw-r--r-- | docs/USAGE.markdown | 566 | ||||
| -rw-r--r-- | docs/VMWX_map_buffer_debug.txt | 116 |
9 files changed, 1622 insertions, 0 deletions
diff --git a/docs/Android.markdown b/docs/Android.markdown new file mode 100644 index 00000000..23064b83 --- /dev/null +++ b/docs/Android.markdown @@ -0,0 +1,45 @@ +# Tracing Java applications on Android # + +Android's Java virtual machine, runs as a system service (started at +bootup by `init`) and Java applications are run by forks of the initial +resident process. Thus, injecting apitrace's tracing library is different from +other operating systems. + +The following discussion assumes that tracing library is copied to `/data`: + + adb push /path/to/apitrace/libs/[arch]/egltrace.so /data + + +## Tracing on Android 4.0 and newer ## + +Starting from Android 4.0 (Ice Cream Sandwich) release, the system supports +running designated processes with wrappers, in which case a new Java VM is +started with 'system()' library call for that process. + +Obtain the process name of the application to be traced (the one reported in +`ps` output, such as `com.android.settings`), and set two system properties: + + PROCNAME=com.android.settings + adb root + adb shell ln -s /data/data/apitrace.github.io.eglretrace/libgnustl.so /data/libgnustl.so + adb shell setprop wrap.$PROCNAME LD_PRELOAD="/data/libgnustl_shared.so:/data/egltrace.so" + adb shell setprop debug.apitrace.procname $PROCNAME + +(the former is read by Dalvik and specifies wrapping prefix, the latter is +read by apitrace itself and used in case apitrace is preloaded into Java VM +globally to specify which process should be traced). Elevating privileges +via `adb root` is required to set the first property. + +If the `wrap.$PROCNAME` property name is longer than 31 characters [you'll need +to truncate it](https://github.com/apitrace/apitrace/issues/296). + +Make sure the process is not loaded before starting to trace it, for example +use `-S` flag to `am start`: + + adb shell am start -S $PROCNAME + +Use `adb logcat \*:S apitrace` to examine apitrace debug output. Trace files +are saved into `/data/data/$PROCNAME` directory by default: + + adb pull /data/data/$PROCNAME/$PROCNAME.trace + adb shell rm /data/data/$PROCNAME/$PROCNAME.trace diff --git a/docs/BUGS.markdown b/docs/BUGS.markdown new file mode 100644 index 00000000..2c35bac7 --- /dev/null +++ b/docs/BUGS.markdown @@ -0,0 +1,215 @@ +# Reporting bugs # + +Before reporting, please skim through the known issues below. + +Report any issues on [github](https://github.com/apitrace/apitrace/issues), +always including the following information: + +* operating system name and version + +* OpenGL/D3D driver name and version + + +# Known issues # + +These are issues that the developers are already aware of, but for which there +is no immediate plan to address them, because either: + +* they stem from architectural limitations that are difficult to overcome + and/or time-consuming; + +* they are corners cases that are thought to be of very little practical use; + +* merely lack of time/opportunity. + +That said, feel free to file an issue and/or send an email to the mailing list +if: + +* you want discuss the rationale, propose your ideas on how to address it, or + volunteer to work on it; + +* a known issue is important for you and you would like to see it addressed + sooner rather than later. + + +## Tracing ## + +* Fake calls may be emitted in the trace, in order to provide complete + information for retracing. The typical case is OpenGL vertex arrays in user + memory (as opposed to VBOs): where glXxxPointer calls will be deferred, + glInterleavedArrays will be decomposed, etc. + + This should not affect the rendered output, but it may use different paths in + the OpenGL driver, exercising different paths and with different performance + characteristics. + + There is no way to distinguish the fake calls from those actually + made by the application yet. + +* Huge traces will be generated for applications that make extensive use of + immediate mode drawing (ie., glBegin/glEnd), use vertex/element arrays in + user memory, or generate a lot of dynamic vertex data per frame. This is + because large quantities of (often redundant) data will be recorded over and + over; and although the traces are compressed, the compression algorithms used + aim a good performance/compression balance, hence fail to identify and remove + the redundancy at this scale. + + However, this should not be a problem for modern OpenGL applications that + make an efficient use of VBOs and vertex shaders. + +* On MacOSX, the internal OpenGL calls done by GLU are not traced yet. + + +## Retracing ## + +* Replaying can take substantially more CPU due to the overhead of reading the + trace file from disk. + + However, the overhead should not be significant for modern 3D applications + that do efficient use of VBOs and vertex shaders. The communication between + CPU to GPU can easily be a bottleneck on the powerful discrete GPUs of + nowadays, and trace overhead tend to be propotional so it is not a + coincidence that applications that are optimized for modern GPUs will also be + traced and replayed efficiently. + +* glretrace needs to infer window sizes from glViewport calls, because calls + that create/resize windows happen outside of OpenGL and are not traced. + Therefore window will be missing if the application relies on the default + viewport instead of explicitly invoking glViewport; or it will to too big if + the window is shrunk. Most apps call glViewport before rendering. + +* OS specific OpenGL APIs (WGL, GLX, CGL, etc), are not retraced literally, but + instead partially emulated. This is by design, to allow traces to be + retraced on any OS, as the focus is on the OS-independent parts of OpenGL API. + +* There is no guarantee that the same visual that was used on tracing will be + used for retracing OpenGL. Actually currently, glretrace will always choose + a standard 32bit RGBA, 24bit depth, 8bit alpha, double buffer visual. Unless + overridden on command line. + +* OpenGL context sharing is not fully respected -- all contexts are assumed to + share state. This is by far the most common case though. + + +## GUI ## + +* Not all types of arguments can be edited. + + + +# Proprietary/confidential applications # + +Issues should be preferably filed on github to facilitate collaborative +development and for future reference. + +Access to applications source code is not required -- binaries are sufficient. + +If the bug happens with a proprietary application, and you don't want to +publicly release the application and/or any data collected from it, then +alternatively you can provide the necessary application and/or data via e-mail, +to *jose dot r dot fonseca at gmail dot com*. + +If it is not technically/legally feasible for you to provide application and/or +data at all, then you must be either: + +* develop and provide a test application, stripped-down of all + proprietary/confidential data, but that can reproduce the issue; + +* be willing/able to do the investigation of the issue, namely to identify the + root cause of the issue (e.g., which OpenGL call is not properly handled and + why), using all necessary tools (such as debuggers). + +Failure to do so will render the apitrace authors powerless to address the +issue. + + +# Attachments # + +github issue tracker doesn't support attachments. + +Please attach long logs to https://gist.github.com/ and paste the URL into the +issue description. + +For big attachments, such as traces, please upload them temporarily to a web +server you control, or use a file upload service such as [Google +Drive](https://www.google.com/drive/) or [Dropbox](https://dropbox.com/) and +paste the URL into the issue description. + +Trace files are only slightly compressed (for performance reasons). You can +further reduce their size when attaching/uploading by compressing with +[XZ](http://tukaani.org/xz/) or [7-Zip](http://www.7-zip.org/). + + +# Bugs on tracing # + +For bugs that happen while tracing (e.g., crashes while tracing the +application, or incorrect traces) please: + +* provide information on how to obtain the application; + +* describe how you were using it when the issue happened. + + +# Bugs on retracing/GUI # + +For bugs on retracing (e.g. crashes when retracing the application, +incorrect inconsistent rendering, or viewing with the GUI) please: + +* provide the trace file; + +* describe the results you got, and what results you were expecting. + + +# Obtaining stack back-traces # + +Please rebuild apitrace with debugging information, by passing +`-DCMAKE_BUILD_TYPE=Debug` to cmake, or editing its value in `CMakeCache.txt` +and rebuilding. + +## Linux ## + +To obtain a stack back-trace, run the application with gdb from a terminal: + + $ gdb --args application arg1 arg2 ... + (gdb) run + ... + (gdb) bt + ... + (gdb) quit + +To trace an application inside GDB invoke apitrace as: + + apitrace trace --verbose --debug application arg1 ... + +See also more detailed and Distro specific instructions: + +* http://wiki.debian.org/HowToGetABacktrace + +* https://wiki.ubuntu.com/Backtrace + +* http://fedoraproject.org/wiki/StackTraces + +* http://live.gnome.org/GettingTraces + + +## Mac OS X ## + +Before you can debug you must first enable developer mode on the machine if you +haven't done so before: + + sudo /usr/sbin/DevToolsSecurity --enable + +To trace an application inside LLDB and obtain a stack backtrace invoke apitrace as: + + $ apitrace trace --verbose --debug application arg1 ... + ... + (lldb) bt + ... + (lldb) quit + + +## Windows ## + +See: + +* <https://developer.mozilla.org/en/how_to_get_a_stacktrace_with_windbg> diff --git a/docs/FORMAT.markdown b/docs/FORMAT.markdown new file mode 100644 index 00000000..08288a7c --- /dev/null +++ b/docs/FORMAT.markdown @@ -0,0 +1,128 @@ +# Trace binary format specification # + +This document specifies the binary format of trace streams. + +Trace streams are not written verbatim to file, but compressed, nowadays with +snappy (see `common/trace_file_snappy.cpp` for details). Previously they used +to be compressed with gzip. + + +## Versions ## + +We keep backwards compatability reading old traces, i.e., it should always be +possible to parse and retrace old trace files. + +The trace version number refers not only to changes in the binary format +representation, but also semantic changes in the way certain functions should +be retraced. + +| `version_no` | Changes | +| ------------ | ------- | +| 0 | initial implementation | +| 1 | support for OpenGL user arrays as blobs (whereas before calls that operated with user memory instead of VBOs should be ignored) | +| 2 | malloc/free memory calls | +| 3 | enums signatures with the whole set of name/value pairs | +| 4 | call enter events include thread no | +| 5 | support for call backtraces | + +Writing/editing old traces is not supported however. An older version of +apitrace should be used in such circunstances. + + +## Basic types ## + +| Type | Description | +| ---- | ----------- | +| `byte` | Raw byte. | +| `uint` | Variable-length unsigned integer, where the most significative bit is zero for last byte or non-zero if more bytes follow; the 7 least significant bits of each byte are used for the integer's bits, in little-endian order. | +| `float` | 32 bits single precision floating point number | +| `double` | 64 bits single precision floating point number | + +Strings are length-prefixed. The trailing zero is implied, not appearing neither in the length prefix nor in the raw bytes. + + string = count byte* + + count = uint + + +## Grammar ## + +The trace consists of a small header with version information, followed by an +arbitrary number of events. + + trace = version_no event* + + version_no = uint + +### Calls ### + +Calls consist of an enter and leave event pair. Calls are numbered from zero, +and the call number is implied for the enter event. + + event = 0x00 thread_no call_sig call_detail+ // enter call (version_no >= 4) + | 0x00 call_sig call_detail+ // enter call (version_no < 4) + | 0x01 call_no call_detail+ // leave call + + call_sig = id function_name count arg_name* // first occurrence + | id // follow-on occurrences + + call_detail = 0x00 // terminator + | 0x01 arg_no value // argument value + | 0x02 value // return value + | 0x03 thread_no // thread number (version_no < 4) + | 0x04 count frame* // stack backtrace + + arg_name = string + function_name = string + + arg_no = uint + call_no = uint + thread_no = uint + + id = uint + +### Values ### + + value = 0x00 // null pointer + | 0x01 // false value + | 0x02 // true + | 0x03 uint // negative integer + | 0x04 uint // positive integer value + | 0x05 float // single-precision floating point value + | 0x06 double // double-precision floating point value + | 0x07 string // character string value (zero terminator implied) + | 0x08 string // binary blob + | 0x09 enum_sig value // enumeration (version_no >= 3) + | 0x09 string value // enumeration (version_no < 3) + | 0x0a bitmask_sig value // integer bitmask + | 0x0b count value* // array + | 0x0c struct_sig value* // structure + | 0x0d uint // opaque pointer + | 0x0e value value // human-machine representation + | 0x0f wstring // wide character string value (zero terminator implied) + + enum_sig = id count (name value)+ // first occurrence + | id // follow-on occurrences + + bitmask_sig = id count (name value)+ // first occurrence + | id // follow-on occurrences + + struct_sig = id count member_name* // first occurrence + | id // follow-on occurrences + + name = string + member_name = string + + wstring = count uint* + +### Backtraces ### + + frame = id frame_detail+ // first occurrence + | id // follow-on occurrences + + frame_detail = 0x00 // terminator + | 0x01 string // module name + | 0x02 string // function name + | 0x03 string // source file name + | 0x04 uint // source line number + | 0x05 uint // byte offset from module start diff --git a/docs/HACKING.markdown b/docs/HACKING.markdown new file mode 100644 index 00000000..a8041b46 --- /dev/null +++ b/docs/HACKING.markdown @@ -0,0 +1,245 @@ +# Overview # + +Although focus was and still is on graphical APIs, apitrace has a +generic infrastructure to trace any kind of API: + + * the API's types and calls are specified in Python files in specs + sub-directory; + + * there is a type hierarchy in `specs/stdapi.py`, capable of representing + most types in C language, and additional semantic metadata + + * Python scripts generate C++ code to trace and serialize calls parameters to + a file, and vice-versa. + + * The _Visitor_ design pattern is used to navigate over the types. + + * The _Template_ design pattern is used to enable any step of code + generation to be overriden by derived classes, allowing to handle + cases that need special treatment without sacrifycing code reuse. + +apitrace's architecture is composed of several layers/components. There are +too many to show in a single graph, so only those relevant for OpenGL API are +illustrated below: + + specs + ^ + | + glproc + ^ ^ ^ + | | | + /------/ | \--\ + | | | + helpers | | + ^ ^ ^ | | + | | | | | + /--------/ | \----\ | | + | | | | | + | | | | | + trace retrace glstate glws + ^ ^ ^ ^ + | | | | + | \-----\ | /---/ + | | | | + | | | | + gltrace glretrace + ^ ^ ^ ^ + | | | | + /------/ | \-----\ | + | | | | + | | | | + glxtrace wgltrace cgltrace qapitrace + +Here is a quick synopsis of what the layers do: + + * `specs` -- specifies the types, functions, and interfaces of the API, + expressed as a hierarchy of Python objects + + * `dispatch` -- runtime dispatch of calls to DLLs (open the DLL, get the symbol + address, and call it passing all arguments as-is) + + * `glproc` -- specialization of the dispatch generation for GL APIs + + * `helpers` -- helper functions to determine sizes of arrays, blobs, etc. It + often needs to dispatch calls to give the answers. + + * `trace` -- generate C++ code for tracing an API based on its spec + + * `gltrace` -- specialization of the tracing generation for GL API, with extra + code to generate + + * `glxtrace`,` wgltrace`, `cgltrace` -- specialization of the tracing code for the + GLX, WGL, and CGL APIs. + + * `retrace` -- generate C++ code to interpret calls from trace, based on the + API's spec + + * `glretrace` -- specialization of the retrace code for the GL API + + * `glstate` -- code to dump OpenGL state to a JSON file + + * `glws` -- abstraction of the window system specific APIs (GXL, WGL, CGL), to + enable cross-platform portability of `glretrace` + + * `qapitrace` -- the GUI; it reads traces directly, and gets JSON state by + invoking `glretrace` + +The architecture for Direct3D APIs is similar, with the exception that, because +it's not cross platform, there are less specialized variations. + + +# Coding Style # + +These are guidelines for new code. Admittedly some of the existing code hasn't +been updated to follow these conventions yet. + +Whitespace (all languages): + + * indentation is 4 spaces + + * never use tabs as indents, except on Makefiles + + * otherwise tab equals to 8 spaces + + * separate classes with two empty lines + +Naming convention: + + * `camelCase` for functions/methods + + * `UpperCase` for structures/classes + + * `lowercase` for namespaces/modules + + * `UPPER_CASE` for #defines + + * single underscore prefix for variables/functions in automatically generated + code + +C++: + + * enclose single statement `if` clauses in `{` `}`, specially for + automatically generated code + + * `} else {` + + * use `inline` keyword for functions/methods which are called with high-frequency + +CMake: + + * `lower_case` commands + + * space between `(` and precedent name + + +And when in doubt, be consistent with the existing code. + + +# Commit policy # + +Feature development: + +* Existing features in master branch should not degrade at any time, for any + platform. Unless they are seldom used or redundant, and there is agreement. + + * In particular, new features / changes must not introduce any sort of + instability when tracing. + + While application developers and driver developers may be able to + workaround quirks in apitrace, we want to be able to obtain traces from + non-technical end-users with minimal intervention. + + This implies that tracing should not make any non-standard assumptions, and + care must be taken to ensure the tracing code is robust against invalid + parameters, multiple threads, etc. + +* It's fine to add new features for only some platforms or APIs. + +* Non-trivial changes should be staged in a branch, to allow review and + regression testing. Feature branches should be deleted once they have been + merged. + +* Releases are tagged commits from master. There are no stable branches. + + +Backwards compatibility: + +* Backwards binary compatibility with old traces must be always maintained: all + tools, including `glretrace`, must handle old traces without regressions. + +* No backwards compatibility guarantees for derived data (ASCII dumps, state, + images, etc). + +* There should be no gratuitous changes to command line tool interfaces, but no + guarantees are given. + + +# Regression testing # + +There is a regression test suite under development in +https://github.com/apitrace/apitrace-tests . + + +# Further reading # + +* [Writing ELF Shared Library Wrappers](https://github.com/amonakov/on-wrapping/blob/master/interposers-discussion.asciidoc) +* [Intercepting and Instrumenting COM Applications](https://www.usenix.org/legacy/events/coots99/full_papers/hunt/hunt_html) +* [Proxy-Dll: Intercept Calls to DirectX](http://www.mikoweb.eu/index.php?node=21) + + +# How to's # + +## How to support a new OpenGL extension ## + +All OpenGL (and OpenGL ES) function prototypes live in `specs/glapi.py`. This +file is semi-automatically derived from Khronos XML description of OpenGL / +OpenGL ES. To refresh do + + $ make -C specs/scripts/ glapi.py + $ meld specs/glapi.py specs/scripts/glapi.py + +and then port over new prototypes. See also `specs/scripts/README.markdown`. + +The upstream XML description is not rich enough to describe all semantic +details that apitrace needs, therefore one needs to manually tweak the +specifications: + +* Fix-up the types of array, blob, and pointer arguments. + + * For `glGet*` you can use `"_gl_param_size(pname)"` for automatically determining the number of parameters written, e.g. + + GlFunction(Void, "glGetIntegerv", [(GLenum, "pname"), Out(Array(GLint, "_gl_param_size(pname)"), "params")], sideeffects=False), + +* Add the `sideeffects=False` keyword argument where appropriate, so that those + calls can be merely ignored by `glretrace`. + +* Replace generically type `GLuint` object IDs with typed ones, (e.g., replace + `(GLuint, "texture")` into `(GLtexture, "texture")`, so that `glretrace` can + swizzle the objects IDs, when replaying on a different OpenGL implementation. + + +## Dump more OpenGL state ## + +TBD. + + +## Dump more D3D10/D3D11 parameter state ## + +In short, to dump another piece of state (e.g., `D3DXX_FOO_STATE`) you need to: + +* declare a + + void dumpStateObject(JSONWriter &, const D3DXX_FOO_STATE &); + + in `retrace/dxgistate_so.hpp` + +* add + + d3dxx.D3DXX_FOO_STATE, + + to the bottom of `retrace/dxgistate_so.py` so that C++ code to dump that structure is generated. + +* add a new `dumpFooState` function to `retrace/d3d10state.cpp` or `retrace/d3d11state.cpp`, similar to the existing `dumpBlendState` function, which gets the state object, and then calls `dumpStateObjectDesc` template and the generated `dumpStateObject` functions to do the grunt work. + +* update `dumpParameters` to call `dumpFooState` + diff --git a/docs/INSTALL.markdown b/docs/INSTALL.markdown new file mode 100644 index 00000000..10dcbc19 --- /dev/null +++ b/docs/INSTALL.markdown @@ -0,0 +1,204 @@ +# Requirements # + +Requirements common for all platforms: + +* C++ compiler + +* Python version 2.7 + + * Python Image Library + +* CMake version 2.8.11 or higher (tested with version 2.8.12.2) + +Optional dependencies: + +* zlib 1.2.6 or higher + +* libpng + +The GUI also dependends on: + +* Qt version 5.2.1 or higher (tested with version 5.4.0 and 5.3.0; use the + [6.1 release](https://github.com/apitrace/apitrace/releases/tag/6.1), if you + must build with Qt4) + +Qt will be required if `-DENABLE_GUI=TRUE` is passed to CMake, and never used +if `-DENABLE_GUI=FALSE` is passed instead. The implicit default is +`-DENABLE_GUI=AUTO`, which will build the GUI if Qt is available. + + +The code also depends on snappy libraries, but the bundled sources are always +used regardless of system availability, to make the wrapper shared-objects/DLL +self contained, and to prevent symbol collisions when tracing. + + +# Linux # + +Optional dependencies: + +* Xlib headers + +* libprocps (procps development libraries) + +* libdwarf + +Build as: + + cmake -H. -Bbuild -DCMAKE_BUILD_TYPE=RelWithDebInfo + make -C build + +Other possible values for `CMAKE_BUILD_TYPE` `Debug`, `Release`, +`RelWithDebInfo`, and `MinSizeRel`. + +You can also build the 32-bits GL wrapper on a 64-bits distribution, provided +you have a multilib gcc and 32-bits X11 libraries, by doing: + + cmake \ + -H. -Bbuild32 \ + -DCMAKE_C_FLAGS=-m32 \ + -DCMAKE_CXX_FLAGS=-m32 \ + -DCMAKE_SYSTEM_LIBRARY_PATH=/usr/lib32 \ + -DENABLE_GUI=FALSE + make -C build32 glxtrace + +The `/usr/lib32` refers to the path where the 32-bits shared objects are may +differ depending on the actual Linux distribution. + + +# Mac OS X # + +Build as: + + cmake -H. -Bbuild -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_PREFIX_PATH=~/QtX.Y.Z/X.Y/clang_64 + make -C build + + +# Android # + +Additional requirements: + +* [Android CMake](https://github.com/taka-no-me/android-cmake) +* [Android NDK](http://developer.android.com/sdk/ndk/index.html) +* [Android SDK](http://developer.android.com/sdk/index.html#Other). **Make sure you have Android 4.4.2 (API 19) platform SDK installed and Android build tools "21.1.2". API 19 is needed only to build the APK, but it will still run on lower API versions (with works starting with API 12).** + +Build as: + + wget -N https://raw.githubusercontent.com/taka-no-me/android-cmake/master/android.toolchain.cmake + + cmake \ + -H. -Bbuild \ + -DCMAKE_TOOLCHAIN_FILE=$PWD/android.toolchain.cmake \ + -DANDROID_NDK=/path/to/your/ndk \ + -DANDROID_API_LEVEL=9 \ + -DANDROID_STL=gnustl_shared \ + [-DANDROID_SDK=/path/to/your/sdk] + + make -C build + [make -C build retraceAPK] will build Android retrace APK. + [make -C build installRetraceAPK] will build & install Android retrace APK on the connected device. + +You can also choose a particular ABI by passing `ANDROID_ABI` variable to +cmake, e.g., `-DANDROID_ABI=x86`. Currently, when targeting AArch64 you [must +build with GCC](https://github.com/apitrace/apitrace/issues/312), by invoking +CMake as: + + cmake \ + -H. -Bbuild \ + -DCMAKE_TOOLCHAIN_FILE=$PWD/android.toolchain.cmake \ + -DANDROID_API_LEVEL=9 \ + -DANDROID_TOOLCHAIN_NAME=aarch64-linux-android-4.9 \ + -DANDROID_ABI=arm64-v8a + +** You'll need Android SDK only to build the retrace APK. ** + + +# FirefoxOS # + +Put Apitrace source tree into `B2GROOT/external/apitrace/` and the `Android.mk` +file (`B2GROOT/external/apitrace/Android.mk`) will do the needful to compile +and install apitrace appropriately into the system image as part of FirefoxOS +build process. It expects a linaro-type of Android NDK to be present in +`../../prebuilt/ndk/android-ndk-r7` (ie `B2GROOT/prebuilt/ndk/android-ndk-r7`). + + +# Windows # + +## Microsoft Visual Studio ## + +Additional requirements: + +* Microsoft Visual Studio 2013 or newer (tested with 2013) + +* [Windows 10 SDK](https://dev.windows.com/en-us/downloads/windows-10-sdk) + for D3D11.3 headers. + +* Microsoft DirectX SDK is now part of Microsoft Visual Studio (from version + 2012), but D3D8 headers are not included, so if you want D3D8 support you'll + need to donwload and install the + [August 2007 release of DirectX SDK](http://www.microsoft.com/downloads/details.aspx?familyid=529F03BE-1339-48C4-BD5A-8506E5ACF571) + +### CMake GUI ### + +To build with Visual Studio first invoke CMake GUI as: + + cmake-gui -H. -Bbuild -DCMAKE_PREFIX_PATH=C:\Qt\QtX.Y.Z\X.Y\msvc2013 + +and press the _Configure_ button. + +It will try to detect most required/optional dependencies automatically. When +not found automatically, you can manually specify the location of the +dependencies from the CMake GUI. + +If the source/build/compiler/tools are spread across multiple drives, you might +need to [use absolute paths](https://github.com/apitrace/apitrace/issues/352). + +After you've successfully configured, you can start the build by opening the +generated `build\apitrace.sln` solution file + +### CMake CLI ### + +Another option is to use the commandline to configure the project. First of all find out which +generators are available on your system: + + cmake --help + +At the end of the output, choose a generator and start configuring the project: + + cmake -H. -Bbuild -DCMAKE_PREFIX_PATH=C:\Qt\QtX.Y.Z\X.Y\msvc2013 -G "Visual Studio 12 2013" + +After you've successfully configured, you can start the build by invoking CMake as: + + cmake --build build --config MinSizeRel + +### Deployment ### + +To run qapitrace, either ensure that `C:\Qt\QtX.Y.Z\X.Y\msvc2013\bin` is in the system path, or use +[Qt's Windows deployment tool](http://doc.qt.io/qt-5/windows-deployment.html#the-windows-deployment-tool) +to copy all necessary DLLs, like: + + set Path=C:\Qt\QtX.Y.Z\X.Y\msvc2013\bin;%Path% + windeployqt build\qapitrace.exe + +### 64-bits ### + +The steps to build 64-bits version are similar, but choosing _Visual Studio xx +Win64_ instead of _Visual Studio xx_, and using `C:\Qt\QtX.Y.Z\X.Y\msvc2013_64` +for Qt path. + +### Windows XP ### + +By default, binaries generated by recent builds of Visual Studio will not work +on Windows XP. If you want to obtain binaries that work on Windows XP then +pass the `-T v120_xp` options to CMake when building with Visual Studio 2013. + +## MinGW ## + +Additional requirements: + +* [MinGW-w64](http://mingw-w64.sourceforge.net/) (tested with mingw-w64's gcc version 4.9) + +* [DirectX headers](https://github.com/apitrace/dxsdk) + +It's also possible to cross-compile Windows binaries from Linux with +[MinGW cross compilers](http://www.cmake.org/Wiki/CmakeMingw). + diff --git a/docs/NEWS.markdown b/docs/NEWS.markdown new file mode 100644 index 00000000..003eb3d1 --- /dev/null +++ b/docs/NEWS.markdown @@ -0,0 +1,102 @@ +This file lists the major user visible improvements. For a full list of changes +and their authors see the git history. + + +# Version 7 # + +* Native Android retrace with remote GUI + +* OpenGL ES 3 support + +* GUI ported to Qt5 + +* Thumbnails per draw call in GUI + +* Rudimentary D3D7 retrace support + + +# Version 6 # + +* OpenGL 4.5 support + +* DXGI 1.3 support + +* Support exporting buffers to disk from GUI + + +# Version 5 # + +* OpenGL 4.4 support + +* Stack backtraces on Linux + +* Better tracing of enums in attribute arrays + +* MD5 snapshots + +* Better surface viewer + + +# Version 4 # + +* Support tracing in Android, both native and Java applications + +* Show frame thumbnails in the GUI + +* Basic D3D 10.1, 11, and 11.1 trace support + +* Basic D3D retrace support + +* Multi-threaded trace/retrace support + +* Several OpenGL ES state dump fixes + +* GPU profiling + +* Thumbnails in GUI + +* Trim improvements + + +# Version 3 # + +* Top-level `apitrace` command + +* Trace and replay support for EGL, GLES1, and GLES2 APIs on Linux + +* Ability to trim traces + +* Basic CPU profiling when retracing + +* Basic D3D10 trace support + + +# Version 2 # + +* Flush/sync trace file only when there is an uncaught signal/exception, + yielding a 5x speed up while tracing + +* Employ snappy compression library instead of zlib, yielding a 2x speed up + while tracing + +* Implement and advertise `GL_GREMEDY_string_marker` and + `GL_GREMEDY_frame_terminator` extensions + +* Mac OS X support + +* Support up-to OpenGL 4.2 calls + +* Better GUI performance with very large traces, by loading frames from disk on + demand + + +# Version 1 # + +* Qt GUI, capable of visualizing the calls, the state, and editing the state + + +# Version 0 # + +* D3D8 and D3D9 trace support + +* OpenGL replay support diff --git a/docs/TODO.markdown b/docs/TODO.markdown new file mode 100644 index 00000000..d8375aee --- /dev/null +++ b/docs/TODO.markdown @@ -0,0 +1 @@ +Content moved to the [wiki](https://github.com/apitrace/apitrace/wiki/ToDo). diff --git a/docs/USAGE.markdown b/docs/USAGE.markdown new file mode 100644 index 00000000..89dcccf4 --- /dev/null +++ b/docs/USAGE.markdown @@ -0,0 +1,566 @@ +# Basic usage # + +Run the application you want to trace as + + apitrace trace --api API /path/to/application [args...] + +and it will generate a trace named `application.trace` in the current +directory. You can specify the written trace filename by passing the +`--output` command line option. + +Problems while tracing (e.g, if the application uses calls/parameters +unsupported by apitrace) will be reported via stderr output on Unices. On +Windows you'll need to run +[DebugView](http://technet.microsoft.com/en-us/sysinternals/bb896647) to view +these messages. + +If you cannot obtain a trace, check the [application specific instructions on +the wiki](https://github.com/apitrace/apitrace/wiki/Applications), or the +[manual tracing instructions below](#tracing-manually). + +View the trace with + + apitrace dump application.trace + +Replay an OpenGL trace with + + apitrace replay application.trace + +Pass the `--sb` option to use a single buffered visual. Pass `--help` to +`apitrace replay` for more options. + +If you run into problems [check if it is a known issue and file an issue if +not](BUGS.markdown). + + +# Basic GUI usage # + +Start the GUI as + + qapitrace application.trace + +You can also tell the GUI to go directly to a specific call + + qapitrace application.trace 12345 + +Press `Ctrl-T` to see per-frame thumbnails. And while inspecting frame calls, +press again `Ctrl-T` to see per-draw call thumbnails. + + +# Backtrace Capturing # + +apitrace now has the ability to capture the call stack to an OpenGL call on +certain OSes (only Android and Linux at the moment). This can be helpful in +determing which piece of code made that glDrawArrays call. + +To use the feature you need to set an environment variable with the list of GL +call prefixes you wish to capture stack traces to. + + export APITRACE_BACKTRACE="glDraw* glUniform*" + +The backtrace data will show up in qapitrace in the bottom section as a new tab. + + +# Advanced command line usage # + + +## Call sets ## + +Several tools take `CALLSET` arguments, e.g: + + apitrace dump --calls=CALLSET foo.trace + apitrace dump-images --calls=CALLSET foo.trace + apitrace trim --calls=CALLSET1 --calls=CALLSET2 foo.trace + +The call syntax is very flexible. Here are a few examples: + + * `4` one call + + * `0,2,4,5` set of calls + + * `"0 2 4 5"` set of calls (commas are optional and can be replaced with whitespace) + + * `0-100/2` calls 1, 3, 5, ..., 99 + + * `0-1000/draw` all draw calls between 0 and 1000 + + * `0-1000/fbo` all fbo changes between calls 0 and 1000 + + * `frame` all calls at end of frames + + * `@foo.txt` read call numbers from `foo.txt`, using the same syntax as above + + + +## Tracing manually ## + +### Linux ### + +On 64 bits systems, you'll need to determine whether the application is 64 bits +or 32 bits. This can be done by doing + + file /path/to/application + +But beware of wrapper shell scripts -- what matters is the architecture of the +main process. + +Run the GLX application you want to trace as + + LD_PRELOAD=/path/to/apitrace/wrappers/glxtrace.so /path/to/application + +and it will generate a trace named `application.trace` in the current +directory. You can specify the written trace filename by setting the +`TRACE_FILE` environment variable before running. + +For EGL applications you will need to use `egltrace.so` instead of +`glxtrace.so`. + +The `LD_PRELOAD` mechanism should work with the majority of applications. There +are some applications (e.g., Unigine Heaven, Android GPU emulator, etc.), that +have global function pointers with the same name as OpenGL entrypoints, living in a +shared object that wasn't linked with `-Bsymbolic` flag, so relocations to +those global function pointers get overwritten with the address to our wrapper +library, and the application will segfault when trying to write to them. For +these applications it is possible to trace by using `glxtrace.so` as an +ordinary `libGL.so` and injecting it via `LD_LIBRARY_PATH`: + + ln -s glxtrace.so wrappers/libGL.so + ln -s glxtrace.so wrappers/libGL.so.1 + ln -s glxtrace.so wrappers/libGL.so.1.2 + export LD_LIBRARY_PATH=/path/to/apitrace/wrappers:$LD_LIBRARY_PATH + export TRACE_LIBGL=/path/to/real/libGL.so.1 + /path/to/application + +If you are an application developer, you can avoid this either by linking with +`-Bsymbolic` flag, or by using some unique prefix for your function pointers. + +See the `ld.so` man page for more information about `LD_PRELOAD` and +`LD_LIBRARY_PATH` environment flags. + +### Android ### + +To trace standalone native OpenGL ES applications, use +`LD_PRELOAD=/path/to/egltrace.so /path/to/application` as described in the +previous section. To trace Java applications, refer to Android.markdown. + +### Mac OS X ### + +Run the application you want to trace as + + DYLD_FRAMEWORK_PATH=/path/to/apitrace/wrappers /path/to/application + +Note that although Mac OS X has an `LD_PRELOAD` equivalent, +`DYLD_INSERT_LIBRARIES`, it is mostly useless because it only works with +`DYLD_FORCE_FLAT_NAMESPACE=1` which breaks most applications. See the `dyld` man +page for more details about these environment flags. + +### Windows ### + +When tracing third-party applications, you can identify the target +application's main executable, either by: + +* right clicking on the application's icon in the _Start Menu_, choose + _Properties_, and see the _Target_ field; + +* or by starting the application, run Windows Task Manager (taskmgr.exe), right + click on the application name in the _Applications_ tab, choose _Go To Process_, + note the highlighted _Image Name_, and search it on `C:\Program Files` or + `C:\Program Files (x86)`. + +On 64 bits Windows, you'll need to determine ether the application is a 64 bits +or 32 bits. 32 bits applications will have a `*32` suffix in the _Image Name_ +column of the _Processes_ tab of _Windows Task Manager_ window. + +You also need to know which graphics API is being used. If you are unsure, the +simplest way to determine what API an application uses is to: + +* download and run [Process Explorer](http://technet.microsoft.com/en-us/sysinternals/bb896653.aspx) + +* search and select the application's process in _Process Explorer_ + +* list the DLLs by pressing `Ctrl + D` + +* sort DLLs alphabetically, and look for the DLLs such as `opengl32.dll`, + `d3d9.dll`, `d3d10.dll`, etc. + +Copy the appropriate `opengl32.dll`, `d3d8.dll`, or `d3d9.dll` from the +wrappers directory to the directory with the application you want to trace. +Then run the application as usual. + +You can specify the written trace filename by setting the `TRACE_FILE` +environment variable before running. + +For D3D10 and higher you really must use `apitrace trace -a DXGI ...`. This is +because D3D10-11 API span many DLLs which depend on each other, and once a DLL +with a given name is loaded Windows will reuse it for LoadLibrary calls of the +same name, causing internal calls to be traced erroneously. `apitrace trace` +solves this issue by injecting a DLL `dxgitrace.dll` and patching all modules +to hook only the APIs of interest. + + +## Emitting annotations to the trace ## + +### OpenGL annotations ### + +From within OpenGL applications you can embed annotations in the trace file +through the following extensions: + +* [`GL_KHR_debug`](http://www.opengl.org/registry/specs/KHR/debug.txt) + +* [`GL_ARB_debug_output`](http://www.opengl.org/registry/specs/ARB/debug_output.txt) + +* [`GL_EXT_debug_marker`](http://www.khronos.org/registry/gles/extensions/EXT/EXT_debug_marker.txt) + +* [`GL_EXT_debug_label`](http://www.opengl.org/registry/specs/EXT/EXT_debug_label.txt) + +* [`GL_AMD_debug_output`](http://www.opengl.org/registry/specs/AMD/debug_output.txt) + +* [`GL_GREMEDY_string_marker`](http://www.opengl.org/registry/specs/GREMEDY/string_marker.txt) + +* [`GL_GREMEDY_frame_terminator`](http://www.opengl.org/registry/specs/GREMEDY/frame_terminator.txt) + +**apitrace** will advertise and intercept these OpenGL extensions regardless +of whether the OpenGL implementation supports them or not. So all you have +to do is to use these extensions when available, and you can be sure they +will be available when tracing inside **apitrace**. + +For example, if you use [GLEW](http://glew.sourceforge.net/) to dynamically +detect and use OpenGL extensions, you could easily accomplish this by doing: + + void foo() { + + if (GLEW_KHR_debug) { + glPushDebugGroup(GL_DEBUG_SOURCE_APPLICATION, 0, -1, __FUNCTION__); + } + + ... + + if (GLEW_KHR_debug) { + glDebugMessageInsert(GL_DEBUG_SOURCE_APPLICATION, GL_DEBUG_TYPE_OTHER, + 0, GL_DEBUG_SEVERITY_MEDIUM, -1, "bla bla"); + } + + ... + + if (GLEW_KHR_debug) { + glPopDebugGroup(); + } + + } + +This has the added advantage of working equally well with other OpenGL debugging tools. + +Also, provided that the OpenGL implementation supports `GL_KHR_debug`, labels +defined via glObjectLabel() , and the labels of several objects (textures, +framebuffers, samplers, etc. ) will appear in the GUI state dumps, in the +parameters tab. + + +For OpenGL ES applications you can embed annotations in the trace file through the +[`GL_KHR_debug`](http://www.khronos.org/registry/gles/extensions/KHR/debug.txt) or +[`GL_EXT_debug_marker`](http://www.khronos.org/registry/gles/extensions/EXT/EXT_debug_marker.txt) +extensions. + + +### Direct3D annotations ### + +For Direct3D applications you can follow the standard procedure for +[adding user defined events to Visual Studio Graphics Debugger / PIX](http://msdn.microsoft.com/en-us/library/vstudio/hh873200.aspx): + +- `D3DPERF_BeginEvent`, `D3DPERF_EndEvent`, and `D3DPERF_SetMarker` for D3D9, + D3D10, and D3D11.0 applications. + +- `ID3DUserDefinedAnnotation::BeginEvent`, + `ID3DUserDefinedAnnotation::EndEvent`, and + `ID3DUserDefinedAnnotation::SetMarker` for D3D11.1 applications. + +And for [naming objects](http://blogs.msdn.com/b/chuckw/archive/2010/04/15/object-naming.aspx) +which support `SetPrivateData` method: + + pObject->SetPrivateData(WKPDID_D3DDebugObjectName, strlen(szName), szName); + +Note that [programmatic capture interfaces](https://msdn.microsoft.com/en-us/library/hh780905.aspx) +are currently _not_ supported. + +See also: + +* <http://seanmiddleditch.com/direct3d-11-debug-api-tricks/> + +* <http://blogs.msdn.com/b/chuckw/archive/2012/11/30/direct3d-sdk-debug-layer-tricks.aspx> + + +## Mask OpenGL features ## + +It's now possible to mask some of OpenGL features while tracing via a configuration file: + + * `$XDG_CONFIG_HOME/apitrace/gltrace.conf` or `$HOME/.config/apitrace/gltrace.conf` on Linux + + * `$HOME/Library/Preferences/apitrace/gltrace.conf` on MacOS X + + * `%LOCALAPPDATA%\apitrace\gltrace.conf` on Windows + +Here's an example `gltrace.conf` config file showing some variables: + + # comment line + GL_VERSION = "2.0" + GL_VENDOR = "Acme, Inc." + GL_EXTENSIONS = "GL_EXT_texture_swizzle GL_ARB_multitexture" + GL_RENDERER = "Acme rasterizer" + GL_SHADING_LANGUAGE_VERSION = "1.30" + GL_MAX_TEXTURE_SIZE = 1024 + +This basically overrides the respective `glGetString()` and `glGetIntegerv()` +parameters. + +String values are contained inside `""` pairs and may span multiple lines. +Integer values are given without quotes. + +## Identify OpenGL object leaks ## + +You can identify OpenGL object leaks by running: + + apitrace leaks application.trace + +This will print leaked object list and its generated call numbers. + +apitrace provides very basic leak tracking: it tracks all textures/ +framebuffers/renderbuffers/buffers name generate and delete call. If a object is not +deleted until context destruction, it's treated as 'leaked'. This logic doesn't +consider multi-context in multi-thread situation, so may report incorrect +results in such scenarios. + +To use this fomr the GUI, go to menu -> Trace -> LeakTrace + +## Dump OpenGL state at a particular call ## + +You can get a dump of the bound OpenGL state at call 12345 by doing: + + apitrace replay -D 12345 application.trace > 12345.json + +This is precisely the mechanism the GUI uses to obtain its own state. + +You can compare two state dumps by doing: + + apitrace diff-state 12345.json 67890.json + + +## Comparing two traces side by side ## + + apitrace diff trace1.trace trace2.trace + +This works only on Unices, and it will truncate the traces due to performance +limitations. + + +## Recording a video with FFmpeg/Libav ## + +You can make a video of the output with FFmpeg by doing + + apitrace dump-images -o - application.trace \ + | ffmpeg -r 30 -f image2pipe -vcodec ppm -i pipe: -vcodec mpeg4 -y output.mp4 + +or Libav (which replaces FFmpeg on recent Debian/Ubuntu distros) doing + + apitrace dump-images -o - application.trace \ + | avconv -r 30 -f image2pipe -vcodec ppm -i - -vcodec mpeg4 -y output.mp4 + + +## Recording a video with gstreamer ## + +You can make a video of the output with gstreamer by doing + + glretrace --snapshot-format=RGB -s - smokinguns.trace | gst-launch-0.10 fdsrc blocksize=409600 ! queue \ + ! videoparse format=rgb width=1920 height=1080 ! queue ! ffmpegcolorspace ! queue \ + ! vaapiupload direct-rendering=0 ! queue ! vaapiencodeh264 ! filesink location=xxx.264 + + +## Trimming a trace ## + +You can truncate a trace by doing: + + apitrace trim --calls 0-12345 -o trimed.trace application.trace + +If you need precise control over which calls to trim you can specify the +individual call numbers in a plain text file, as described in the 'Call sets' +section above. + +There is also experimental support for automatically trimming the calls +necessary for a given frame or call: + + apitrace trim-auto --calls=12345 -o trimed.trace application.trace + apitrace trim-auto --frames=12345 -o trimed.trace application.trace + + +## Profiling a trace ## + +You can perform gpu and cpu profiling with the command line options: + + * `--pgpu` record gpu times for frames and draw calls. + + * `--pcpu` record cpu times for frames and draw calls. + + * `--ppd` record pixels drawn for each draw call. + +The results from these can then be read by hand or analyzed with a script. + +`scripts/profileshader.py` will read the profile results and format them into a +table which displays profiling results per shader. + +For example, to record all profiling data and utilise the per shader script: + + apitrace replay --pgpu --pcpu --ppd foo.trace | ./scripts/profileshader.py + + +# Advanced usage for OpenGL implementers # + +There are several advanced usage examples meant for OpenGL implementors. + + +## Regression testing ## + +These are the steps to create a regression test-suite around **apitrace**: + +* obtain a trace + +* obtain reference snapshots, by doing on a reference system: + + mkdir /path/to/reference/snapshots/ + apitrace dump-images -o /path/to/reference/snapshots/ application.trace + +* prune the snapshots which are not interesting + +* to do a regression test, use `apitrace diff-images`: + + apitrace dump-images -o /path/to/test/snapshots/ application.trace + apitrace diff-images --output summary.html /path/to/reference/snapshots/ /path/to/test/snapshots/ + + +## Automated git-bisection ## + +With tracecheck.py it is possible to automate git bisect and pinpoint the +commit responsible for a regression. + +Below is an example of using tracecheck.py to bisect a regression in the +Mesa-based Intel 965 driver. But the procedure could be applied to any OpenGL +driver hosted on a git repository. + +First, create a build script, named build-script.sh, containing: + + #!/bin/sh + set -e + export PATH=/usr/lib/ccache:$PATH + export CFLAGS='-g' + export CXXFLAGS='-g' + ./autogen.sh --disable-egl --disable-gallium --disable-glut --disable-glu --disable-glw --with-dri-drivers=i965 + make clean + make "$@" + +It is important that builds are both robust, and efficient. Due to broken +dependency discovery in Mesa's makefile system, it was necessary to invoke `make +clean` in every iteration step. `ccache` should be installed to avoid +recompiling unchanged source files. + +Then do: + + cd /path/to/mesa + export LIBGL_DEBUG=verbose + export LD_LIBRARY_PATH=$PWD/lib + export LIBGL_DRIVERS_DIR=$PWD/lib + git bisect start \ + 6491e9593d5cbc5644eb02593a2f562447efdcbb 71acbb54f49089b03d3498b6f88c1681d3f649ac \ + -- src/mesa/drivers/dri/intel src/mesa/drivers/dri/i965/ + git bisect run /path/to/tracecheck.py \ + --precision-threshold 8.0 \ + --build /path/to/build-script.sh \ + --gl-renderer '.*Mesa.*Intel.*' \ + --retrace=/path/to/glretrace \ + -c /path/to/reference/snapshots/ \ + topogun-1.06-orc-84k.trace + +The trace-check.py script will skip automatically when there are build +failures. + +The `--gl-renderer` option will also cause a commit to be skipped if the +`GL_RENDERER` is unexpected (e.g., when a software renderer or another OpenGL +driver is unintentionally loaded due to a missing symbol in the DRI driver, or +another runtime fault). + + +## Side by side retracing ## + +In order to determine which draw call a regression first manifests one could +generate snapshots for every draw call, using the `-S` option. That is, however, +very inefficient for big traces with many draw calls. + +A faster approach is to run both the bad and a good OpenGL driver side-by-side. +The latter can be either a previously known good build of the OpenGL driver, or a +reference software renderer. + +This can be achieved with retracediff.py script, which invokes glretrace with +different environments, allowing to choose the desired OpenGL driver by +manipulating variables such as `LD_LIBRARY_PATH`, `LIBGL_DRIVERS_DIR`, or +`TRACE_LIBGL`. + +For example, on Linux: + + ./scripts/retracediff.py \ + --ref-env LD_LIBRARY_PATH=/path/to/reference/OpenGL/implementation \ + --retrace /path/to/glretrace \ + --diff-prefix=/path/to/output/diffs \ + application.trace + +Or on Windows: + + python scripts\retracediff.py --retrace \path\to\glretrace.exe --ref-env TRACE_LIBGL=\path\to\reference\opengl32.dll application.trace + + +# Advanced GUI usage # + +qapitrace has rudimentary support for replaying traces on a remote +target device. This can be useful, for example, when developing for an +embedded system. The primary GUI will run on the local host, while any +replays will be performed on the target device. + +In order to target a remote device, use the command-line: + + qapitrace --remote-target <HOST> <trace-file> + +In order for this to work, the following must be available in the +system configuration: + +1. It must be possible for the current user to initiate an ssh session + that has access to the target's window system. The command to be + exectuted by qapitrace will be: + + ssh <HOST> glretrace + + For example, if the target device is using the X window system, one + can test whether an ssh session has access to the target X server + with: + + ssh <HOST> xdpyinfo + + If this command fails with something like "cannot open display" + then the user will have to configure the target to set the DISPLAY + environment variable, (for example, setting DISPLAY=:0 in the + .bashrc file on the target or similar). + + Also, note that if the ssh session requires a custom username, then + this must be configured on the host side so that ssh can be + initiated without a username. + + For example, if you normally connect with `ssh user@192.168.0.2` + you could configure ~/.ssh/config on the host with a block such as: + + Host target + HostName 192.168.0.2 + User user + + And after this you should be able to connect with `ssh target` so + that you can also use `qapitrace --remote-target target`. + +2. The target host must have a functional glretrace binary available + +3. The target host must have access to <trace-file> at the same path + in the filesystem as the <trace-file> path on the host system being + passed to the qapitrace command line. diff --git a/docs/VMWX_map_buffer_debug.txt b/docs/VMWX_map_buffer_debug.txt new file mode 100644 index 00000000..254e08d3 --- /dev/null +++ b/docs/VMWX_map_buffer_debug.txt @@ -0,0 +1,116 @@ +Name + + VMWX_map_buffer_debug + +Name Strings + + GL_VMWX_map_buffer_debug + +Contact + + Jose Fonseca, VMware (jfonseca 'at' vmware.com) + +IP Status + + No known IP claims. + +Status + + Implemented by Apitrace + +Version + + Last Modified Date: December 14, 2014 + Version: 1 + +Number + + TBD. + +Dependencies + + GL_ARB_buffer_storage is required. + +Overview + + This extension provides a mechanism for the application to notify OpenGL + debugging tools that it modified ranges of persistent buffer mappings, + without explicitly flushing buffer ranges. + +New Procedures and Functions + + void NotifyMappedBufferRangeVMWX(const void * start, sizeiptr length); + +New Tokens + + Accepted in the <flags> parameter of BufferStorage: + + MAP_NOTIFY_EXPLICIT_BIT_VMWX 0x80000000 + + Accepted as part of the <access> parameter to MapBufferRange and + MapNamedBufferRange: + + MAP_NOTIFY_EXPLICIT_BIT_VMWX 0x80000000 + +Additions to Chapter 6 of the OpenGL Core Profile Specification, Version 4.3, +"Buffer Objects" + + Modify Section 6.2, "Creating and Modifying Buffer Object Data Stores" + + Add to the bulleted list describing flags that modify buffer storage + flags, p.57. + + * MAP_NOTIFY_EXPLICIT_BIT_VMWX indicates that the application will + notify whenever discrete subranges of coherent mappings are + notified. + + This flag may only be used in conjunction with MAP_PERSISTENT_BIT. + + Modify Section 6.3, "Mapping and Unmapping Buffer Data" + + Add to the bulleted list describing flags that modify buffer mappings, + p.62. + + * MAP_NOTIFY_EXPLICIT_BIT_VMWX indicates that discrete subranges of the + mapping will be notified explicitly when modified. + + When this flag is set, modifications to each subrange must be + explicitly flushed by calling NotifyMappedBufferRangeVMWX. + + This flag may only be used in conjunction with MAP_PERSISTENT_BIT. + + If this bit is set, the value of BUFFER_STORAGE_FLAGS for the buffer + being mapped must include MAP_NOTIFY_EXPLICIT_BIT_VMWX. + +Issues + + 1) Why is this extension necessary? + + It is true that an application may be friendly towards OpenGL debugging + tools that intercept calls by ensuring that MAP_PERSISTENT_BIT is always + set with MAP_FLUSH_EXPLICIT_BIT, and never with MAP_COHERENT_BIT. But + this restricts/deviates from intended behavior. This extensions provides + a mechanism for applications to notify debugging tools without affecting + behavior. + + + 2) Why the new MAP_NOTIFY_EXPLICIT_BIT_VMWX token? + + To be future-proof. + + In order to record complete traces, OpenGL tracing tools may choose to + mask out support for coherent mappings by failing BufferStorage calls with + OUT_OF_MEMORY when MAP_COHERENT_BIT is set without + MAP_NOTIFY_EXPLICIT_BIT_VMWX; or use techniques to approximately detect + writes to coherent mappings if the application calls MapBufferRange with + MAP_COHERENT_BIT and MAP_NOTIFY_EXPLICIT_BIT_VMWX. + + It is therefore crucial that applications that want to explicitily notify + modified subranges with calls NotifyMappedBufferRangeVMWX set the + MAP_NOTIFY_EXPLICIT_BIT_VMWX bit both on BufferStorage and MapBufferRange + calls, to opt-out of further interference from debugging tools. + + +Revision History + + Version 1, 2014/12/14 - Initial version |