diff options
Diffstat (limited to 'chromium/docs/website/site/nativeclient/how-tos')
42 files changed, 2067 insertions, 0 deletions
diff --git a/chromium/docs/website/site/nativeclient/how-tos/3d-tips-and-best-practices/index.md b/chromium/docs/website/site/nativeclient/how-tos/3d-tips-and-best-practices/index.md new file mode 100644 index 00000000000..8e3ae771ead --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/3d-tips-and-best-practices/index.md @@ -0,0 +1,146 @@ +--- +breadcrumbs: +- - /nativeclient + - Native Client +- - /nativeclient/how-tos + - '2: How Tos' +page_name: 3d-tips-and-best-practices +title: 3D Tips and Best Practices +--- + +# Pepper 3D on Chrome provides a secure implementation of OpenGL ES 2.0. Here are some tips for getting maximum performance. + +## Don’t update indices + +For security all indices must be validated. If you change them we have to +validate them again. Therefore structure your code so indices are not updated +often. + +## Don’t use client side buffers + +In OpenGL ES 2.0 you can use client side data with glVertexAttribPointer and +glDrawElements. It’s REALLY SLOW! Don’t use them. Instead, whenever possible use +VBOs (Vertex Buffer Objects). Side-note: Client side buffers have been removed +from OpenGL 4.0. + +## Don’t mix vertex data with index data. + +Actually this is off by default. In real OpenGL ES 2.0 you can create a single +buffer and bind it to both GL_ARRAY_BUFFER and GL_ELEMENT_ARRAY_BUFFER. In +Pepper 3D, by default, you can only bind buffers to 1 bind point. There is the +option to enable binding buffers to both points. Doing so requires expensive +work so don’t do it. + +## For dynamic textures (ie, video) or dynamic vertex data (skinning / particles) consider using CHROMIUM_map_sub + +<http://src.chromium.org/viewvc/chrome/trunk/src/gpu/GLES2/extensions/CHROMIUM/CHROMIUM_map_sub.txt> + +## Don’t call glGetXXX or glCheckXXX during rendering. + +Calling either of those stalls our multi-process pipeline. This is normal advice +for OpenGL programs but is particularly important for 3D on Chrome. This +includes glGetError – avoid calling it in release builds. + +## Make sure to enable Attrib 0. + +In OpenGL you MUST enable Attrib 0. In OpenGL ES 2.0 you don’t have to enable +Attrib 0. What that means is that in order to emulate OpenGL ES 2.0 on top of +OpenGL we have to do some expensive work. +In practice most programs don’t have an issue here but just in case, the most +obvious way this might bite you is if you bind your own locations and don’t +start with 0. Example: Imagine you have a vertex shader with 2 attributes +“positions” and “normals” + +> glBindAttribLocation(program, “positions”, 1); + +> glBindAttribLocation(program, “normals”, 2); + +Those 2 functions would make make your shader NOT use attrib 0 in which case +we’d have to do some expensive work internally + +## Minimize the use of glFlush and avoid using glFinish + +It is generally good practice to minimize explicit calls to glFlush and avoid +using glFinish. Particularly so on Native Client where they incur additional +overhead. + +## Avoid reading back output from the GPU to the client + +In other words, don't call glReadPixels. This is slow. + +**When benchmarking, avoid comparing results where one system is limited by +vsync and another is not.** + +## Don’t use GL_FIXED + +It’s not supported in OpenGL and so emulation for OpenGL ES 2.0 is slow. By +default GL_FIXED support is turned off Pepper 3D. There is the option to turn it +on. Don’t do it. + +## Use a smaller plugin and let CSS scale it. + +The size your plugin renders and the size it displays in the page are set +separately. CSS controls the size your plugin displays where as the width and +height attribute of your <embed> element control the size your plugin +renders. + +## Use HTML where approriate + +If you’re used to making native games you’re probably used to rendering +everything yourself. The browser though can already render text and UI very well +and it will composite that HTML with your plugin using all the standard HTML5 +and CSS methods available. + +**Avoid updating a small portion of a large buffer** + +This is especially an issue in Windows where we emulate OpenGL ES 2.0 on top of +DirectX. In the current implementation, updating a portion of a buffer requires +re-processing the entire buffer. In other words if you make a buffer +(glBufferData) of 10000 bytes and then later call glSubBufferData to update just +3 of those bytes, all 10000 bytes will have to be re-converted. (Yea, I know, +lame) + +2 suggestions: + +1. Separate static vertex data from dynamic. In other words, put your + static data in 1 buffer and dynamic data in a different buffer. That + way your static data won't have to be re-converted. +2. Volunteer to fix the perf issues + <http://angleproject.googlecode.com> + +# General OpenGL advice + +## Interleaved data is faster to render than non-interleaved + +3 buffers of \[position,position,position\], \[normal,normal,normal\], +\[texcoord,texcoord,texcoord\] is slower than 1 buffer of +\[position,normal,texcoord,position,normal,texcoord,position,normal,texcoord\]. + +## Separate dynamic data from static + +Assume you have positions, normals and texcoords. Further assume you update +positions every frame. It would be best to put positions in 1 buffer and normals ++ texcoords in a separate buffer. That way, you can call glBufferData or +glBufferSubData on a smaller range of data. + +## glBindBuffer is expensive + +Consider putting multiple meshes in a single buffer and using offsets (as long +as the buffers are static, see above) + +## Check your extensions and max GL features + +Not every GPU supports every extension nor has the same amount of textures +units, vertex attributes, etc. Make sure you check for the features you need. +For example, if you are using non power of 2 texture with mips make sure +GL_OES_texture_npot exists. If you are using floating point textures make sure +GL_OES_texture_float exists. If you are using DXT1, DXT3 or DXT5 texture make +sure GL_ETC_texture_compression_dxt1, GL_CHROMIUM_texture_compression_dxt3 and +GL_CHROMIUM_texture_compression_dxt5 exist. +If you are using textures in vertex shaders make sure +glGetIntegerv(GL_MAX_VERTEX_TEXTURE_IMAGE_UNITS, …) returns a value greater than +0. +If you are using more than 8 textures in a single shader make sure +glGetIntegerv(GL_MAX_TEXTURE_IMAGE_UNITS, …) returns a value greater than or +equal to the number of simulatious textures you need. +etc...
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/build-tcb/index.md b/chromium/docs/website/site/nativeclient/how-tos/build-tcb/index.md new file mode 100644 index 00000000000..3c3096382d7 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/build-tcb/index.md @@ -0,0 +1,287 @@ +--- +breadcrumbs: +- - /nativeclient + - Native Client +- - /nativeclient/how-tos + - '2: How Tos' +page_name: build-tcb +title: Building and Testing the Native Client Trusted Code Base +--- + +[TOC] + +## What build system(s) is Native Client using? + +The primary build system used by Native Client is [SCons](http://www.scons.org). +For historical reasons we are not using plain [SCons](http://www.scons.org/) but +an extension call Hammer. + +The parts of the system shared with Chrome are also built using Chrome's build +system, GN. + +We also have some Makefiles and some shell scripts for certain build tasks. + +## Why is this such a complex mess? + +The usual excuses: + +* Inherent complexity. +* Historical reasons. +* Entropy requires no maintenance. +* ... + +## Which files contain build system information? + +For [SCons](http://www.scons.org/) it is: SConstruct, \*\*/build.scons, +\*\*/nacl.scons There are also relevant configuration files in +site_scons/site_tools/\*, and random Python scripts located here and there. + +For GN it is: \*\*/BUILD.gn and \*\*/config.gni + +## What is the difference between trusted and untrusted code? + +"Trusted code" encompasses components like: + +* the browser plugin +* service runtime (sel_ldr) + +It is compiled using regular compilers. Bugs in trusted code can compromise +system security, hence the name. As far as the build system is concerned trusted +code is described in \*\*/build.scons files. Trusted code lives in +src/trusted/\*\* + +"Untrusted code" encompasses components like: + +* quake and other examples of Native Client executables +* libraries necessary to build those executables +* The IRT + +It is compiled using special sandboxing compilers. As far as the build system is +concerned, untrusted code is described in \*\*/nacl.scons files. Untrusted code +lives in src/untrusted/\*\* and also in tests/\*\* + +Some code can be compiled either as trusted or shared code, e.g. libraries that +facilitate communication between trusted and untrusted code. Such code typically +lives in src/shared/\*\* and has both build.scons and nacl.scons files. + +## How do you use the MODE= setting when invoking SCons? + +The MODE= setting or its equivalent --mode is used to select whether you want to +compile trusted or untrusted code or both and how. Examples: + +MODE=nacl + +* just build untrusted code +* note that this doesn't build all of the untrusted code. If you don't + specify a trusted platform (e.g. MODE=opt-linux,nacl) most of the + tests will not be built. + +MODE=opt-linux + +* just build (optimized) trusted code - you must be on a Linux system + +MODE=nacl,dbg-win + +* build both (trusted code will be unoptimized) - you must be on a + Windows system + +NOTE: if you do not specify MODE, "opt-*<your-system-os>"* will be +assumed. + +NOTE: if you want to run integration tests, you need to build both trusted and +untrusted code simultaneously, because those tests involve running untrusted +code under the control of trusted code. + +What is the meaning of BUILD_ARCH, TARGET_ARCH, etc. ? + +Just like any cross compilation environment, there are some hairy configuration +issues which are controlled by BUILD_ARCH, TARGET_ARCH, etc. to force +conditional compilation and linkage. + +It helps to revisit the +[terminology](http://www.airs.com/ian/configure/configure_5.html) used by cross +compilers to better understand Native Client: + +> BUILD_SYSTEM: The system on which the tools will be built (initially) is +> called the build system. + +> HOST_SYSTEM: The system on which the tools will run is called the host system. + +> TARGET_SYSTEM: The system for which the tools generate code is called the +> target system. + +For [NaCl](/p/nativeclient/wiki/NaCl) we only have **two** of these, sadly they +have confusing names: + +> BUILD_PLATFORM: The system on which the trusted code runs. + +> TARGET_PLATFORM: The sandbox system that is being enforced by the trusted +> code. + +The BUILD_PLATFORM is closest in nature to the HOST_SYSTEM, the TARGET_PLATFORM +is closest to the TARGET_SYSTEM. We do not have an equivalent to BUILD_SYSTEM +since we just assume the build system is x86 (either a 32- or 64-bit system). + +## What kind of BUILD_PLATFORM/TARGET_PLATFORM configurations are supported? + +Conceptually we have + +> BUILD_PLATFORM = (BUILD_ARCH, BUILD_SUBARCH, BUILD_OS) + +and + +> TARGET_PLATFORM = (TARGET_ARCH. TARGET_SUBARCH) + +NOTE: + +There is no TARGET_OS, since Native Client executables are OS independent. + +The BUILD_OS is usually tested for using [SCons](http://www.scons.org/) +expressions like "env.Bit('windows')". You cannot really control it as it is +inherited from the system you are building on, the BUILD_SYSTEM in cross +compiler speak. + +Enumeration of all BUILD_PLATFORMs: + +(x86, 32, linux) (x86, 32, windows) (x86, 32, mac) (arm, 32, linux) // the 32 is +implicit as there is no 64bit arm + +(x86, 64, linux) (x86, 64, windows) + +***Special note for Windows users:** The Windows command-line build currently +relies on vcvarsXX.bat being called to set up the environment. The compiler's +target subarchitecture (32,64) is selected by the version of vcvars that you +called (vcvars32/vcvars64). If you call vcvars32 and then build with +platform=x86-64, you will get "target mismatch" errors.* + +Enumeration of all TARGET_PLATFORMs: (x86, 32) (x86, 64) (arm, 32) // the 32 is +implicit as there is no 64bit arm + +Usually BUILD_ARCH == TARGET_ARCH and BUILD_SUBARCH == TARGET_SUBARCH + +There is ONLY ONE exception, you can build the ARM validator like so: + +> BUILD_ARCH = x86, BUILD_SUBARCH=**, TARGET_ARCH=arm TARGET_SUBARCH=32** + +**In particular it is NOT possible to use different SUBARCHs for BUILD and +TARGET.** + +## What is the relationship between TARGET_PLATFORM and untrusted code? + +The flavor of the untrusted code is derived from the TARGET_PLATFORM + +## Why are *BUILD and ARCH* used inconsistently? + +Usually BUILD_ARCH == TARGET_ARCH and BUILD_SUBARCH == TARGET_SUBARCH so +mistakes have no consequences. + +## So how do I build something? (Finally!) + +\[Note: scons --download has been deprecated as of Aug 17, 2010\] + +The first time you build, you will need to get the latest toolchain build. Do +this using gclient hooks: + +```none +fetch nacl +gclient sync +cd native_client +``` + +~~The first time you build something, you use the --download switch to download +the platform's toolchain.~~ + + ~~./scons --download MODE=opt-linux,nacl~~ + + ~~./scons --download MODE=opt-mac,nacl~~ + + ~~.\\scons --download MODE=opt-win,nacl~~ + +~~Subsequent builds can omit the --download option. You should use --download +anytime you want to update your toolchain.~~ + +The default value for MODE is dbg-*<your-system-os>* so these two commands +are identical + +* ./scons MODE=dbg-*<your-system-os>* +* ./scons + +## How do I run the unittests after the build completes? + +To run all unittests: + + ./scons MODE=opt-*<your-system-os>*,nacl run_all_tests + +To run specific sets of tests: + + ./scons MODE=opt-*<your-system-os>*,nacl small_tests + + ./scons MODE=opt-*<your-system-os>*,nacl medium_tests + + ./scons MODE=opt-*<your-system-os>*,nacl large_tests + + ./scons MODE=opt-*<your-system-os>*,nacl browser_tests + +To run a single test: + +* A trusted test + * ./scons MODE=opt-*<your-system-os>* run_format_string_test + * run_format_string_test is defined in + src/trusted/service-runtime/build.scons + * Other trusted unittest targets exist in other build.scons + files + * Note that you do not need to specify nacl as a mode for a + trusted test +* An untrusted test + * ./scons MODE=opt-*<your-system-os>*,nacl run_thread_test + * run_thread_test is defined in tests/threads/nacl.scons + * Other untrusted unittest targets exist in other nacl.scons + files + +## Are there any other cool Scons options? + +There are some other scons options which are useful. Note the confusing syntax +differences for option words (platform=), single minus options (-c), and double +minus options (--clang). Sorry. + +* --clang + * Use the Clang toolchain downloaded by the DEPS hooks instead of + gcc on Linux. Probably should be the default. +* -c + * clean before building +* -jN + * Split the build into N processes. A good choice for N is often + the number of processors on the machine doing the build +* MODE=*<build-mode-list>* (or its equivalent + --mode=*<build-mode-list>*) + * choices are opt-linux, dbg-linux, opt-mac, dbg-mac, opt-win, and + dbg-win (for the type of trusted code to build) and nacl (to + build untrusted code) + * Usually the *<build-mode-list>* will contain one trusted + code choice and the untrusted code name, like: opt-linux,nacl +* platform=TARGET_ARCH + * Cross-compile for TARGET_ARCH + * platform=x86-64 is required in order to build for 64-bit +* sdl=none + * Do not use SDL + +## What about 64-bit? + +The build defaults to a 32-bit build even if the machine running the build is a +64-bit machine. To build for 64-bit: + +* add: platform=x86-64 + +*Also see the **Special note for Windows users** in the **What kind of +BUILD_PLATFORM/TARGET_PLATFORM configurations are supported?** section above.* + +## Where is the source code? + +The source code is divided into these main areas: + +* src/trusted: Code that runs only as part of the trusted portion of + Native Client +* src/untrusted: Code that runs only as part of a user-created Native + Client program +* src/shared: Code that can be used in both the trusted portion and + the user-created portion of Native Client
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/building-and-testing-gcc-and-gnu-binutils/index.md b/chromium/docs/website/site/nativeclient/how-tos/building-and-testing-gcc-and-gnu-binutils/index.md new file mode 100644 index 00000000000..05924246f18 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/building-and-testing-gcc-and-gnu-binutils/index.md @@ -0,0 +1,155 @@ +--- +breadcrumbs: +- - /nativeclient + - Native Client +- - /nativeclient/how-tos + - '2: How Tos' +page_name: building-and-testing-gcc-and-gnu-binutils +title: Building and Testing GCC and GNU binutils +--- + +[TOC] + +## Introduction + +This page describes the structure of source code of the GCC-based Native Client +toolchain. The sources are based on stable releases of external packages: +[Binutils](http://git.chromium.org/gitweb/?p=nacl-binutils.git;a=summary), +[GCC](http://git.chromium.org/gitweb/?p=nacl-gcc.git;a=summary), +[Newlib](http://git.chromium.org/gitweb/?p=nacl-newlib.git;a=summary), +[GDB](http://git.chromium.org/gitweb/?p=nacl-gdb.git;a=summary), +[GlibC](http://git.chromium.org/gitweb/?p=nacl-glibc.git;a=summary) plus a +subset of [linux kernel +headers](http://git.chromium.org/gitweb/?p=linux-headers-for-nacl.git;a=summary). +The rest of the page addresses the structure of the source repositories, the +ways to synchronize patches across them and the build script. + +## Prerequisites + +We recommend hacking the toolchain on Linux. After each commit the toolchain +tarballs are built on [builders](https://ci.chromium.org/p/nacl/g/main/console). +Using Windows is difficult since Chromium no longer supports Cygwin, and it's +too slow to be practical anyway (mostly due to the poor performance of fork()). + +### Installing packages on your system + +* Refer to + [HowToBuildPorts](http://code.google.com/p/nativeclient/wiki/HowToBuildPorts) + for setting up the build environment. +* optional: Git and Subversion (useful for development) + + ```none + sudo apt-get install gitk subversion + ``` + +Native Client Source is also required to build the toolchain (specifically, +libraries). Follow the instructions on the [Native Client +Source](http://code.google.com/p/nativeclient/wiki/Source) page to fetch the +sources. + +### Setting up environment variables for Git + +If you are going to contribute to the toolchain, you will need to use the Git +repository. Add similar lines to your .bashrc or a shell login script: + +```none +export GIT_COMMITTER_NAME="John Doe" +export GIT_COMMITTER_EMAIL="doe@example.com" +export GIT_AUTHOR_NAME="Mary Major" +export GIT_AUTHOR_EMAIL="mary@example.com" +``` + +In the most common case author and committer strings should be equal. + +## Obtaining the toolchain sources + +```none +cd native_client/tools +make sync # For more options about syncing and building read the topmost comment in the Makefile. +``` + +### Building the toolchain + +Option 1: Build a *newlib*-based toolchain + +```none +make clean build-with-newlib -j16 +``` + +Option2:Build a *GlibC*-based toolchain. + +```none +make clean build-with-glibc -j16 +``` + +The toolchain binaries get installed to native_client/tools/out by default, you +bay override it by providing *TOOLCHAINLOC=<path> in make invocation.* + +*note:* Although the build script is written as a Makefile, it does not support +incremental rebuilds (though it supports parallel builds). + +*note*: To build in a 100% clean way, the TOOLCHAINLOC directory must be empty. + +## Structure of the Git repositories + +The Git repositories are hosted at [chromium git +repositories](http://git.chromium.org/). NaCl development happens in branch +master in each repository. + +### Branches + +The branch vendor-src keeps the sources from the original tarball unchanged. +From time to time the master branch should be **rebased** on top of newer +revisions of the vendor-src branch. Once the **master** branch is rebased, the +old branch should be kept from garbage collection so that old commits can be +found by hashes (required to be able to reproduce old builds). + +## Code reviews + +Follow the [Git Cookbook](http://code.google.com/p/chromium/wiki/GitCookbook) +for sending your commit for review. Recommendations: Method #1 is the easiest. +Instead of "git cl" you can use git-cl from **depot_tools**. In the simplest +case you may: + +```none +git checkout -b my_hack origin/master # make your branch +# hack hack hack +git add your/file1 your/file2 +git commit -m "do my hack with GCC" +git-cl upload --send-mail -r reviewer@chromium.org +# fix stuff during review +git commit --amend your/fixed/file1 +git-cl upload +# you've got an LGTM +git-cl push +``` + +## Testing the toolchain (the GCC testsuite) + +#### Currently it is only easy to run the tests in x86-64 mode, x86-32 testing is broken. To run all tests: + +```none +make -j4 check SDKLOC=/path/to/your/location +``` + +To run one of the three testsuites (c++ testsuite in this case): + +```none +make DEJAGNU=/your/native_client/tools/dejagnu/site.exp check-c++ RUNTESTFLAGS="SIM=/your/sel_ldr --target_board=nacl --outdir=your-directory-for-reports" +``` + +To run a subset of a testsuite governed by some '.exp' config file just add the +name of the file (without path to it) as additional parameter to runtest: + +<pre><code> +cd your-native-client/native_client/tools/BUILD/build-gcc-nacl64/gcc +DEJAGNU=your-dejagnu/site.exp <b>runtest</b> --tool gcc --target_board=nacl --outdir=/tmp/your-temp-dir SIM=/your/sel_ldr builtins.exp +</code></pre> + +You may limit running tests to a single file. Again, the file name should omit +the path part: + +<pre><code> +cd your-native-client/native_client/tools/BUILD/build-gcc-nacl64/gcc +DEJAGNU=your-dejagnu/site.exp <b>runtest</b> --tool gcc --target_board=nacl --outdir=/tmp/your-temp-dir SIM=/your/sel_ldr builtins.exp<b>=strncat-chk.c</b> +</code></pre>
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin/debugging-a-trusted-plugin-on-linux/index.md b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin/debugging-a-trusted-plugin-on-linux/index.md new file mode 100644 index 00000000000..8605f2222e7 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin/debugging-a-trusted-plugin-on-linux/index.md @@ -0,0 +1,52 @@ +--- +breadcrumbs: +- - /nativeclient + - Native Client +- - /nativeclient/how-tos + - '2: How Tos' +- - /nativeclient/how-tos/debugging-documentation + - Debugging Documentation +- - /nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin + - Debugging a Trusted Plugin +page_name: debugging-a-trusted-plugin-on-linux +title: Debugging a Trusted Plugin on Linux +--- + +1. Get a Chromium check-out. You can usually use the revision from the + nacl-sdk DEPS file. +2. You don’t need to build all of chromium, just pepper. + 1. Go to the src/ directory in your check-out + 2. type: ‘make ppapi_tests’ to build the pepper tests as well as + any libraries they depend on. You’ll end up with libppapi_cpp.a + and libppapi_cpp_object.a. +3. Build trusted version of the code + 1. For a C plugin you don’t have to link against anything. ppapi C + is all headers. + 2. For C++, you need libppapi_cpp.a and libppapi_cpp_objects.a. + Link against ppapi_cpp_objects and ppapi_cpp from chrome. + 1. link order matters: ppapi_cpp_objects has to come before + ppapi_cpp + 3. Be sure to specify -fno-rtti and -fPIC since chrome does not + build run-time type information by default, and you’ll be + generating a shared library as your plugin. + 4. For the linking step, be sure to specify -shared +4. To load your plugin, your application will need an embed tag. For + trusted plugins this should not have a “nacl” but a regular “type” + attribute, for example: type="application/x-hello-world" +5. Unlike with an untrusted plugin, instead of handling a onload event + in the EMBED tag, you have to call moduleDidLoad() directly after + the EMBED tag. +6. To debug, you have to use Chromium - best is to get a waterfall for + your platform build from + http://build.chromium.org/f/chromium/snapshots/ You can also finish + the chromium build you checked out but be prepared to wait a while. + This style of debugging is not supported with Google Chrome Dev + Channel +7. In a shell, launch chrome with the following arguments: + 1. --user-data-dir=/tmp/nacl_debugging_chrome_profile + 2. --register-pepper-plugins="location/of/your/plugin.so;application/x-hello-world" + 3. --single-process + 4. file://location/of/your/web_page.html +8. In Chrome, create a new tab and visit about:memory, this will list + the pid of the plugin tab. +9. You can now use gdb to attach to the pid and debug your plugin
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin/debugging-trusted-plugin-on-windows/index.md b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin/debugging-trusted-plugin-on-windows/index.md new file mode 100644 index 00000000000..7c6ecdab808 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin/debugging-trusted-plugin-on-windows/index.md @@ -0,0 +1,81 @@ +--- +breadcrumbs: +- - /nativeclient + - Native Client +- - /nativeclient/how-tos + - '2: How Tos' +- - /nativeclient/how-tos/debugging-documentation + - Debugging Documentation +- - /nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin + - Debugging a Trusted Plugin +page_name: debugging-trusted-plugin-on-windows +title: Debugging a Trusted Plugin on Windows +--- + +1. Get VS2008 +2. Set up the project/Solution using the wizard: make a Win32 Console + app, and then click through the wizard to modify the project to be a + Win32 DLL, that exports symbols. Visit here for more info: + <http://msdn.microsoft.com/en-us/library/ms235636(v=vs.80).aspx> +3. In the project properties, turn off precompiled headers. Do this so + you can use the same #include stack in your sources to build both + untrusted and trusted. +4. Note: I ran into problems using the ppapi headers that come with + NaCl: + 1. 1>d:\\native_client_sdk\\toolchain\\win_x86\\nacl64\\include\\machine\\_types.h(19) + : fatal error C1083: Cannot open include file: + 'native_client/src/include/portability.h': No such file or + directory + 2. I tried -D__native_client__, but this produced even more errors. + 3. To resolve this, I copied toolchain/win_x86/nacl64/include/ppapi + to sit at the same level as examples +5. In the project properties, add <native_client_sdk> to the + header search paths. +6. After copying the ppapi headers, the project still won't build + because I need to copy in the ppapi C++ sources and build them too. + I DEPSed in the ppapi sources from nacl/ppapi and added all the + files in ppapi/cpp/\*.cc to the VS project. +7. I had to change some source files. When you build under nacl-gcc, + things like inttypes.h (and stdint.h) are automagically part of the + #include chain. This is not so when building trusted. In this case, + I added #include <ppapi/c/pp_stdtype.h> to the files that + needed it. (Note that on Windows, there does not seem to be a + <stdint.h> or <inttypes.h>). +8. Edit hello_world/hello_world.html so that the embed tag has + type="application/x-hello-world" and no nacl= attribute. +9. Instead of handling a onload event in the EMBED tag, you have to + call moduleDidLoad() directly after the EMBED tag. +10. Run the local HTTP server in examples. +11. Once the DLL is built, run chrome + --register-pepper-plugins="d:\\native_client_sdk\\examples\\NaClExamples\\HelloWorld\\Debug\\HelloWorld.dll;application/x-hello-world" + --user-data-dir=d:\\trusted-debug-profile + --wait-for-debugger-children +12. Visit localhost:5103 and run the hello_world example. +13. To debug the DLL you have to attach to the right process. It isn't + clear how you find this, other than by guessing. I had limited + success in pulling up the Debug -> Attach... panel, then + launching chrome and visiting + localhost:5103/hello_world/hello_world.html, then hitting Refresh on + the Attach panel and attaching the the new "chrome.exe" process. I + have not been able to figure out how to debug startup issues. There + are some extra debugging hints here: + <http://www.chromium.org/developers/how-tos/debugging> + +Implications: + +1. The SDK will have to DEPS in and bundle src/ppapi from the chromium + project. +2. When building a trusted plugin, you have to use the chromium ppapi + headers and build the .cc files, then switch over to different + headers and link with libppapi_cpp.a to build a .nexe. We could + automate some of this by adding a build step in the SDK to build + libppapi_cpp.a and bundling that library. +3. **Potential show-stopper**: on Windows, there is no built-in + pthreads library. This means the pi_generator example will not + build, nor will any other app that uses pthread, unless we can find + a pthreads lib that we can re-distribute. +4. **Potential show-stopper**: None of this work allows for .dso's, + which are ELF. These will not load on Windows. Not sure if it's + possible to make .dso's into DLLs and mimic the dynamic loading + process. dlopen() will not work for the same reason that pthreads + don't work (no Windows support).
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin/index.md b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin/index.md new file mode 100644 index 00000000000..36f6cfd7c34 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin/index.md @@ -0,0 +1,33 @@ +--- +breadcrumbs: +- - /nativeclient + - Native Client +- - /nativeclient/how-tos + - '2: How Tos' +- - /nativeclient/how-tos/debugging-documentation + - Debugging Documentation +page_name: debugging-a-trusted-plugin +title: Debugging a Trusted Plugin +--- + +In some cases it can be useful to develop/port your Native Client module using a +two-step process, first as a non-portable trusted Pepper plugin for Windows, +Mac, or Linux, then porting to Native Client. In particular this approach allows +you to use the standard debuggers and tools from your preferred desktop +operating system during trusted plugin development. + +Developers should be mindful of the following potential issues when planning +this course of development: + +* Some libraries commonly used with Native Client will not build + easily on all operating systems. +* Threading models differ between trusted Pepper and untrusted Pepper + implementations. +* Extra effort may be required to get source to compile with multiple + different compilers, for example GCC vs. MS Visual Studio. +* Certain operations such as platform-specific library calls and + system calls may succeed during trusted development but fail in + Native Client. + +With this in mind, these sub-pages provide some tips on working with trusted +Pepper plugins on Windows, Mac and Linux.
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin/trusted-debugging-on-mac/index.md b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin/trusted-debugging-on-mac/index.md new file mode 100644 index 00000000000..a6508f76533 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin/trusted-debugging-on-mac/index.md @@ -0,0 +1,63 @@ +--- +breadcrumbs: +- - /nativeclient + - Native Client +- - /nativeclient/how-tos + - '2: How Tos' +- - /nativeclient/how-tos/debugging-documentation + - Debugging Documentation +- - /nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin + - Debugging a Trusted Plugin +page_name: trusted-debugging-on-mac +title: Debugging a Trusted Plugin on Mac +--- + +<table> +<tr> + +1. <td>Make an new Xcode project, use the GUI to make a Bundle project + that uses Core Foundation.</td> +2. <td>Add existing NaCl sources</td> +3. <td>DEPS in ppapi from chromium, add the C++ sources - create a + Group and add the ppapi files directly. Adding ppapi as a folder + reference doesn't work.</td> +4. <td>Set "Header search paths" to point to the chromium ppapi headers + (|SDK_root|/third_party), NOT the built-in NaCl headers.</td> +5. <td>Add the SDK root to "Header Search Paths"</td> +6. <td>Build the plugin.</td> +7. <td>Edit hello_world/hello_world.html so that the embed tag has + type="application/x-hello-world" and no nacl= attribute.</td> +8. <td>Instead of handling a onload event in the EMBED tag, you have to + call moduleDidLoad() directly after the EMBED tag.</td> +9. <td>Make sure to uncheck "Load Symbols Lazily" in the Debugging + panel of Xcode preferences.</td> +10. <td>To debug, you have to use Chromium - best is to get a waterfall + build from http://build.chromium.org/f/chromium/snapshots/Mac/. This + style of debugging is not supported with Google Chrome Dev + Channel</td> + 1. <td>In Xcode, ctrl-click on "Executables" and select "Add Custom + Executable…".</td> + 2. <td>Call the new custom exec, say, "Chromium Dev"</td> + 3. <td>Point it at the .app wrapper for Chromium that you got from + the waterfall, e.g. ~/Downloads/chrome-mac/Chromium.app.</td> + 4. <td>Add these arguments in the Arguments tab:</td> + 1. <td>--user-data-dir=/tmp/nacl-debug-profile</td> + 2. <td>--register-pepper-plugins="$HOME/Source/nacl-sdk/src/examples/hello_world/HelloWorld/build/Debug/HelloWorld.bundle;application/x-hello-world"</td> + 3. <td>--single-process</td> + 4. <td>file://$HOME/Source/nacl-sdk/src/examples/hello_world/hello_world.html</td> +11. <td>It is possible to debug a plugin using Chrome Dev channel, but + it's a little more raw:</td> + 1. <td>In a shell, run Chrome like this: Google\\ + Chrome.app/Contents/MacOS/Google\\ Chrome + --user-data-dir=/tmp/nacl-debug-profile + --register-pepper-plugins="$HOME/Source/nacl-sdk/src/examples/hello_world/HelloWorld/build/Debug/HelloWorld.bundle;application/x-hello-world" + file://$HOME/Source/nacl-sdk/src/examples/hello_world/hello_world.html</td> + 2. <td>In Chrome, create a new tab and visit about:memory, this + will list the PID of the plugin tab.</td> + 3. <td>In Xcode, Run -> Attach To Process, then pick the + appropriate PID.</td> + 1. <td>Note: if you get various errors about formatting, just + click "Continue"</td> + +</tr> +</table>
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-chrome-os/index.md b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-chrome-os/index.md new file mode 100644 index 00000000000..8c7afa9da77 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-chrome-os/index.md @@ -0,0 +1,51 @@ +--- +breadcrumbs: +- - /nativeclient + - Native Client +- - /nativeclient/how-tos + - '2: How Tos' +- - /nativeclient/how-tos/debugging-documentation + - Debugging Documentation +- - /nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended + - Debugging with debug stub (recommended) +page_name: debugging-nacl-apps-in-chrome-os +title: Debugging NaCl apps in Chrome OS +--- + +It is not possible to run debugger on Chrome OS without using dev mode. Luckily, +debugger uses network connection to communicate with the NaCl debug stub. This +makes remote debugging possible with debugger running on a remote machine and +NaCl application running on Chrome OS machine. + +## Prepare Chrome OS for NaCl debugging + +On chrome://flags page there are two flags related to NaCl debugging. We need to +enable "Native Client GDB-based debugging" flag and switch "Restrict Native +Client GDB-based debugging by pattern" to "Debug everything except secure shell" +or "Debug only if URL manifest ends with debug.nmf" value. Changes on +chrome://flags page require browser restart to take effect. Log out, close and +open the lid to restart the browser. If they are set properly, secure shell +extension should work, but NaCl application we are trying to debug should hang +waiting for debugger to connect. + +## Tunneling debugger connection + +Once you launch your NaCl application now, the NaCl debug stub opens 4014 port +on Chrome OS machine. This port is not accessible from outside, so we need to +tunnel it through ssh connection to remote machine. There are two ways to do +this. + +The first way is to open new secure shell tab or window and add "-R +port-number:localhost:4014" to "SSH Arguments" field before connecting to remote +computer. Then you can use secure shell to launch NaCl debugger on that machine +where you should use "target remote :port-number" command to connect to debug +stub running on Chrome OS. + +The second way is to use an existing secure shell tab or window. Press enter, ~, +shift+c. This combination opens ssh-prompt where you can enter "-R +port-number:localhost:4014" command. Pressing enter returns control to normal +shell where you can launch NaCl debugger and use "target remote :port-number" +command to connect to debug stub running on Chrome OS. + +In both cases the port number can be any free port number on the remote machine +above 1024 including 4014.
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse add directory path 1.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse add directory path 1.png.sha1 new file mode 100644 index 00000000000..10b369ee135 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse add directory path 1.png.sha1 @@ -0,0 +1 @@ +ca64943da2b5ad39c4b082ce05ef6bc5d50f6ba3
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse add directory path 2.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse add directory path 2.png.sha1 new file mode 100644 index 00000000000..688b4cf55de --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse add directory path 2.png.sha1 @@ -0,0 +1 @@ +b65fdac12539c396a69eb5a8bcac50b08d977508
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse build behaviour tab.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse build behaviour tab.png.sha1 new file mode 100644 index 00000000000..e05359bfe83 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse build behaviour tab.png.sha1 @@ -0,0 +1 @@ +0217e502261b5990339938cf0e151cc6475d041a
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse build variables.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse build variables.png.sha1 new file mode 100644 index 00000000000..5934dc4f52d --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse build variables.png.sha1 @@ -0,0 +1 @@ +7ec46055e3a1f1d8f67e0523e8680d114cb4ca88
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse build.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse build.png.sha1 new file mode 100644 index 00000000000..8b2b25aa248 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse build.png.sha1 @@ -0,0 +1 @@ +7055e7c625e190952b97e8f8af0b40dba722cb16
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse consoles.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse consoles.png.sha1 new file mode 100644 index 00000000000..d107fc5d32e --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse consoles.png.sha1 @@ -0,0 +1 @@ +9066bfef70126de352541877343b8bf0a891143b
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug configuration Debugger Gdbserver Settings.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug configuration Debugger Gdbserver Settings.png.sha1 new file mode 100644 index 00000000000..d931d716598 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug configuration Debugger Gdbserver Settings.png.sha1 @@ -0,0 +1 @@ +bec5808b06a22da25deff8483263b7cec981d28a
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug configuration Debugger Main.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug configuration Debugger Main.png.sha1 new file mode 100644 index 00000000000..cf82235a046 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug configuration Debugger Main.png.sha1 @@ -0,0 +1 @@ +e78f102d96325e58310fac701e30f94c55f44810
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug configuration glibc Debugger Main.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug configuration glibc Debugger Main.png.sha1 new file mode 100644 index 00000000000..17d7d7c0301 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug configuration glibc Debugger Main.png.sha1 @@ -0,0 +1 @@ +0e046c14ee92b0f939ff9b0ea62977dd00e03813
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug configuration glibc main.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug configuration glibc main.png.sha1 new file mode 100644 index 00000000000..e3c1788a897 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug configuration glibc main.png.sha1 @@ -0,0 +1 @@ +f1c519aa044c7c7ae4bdb59031bd51b635fb8d26
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug configuration main.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug configuration main.png.sha1 new file mode 100644 index 00000000000..c92c53401a0 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug configuration main.png.sha1 @@ -0,0 +1 @@ +c120f1938f8513eaa852f63ede2126c777938081
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug icon.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug icon.png.sha1 new file mode 100644 index 00000000000..8584eafa229 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse debug icon.png.sha1 @@ -0,0 +1 @@ +0d9788d92532b0ee7fba7ce0b93f4d0ad6c778cd
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse gdb_init file.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse gdb_init file.png.sha1 new file mode 100644 index 00000000000..3f888727957 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse gdb_init file.png.sha1 @@ -0,0 +1 @@ +79f88416480f41213ce2b4ac87710d2efbd47fff
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse glibc hit breakpoint.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse glibc hit breakpoint.png.sha1 new file mode 100644 index 00000000000..72068aeb700 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse glibc hit breakpoint.png.sha1 @@ -0,0 +1 @@ +0c98492e6c4bed40599fc61dbfe44711eb7b0576
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse hammer icon.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse hammer icon.png.sha1 new file mode 100644 index 00000000000..9c2c4345d88 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse hammer icon.png.sha1 @@ -0,0 +1 @@ +ea173ca1523505dbe55d04b37411809a23766643
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse hit breakpoint.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse hit breakpoint.png.sha1 new file mode 100644 index 00000000000..8d578dd84db --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse hit breakpoint.png.sha1 @@ -0,0 +1 @@ +5ff7261a75a702d6ee9606570c16565c57520b75
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse last debug configurations.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse last debug configurations.png.sha1 new file mode 100644 index 00000000000..49a9695a226 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse last debug configurations.png.sha1 @@ -0,0 +1 @@ +f565b31f9413db44cbba83a9a8685cf05fe56109
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse new build variable.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse new build variable.png.sha1 new file mode 100644 index 00000000000..97a4d9d2353 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse new build variable.png.sha1 @@ -0,0 +1 @@ +9d14e3854ff56820abbdc18f0bd10b880fa6d1a0
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse new debug configuration icon.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse new debug configuration icon.png.sha1 new file mode 100644 index 00000000000..6ca1151e012 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse new debug configuration icon.png.sha1 @@ -0,0 +1 @@ +e186a744d20b1ef135dff670ad94f6870c93aa05
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse new project.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse new project.png.sha1 new file mode 100644 index 00000000000..5f6a8b60c64 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse new project.png.sha1 @@ -0,0 +1 @@ +03a39fa04ee83dcc4d323a70df939a1cdddd9c27
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse output location.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse output location.png.sha1 new file mode 100644 index 00000000000..66ada924981 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse output location.png.sha1 @@ -0,0 +1 @@ +599c895aebaec53f8775d0ba12af5385101b7dea
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse project view.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse project view.png.sha1 new file mode 100644 index 00000000000..50c5c875e6d --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse project view.png.sha1 @@ -0,0 +1 @@ +f288a4e038d156f78555c26ea6703f67b5ff582e
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse select preferred launcher.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse select preferred launcher.png.sha1 new file mode 100644 index 00000000000..77e740b7734 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse select preferred launcher.png.sha1 @@ -0,0 +1 @@ +8c91e6461916b23f0478ecd94f15a6a12d9573f4
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse source location.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse source location.png.sha1 new file mode 100644 index 00000000000..76191ae9887 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse source location.png.sha1 @@ -0,0 +1 @@ +f539c3ce5f461bad6b652e8efd05f18e13ce85e9
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse with indexer enabled.png.sha1 b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse with indexer enabled.png.sha1 new file mode 100644 index 00000000000..ba080511cfc --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse with indexer enabled.png.sha1 @@ -0,0 +1 @@ +1424cd15ac7fdaee490cd965e023001a17a729bb
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/index.md b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/index.md new file mode 100644 index 00000000000..6014b39c661 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/index.md @@ -0,0 +1,222 @@ +--- +breadcrumbs: +- - /nativeclient + - Native Client +- - /nativeclient/how-tos + - '2: How Tos' +- - /nativeclient/how-tos/debugging-documentation + - Debugging Documentation +- - /nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended + - Debugging with debug stub (recommended) +page_name: debugging-nacl-apps-in-eclipse-cdt +title: Debugging NaCl apps in Eclipse CDT +--- + +Eclipse CDT plugin is designed for development with GNU tools. Its flexibility +allows to configure it for developing NaCl applications without using any +additional plugins. The cost of this flexibility is that a lot of advanced +features are not available. The following instructions are written for Windows +but they can be used on any OS if you replace Windows paths to paths on your OS. + +## Creating NaCl project + +Create NaCl Project directory inside Eclipse workspace +(C:\\Users\\username\\workspace by default). Copy all files from +nacl_sdk\\pepper_22\\examples\\hello_world except hello_world.c to this +directory. Create src subdirectory and copy hello_world.c file there. Placing +source files in the src directory makes cleaner project structure. Now go to +File->New->Makefile Project with Existing Code menu in Eclipse. Choose +project name, enter project folder location and select Cross GCC toolchain. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20new%20project.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20new%20project.png) + +Your new project will look like this. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20project%20view.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20project%20view.png) + +## Building NaCl project + +Open Makefile in the editor. Comment out lines +ALL_TARGETS+=win/Debug/hello_world.nmf and +ALL_TARGETS+=win/Release/hello_world.nmf and replace hello_world.c with +src/hello_world.c (Edit->Find/Replace... in the menu or Ctrl+F with default +key bindings). Then right click on the project and choose Preferences in the +popup menu. Go to C/C++ Build->Build Variables page and add NACL_SDK_ROOT +variable. Point the variable to the pepper version you want to build with. If +you downloaded NaCl SDK to c:\\nacl_sdk directory and want to use 22 pepper, set +it to c:\\nacl_sdk\\pepper_22. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20new%20build%20variable.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20new%20build%20variable.png) + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20build%20variables.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20build%20variables.png) + +Now we can use this variable to set build command on C/C++ Build page to +${NACL_SDK_ROOT}/tools/make NACL_SDK_ROOT=${NACL_SDK_ROOT}. On Linux and Mac use +make NACL_SDK_ROOT=${NACL_SDK_ROOT}. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20build.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20build.png) + +Enable parallel build on Behaviour tab. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20build%20behaviour%20tab.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20build%20behaviour%20tab.png) + +Press OK in properties window. You can now build the project by right clicking +on it and selecting Build Project in the popup menu or by pressing hammer icon +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20hammer%20icon.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20hammer%20icon.png) +in the toolbar. Make build log will be shown in console view. + +## Set up eclipse indexer + +Eclipse indexer doesn't use external compiler and so it should be configured +separately. Open project properties and go to C/C++ General->Paths and +Symbols page. Open Source Location tab, add src folder using Add Folder... +button and remove root of the project using Delete button. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20source%20location.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20source%20location.png) + +Then go to Output Location path, add glibc and newlib folders there and remove +root of the project. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20output%20location.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20output%20location.png) + +Now let us setup include paths. Go to Includes tab and press Add... button. +Enter ${NACL_SDK_ROOT}/include in the directory field and select Add to all +configurations and Add to all languages checkboxes. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20add%20directory%20path%201.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20add%20directory%20path%201.png) + +Then press Add... button again and add +${NACL_SDK_ROOT}/toolchain/win_x86_glibc/x86_64-nacl/include directory (replace +win_x86_glibc with linux_x86_glibc or mac_x86_glibc if you use Linux or Mac OS X +accordingly). + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20add%20directory%20path%202.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20add%20directory%20path%202.png) + +Press OK button in properties window and open hello_world.c. There should not be +any compile errors now. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20with%20indexer%20enabled.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20with%20indexer%20enabled.png) + +## Debug NaCl newlib application + +Launching and debugging applications in Eclipse is done via running and +debugging configurations. Usually they are created automatically. Unfortunately, +NaCl debugging is done using remote debugging protocol. Setting up remote +connection requires parameters that can't be determined automatically. So we +have to create debugging configuration by hand. Go to Run->Debug +Configurations... menu or press on debug icon arrow [<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20debug%20icon.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20debug%20icon.png) +in toolbar and choose Debug Configurations... in the popup menu. Select C/C++ +Remote Application in Debug Configurations windows and press new button [<img +alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20new%20debug%20configuration%20icon.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20new%20debug%20configuration%20icon.png) +above filter text field or choose New in the popup menu. + +Change configuration name to NaCl Project newlib and fill C/C++ Application +field with ${workspace_loc}\\NaCl +Project\\newlib\\Debug\\hello_world_x86_64.nexe. We use ${workspace_loc} instead +of ${project_loc} since the later depends on currently selected project. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20debug%20configuration%20main.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20debug%20configuration%20main.png) + +Now press Select other link at the bottom of the window. If you don't see the +link, skip this step. Select Use configuration specific settings checkbox and +choose GDB (DSF) Manual Remote Debugging Launcher in the list. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20select%20preferred%20launcher.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20select%20preferred%20launcher.png) + +Press OK and go to the debugger tab. Change Stop on startup at field to +Instance_DidCreate or deselect the Stop on startup checkbox. On Main tab in +Debugger Options set GDB debugger field to +c:\\nacl_sdk\\pepper_canary\\toolchain\\win_x86_glibc\\bin\\x86_64-nacl-gdb.exe. +Ensure that Non-stop mode checkbox is not selected since nacl-gdb doesn't +support this mode. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20debug%20configuration%20Debugger%20Main.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20debug%20configuration%20Debugger%20Main.png) + +Set port number to 4014 in Gdbserver Settings tab. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20debug%20configuration%20Debugger%20Gdbserver%20Settings.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20debug%20configuration%20Debugger%20Gdbserver%20Settings.png) + +Save debug configuration by clicking Apply button. + +Now you need to launch chrome with --no-sandbox and --enable-nacl-debug flags +and run your NaCl application. NaCl debug stub will stop application at first +instruction. Then you need to open Debug Configuration window, select our debug +configuration and press Debug button. Next time, you can launch it by pressing +debug icon arrow that shows 10 last debug configurations. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20last%20debug%20configurations.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20last%20debug%20configurations.png) + +When program will stop on the start breakpoint or breakpoint you set in project, +Eclipse will switch to debug perspective. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20hit%20breakpoint.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20hit%20breakpoint.png) + +## Debugging NaCl glibc application + +Create gdb_init.txt file and add line nacl-manifest +"c:\\\\Users\\\\username\\\\workspace\\\\NaCl +Project\\\\glibc\\\\Debug\\\\hello_world.nmf". If you use debugger from +pepper_29+, you don't need to double slashes. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20gdb_init%20file.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20gdb_init%20file.png) + +Go to Run->Debug configuration... menu and duplicate newlib debug +configuration using Duplicate item in popup menu. Change new configuration name +to NaCl Project glibc and C/C++ Application field to ${workspace_loc}\\NaCl +Project\\glibc\\Debug\\lib64\\runnable-ld.so. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20debug%20configuration%20glibc%20main.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20debug%20configuration%20glibc%20main.png) + +Then go to Debugger tab and change GDB command file on Main subtab to +c:\\Users\\username\\workspace\\NaCl Project\\gdb_init.txt. Ensure that Non-stop +mode checkbox is not selected. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20debug%20configuration%20glibc%20Debugger%20Main.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20debug%20configuration%20glibc%20Debugger%20Main.png) + +Press Apply button and close the window. Now you need to run your NaCl +application in chrome with --enable-nacl-debug and --no-sandbox flags, select +this debug configuration in Debug Configurations window and press Debug button. +You may see some error messages like + +```none +No source file named hello_world.c. +warning: Could not load shared library symbols for runnable-ld.so. +Do you need "set solib-search-path" or "set sysroot"? +``` + +You should ignore them. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20glibc%20hit%20breakpoint.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20glibc%20hit%20breakpoint.png) + +## Troubleshooting + +If something goes wrong, you can look on gdb input and output. Press on the +arrow of console icon in Console view to show "NaCl Project glibc \[C/C++ Remote +Application\] gdb traces" console. + +[<img alt="image" +src="/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20consoles.png">](/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/debugging-nacl-apps-in-eclipse-cdt/eclipse%20consoles.png)
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/getting-started-with-debug-stub/index.md b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/getting-started-with-debug-stub/index.md new file mode 100644 index 00000000000..5ceee4ee604 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/getting-started-with-debug-stub/index.md @@ -0,0 +1,121 @@ +--- +breadcrumbs: +- - /nativeclient + - Native Client +- - /nativeclient/how-tos + - '2: How Tos' +- - /nativeclient/how-tos/debugging-documentation + - Debugging Documentation +- - /nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended + - Debugging with debug stub (recommended) +page_name: getting-started-with-debug-stub +title: Getting started with debug stub +--- + +### Introduction + +New versions of chrome include NaCl with debug stub support. If +--enable-nacl-debug switch is passed to chrome or -g switch is passed to +sel_ldr, all NaCl applications start with the debug stub enabled. The debug stub +stops untrusted code at the first instruction inside the IRT and listens on a +TCP port of localhost network interface (4014 currently) for incoming connection +from nacl-gdb. When nacl-gdb connects to the debug stub, they talk with each +other using RSP protocol. Since remote debugging does not need to use +OS-specific debugging functions, we need only one version of nacl-gdb for both +32 and 64-bit debugging. Moreover, if one forwards port to a remote machine, it +is possible to use nacl-gdb for one OS to debug NaCl application on a different +OS. All the differences between OSes are abstracted away by debug stub. + +## Get the debugger + +The debugger is included in the latest version of NaCl SDK. It is located in +nacl_sdk/pepper_canary/toolchain/linux_x86_glibc/bin/x86_64-nacl-gdb on Linux, +nacl_sdk/pepper_canary/toolchain/win_x86_glibc/bin/x86_64-nacl-gdb.exe on +Windows, etc. Debuggers in \*_x86_glibc and \*_x86_newlib directories are +exactly the same. You can use either one on them. Moreover, unlike the rest of +SDK, you can copy debugger to a different folder. + +Regarding the pepper and chrome versions, the latest debugger should work with +the previous versions of chrome/sel_ldr but new functionality may be missing. + +## Debugging NaCl applications in Chrome + +NaCl applications can be launched using two ways in Chrome. You can load +unpacked extension on [chrome://chrome/extensions/](javascript:void(0);) page +(switch on developers mode) and open it. Alternative way is to launch a web +server and either launch chrome with --enable-nacl switch or enable NaCl +applications outside of Chrome Web Store or +[chrome://flags/](javascript:void(0);) page (you need to relaunch chrome after +that). In order to switch on debug stub support, you need to pass +--enable-nacl-debug and --no-sandbox switches to chrome. Create a shell script +that launches chrome with these flags. You can also add +--user-data-dir=some-path to use a separate profile. + +### Debugging newlib applications + +In order to debug NaCl application, you need to launch Chrome and open NaCl +application there first. Then run x86_64-nacl-gdb. Enter following commands +there. If you have spaces in paths, use quotes and double all slashes (or use +backslashes). For pepper29+ debugger you should use quotes without doubling +slashes. + +```none +(gdb) file c:\nacl_sdk\pepper_canary\examples\hello_world\newlib\Debug\hello_world_x86_64.nexe +(gdb) target remote :4014 +``` + +Point file command to 64-bit nexe on 64-bit platforms and to 32-bit nexe on +32-bit platforms. Then you can use all normal gdb commands. + +### Debugging glibc applications + +Debugging glibc applications is harder. You need to use following commands. + +```none +(gdb) nacl-manifest c:\nacl_sdk\pepper_canary\examples\hello_world\glibc\Debug\hello_world.nmf +(gdb) target remote :4014 +``` + +If you launched NaCl as unpacked chrome extension or from local http server, you +already have the NaCl manifest file which you should use here. If you launched +NaCl from an external http server, you need to download \*.nmf, \*.nexe and +\*.so files of the NaCl application and place them in the same directory +structure that is used on the server (\*.nmf file uses relative paths to +reference main executable and libraries). Then point nacl-manifest command to +the downloaded \*.nmf file. + +### Debugging with IRT symbols + +You can additionally load IRT symbols. This helps to understand what application +is doing when it is stopped inside NaCl syscall. + +```none +nacl-irt c:\Users\username\AppData\Local\Google\Chrome SxS\Application\23.0.x.x\nacl_irt_x86_64.nexe +``` + +### Automatic debugger launching + +Chrome can be configured to launch debugger automatically. Use additional +command-line option --nacl-gdb="path-to-nacl-gdb" on Windows or +--nacl-gdb="command line to launch nacl-gdb in the new shell" on Linux. You can +use --nacl-gdb-script="path-to-gdb-script" to execute your gdb script at start +up. Chrome will autodetect its IRT location and execute nacl-irt command. +Additionally, if NaCl application is in a chrome extension, nacl-manifest +command is executed automatically. Example chrome command lines are shown below. + +```none +chrome.exe --enable-nacl-debug --no-sandbox "--nacl-gdb=c:\nacl_sdk\pepper_canary\toolchain\win_x86_glibc\bin\x86_64-nacl-gdb" "--nacl-gdb-script=c:\Users\User Name\Documents\script.gdb" +``` + +```none +./chrome --enable-nacl-debug --no-sandbox "--nacl-gdb=xterm /home/user_name/nacl_sdk/pepper_canary/toolchain/linux_x86_glibc/bin/x86_64-nacl-gdb" --nacl-gdb-script=/home/user_name/script.gdb +``` + +## Debugging NaCl applications in sel_ldr + +Debugging command line NaCl applications is enabled by passing -g switch to +sel_ldr. Newlib debugging is the same, glibc debugging requires creating an +artificial manifest. You need to reference runnable-ld.so, main executable and +all \*.so libraries using relative paths from manifest file. If you want to load +IRT symbols, use nacl-irt command with the same IRT that is passed to sel_ldr +using -B switch.
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/index.md b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/index.md new file mode 100644 index 00000000000..9a836944c1a --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/index.md @@ -0,0 +1,19 @@ +--- +breadcrumbs: +- - /nativeclient + - Native Client +- - /nativeclient/how-tos + - '2: How Tos' +- - /nativeclient/how-tos/debugging-documentation + - Debugging Documentation +page_name: debugging-with-debug-stub-recommended +title: Debugging with debug stub (recommended) +--- + +Debug stub is a new way to debug NaCl applications. If --enable-nacl-debug and +--no-sandbox switches are passed to chrome or -g switch is passed to sel_ldr, a +local TCP port is opened that accepts incoming TCP connections from a debugger +via RSP protocol. This port is opened on localhost network interface, so one +need to forward this port to debug NaCl application from remote computer. This +method of debugging is preferred since debug stub inside NaCl process have an +intimate knowledge about NaCl application.
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/index.md b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/index.md new file mode 100644 index 00000000000..041a7914015 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/debugging-documentation/index.md @@ -0,0 +1,72 @@ +--- +breadcrumbs: +- - /nativeclient + - Native Client +- - /nativeclient/how-tos + - '2: How Tos' +page_name: debugging-documentation +title: Debugging Documentation +--- + +**The Basics** + +The NaCl team is hard at work developing an integrated debugging solution(1). +But before this feature is available, developers must resort to alternative +debugging techniques. These techniques are described here (with reservation!) +First, Native Client applications can be debugged the old school way: with +printf() and logging. Second, to a limited degree, Native Client can be debugged +with the host's GDB, but using normal GDB will have problems resolving addresses +-- some manual tweaking needs to be done to map NaCl addresses into the global +address space GDB is using. Third, there are some experimental patches to +customize GDB which enable various degrees of debugging untrusted code. + +First, we recommend debugging as much as possible compiled as a normal trusted +plugin/executable outside of Native Client, which of course will allow full use +of debuggers such as GDB, MSVC, and WinDebug. Native Client most resembles +Linux, so using GCC and POSIX will be the closest match to the NaCl runtime +environment. + +For untrusted Native Client applications, we again recommend debugging on a +Linux based host, and launching a debug build of Chrome from a terminal window. +A Native Client application can use printf() which will output messages to the +terminal window from which Chrome was launched. + +Native Client's Service Runtime can output debug messages to the terminal +window. The level of detail in these logging messages can be controlled via the +environment variable NACLVERBOSITY + +For example: + +developer@host:/home/developer/chrome/src/out/Debug$ export NACLVERBOSITY=3 + +developer@host:/home/developer/chrome/src/out/Debug$ ./chrome –enable-nacl + +Additional messages from the plug-in can be separately enabled via +NACL_SRPC_DEBUG environment variable. + +To capture log output to file “outfile” use: + +developer@host:/home/developer/chrome/src/out/Debug$ ./chrome –enable-nacl +&>outfile + +To get logs in Windows, you must instead run chrome with the environment +variable NACLLOG=<absolute path to log file / path relative to +chrome.exe>. This requires running Chrome with the --no-sandbox flag. + +**Getting the output from the Native Client Program on Windows:** + +On Linux and OSX, the Native Cilent application inherits standard output and +standard error from Chrome, so though cumbersome, printf-style debugging is +feasible. On Windows, like any non-console application, standard output and +standard error outputs are thrown into the bit bucket. To get the Native Client +application's output on Windows, set the NACL_EXE_STDOUT and NACL_EXE_STDERR +environment variables to be the absolute path to files, and then start Chrome +with the --no-sandbox flag. Output written to standard output and standard error +will then be written to the specified files. + +**Getting the Process ID (PID) of the Native Client Program from Chrome:** + +Chrome -> Developer->Task Manager, right-click process table header, +toggle on "Process ID". The PID can be used to attach GDB to running Native +Client processes. Or click on a new tab and type "about:memory" into the URL +address bar.
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/exception-handling-interface/index.md b/chromium/docs/website/site/nativeclient/how-tos/exception-handling-interface/index.md new file mode 100644 index 00000000000..a0d49016546 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/exception-handling-interface/index.md @@ -0,0 +1,93 @@ +--- +breadcrumbs: +- - /nativeclient + - Native Client +- - /nativeclient/how-tos + - '2: How Tos' +page_name: exception-handling-interface +title: Exception Handling Interface +--- + +## Introduction + +Hardware exceptions (invalid memory accesses, division by zero and etc) can not +be caught in the standard C/C++. Different OS provide different mechanisms to +catch hardware exception. POSIX standardizes hardware exception handling via +signals. Native Client doesn't support signals but it provides somewhat similar +interface. The main difference is that Native Client doesn't allow to resume +execution from the failed instruction. Note, that exception handling is disabled +for PNaCl because exception handling interface uses platform-dependent register +context. + +## Retrieving Hardware Exception Handling Interface + +#include <irt.h> + +struct nacl_irt_exception_handling exception_handling_interface; + +size_t interface_size = nacl_interface_query( + +NACL_IRT_EXCEPTION_HANDLING_v0_1, + +&exception_handling_interface, + +sizeof(exception_handling_interface)); + +if (interface_size != sizeof(exception_handling_interface)) { + +/\* error \*/ + +} + +## Using nacl_exception Library + +An alternative way to access hardware exception handling interface is via +nacl_exception library (it is part of libc). Add -lnacl_exception flag and use +functions from `nacl/nacl_exception.h` header. They have the same parameters and +their names are just prefixed with `nacl_exception`. + +## Handling Hardware Exceptions + +Hardware exception handlers are declared as + +`typedef void (*NaClExceptionHandler)(struct NaClExceptionContext *context);` + +in irt.h. They receive platform-dependent hardware exception context which +contains the register state. This function should not return since there is +nowhere to return to. Once exception handler is called, the exception handling +is disabled on this thread. You must call + +`int exception_clear_flag(void);` + +if you need to reenable it (you want to handle hardware exceptions inside +hardware exception handler for example). This function returns 0 on success and +error code on error (exception handling is disabled). If hardware exception +happens on a thread where exception handling is disabled, the whole NaCl process +is terminated. + +The definition of `NaClExceptionContext` can be found in `nacl/nacl_exception.h` +header. + +NaCl supports only one exception handler per process. The exception handler is +set with + +`int exception_handler(NaClExceptionHandler handler,` + +` NaClExceptionHandler *old_handler);` + +This function returns 0 on success, or error code on error (exception handling +is disabled, handler is not aligned to the bundle size or outside of code +region, exception handler thread is failed to start). Old exception handler is +returned via old_handler parameter. In order to disable exception handling, pass +`NULL` exception handler. + +Exception handler is called on current thread stack by default. If you want to +set alternative stack (to handle stack overflows for example) for exception +handler, use + +`int exception_stack(void *stack, size_t size);` + +The alternative stack is set per thread. The function returns 0 on success and +error code on error (stack location is outside of NaCl address space). If you +want to disable alternative stack, call this function with `NULL` stack pointer +and zero size.
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/how-to-use-git-svn-with-native-client/index.md b/chromium/docs/website/site/nativeclient/how-tos/how-to-use-git-svn-with-native-client/index.md new file mode 100644 index 00000000000..071caa29eea --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/how-to-use-git-svn-with-native-client/index.md @@ -0,0 +1,194 @@ +--- +breadcrumbs: +- - /nativeclient + - Native Client +- - /nativeclient/how-tos + - '2: How Tos' +page_name: how-to-use-git-svn-with-native-client +title: Developing Native Client +--- + +**Setup from scratch** + +Native Client code depends on some external code that is not present in its own +repository. These dependencies (aka DEPS) are managed by a tool called gclient +that is part of Chromium's depot_tools package. Get depot_tools +[here](/developers/how-tos/install-depot-tools) and put the directory (we'll +call it $DEPOT_TOOLS) in your PATH. + +Then create a directory to hold Native Client and all its deps (We'll call it +$NACL_DIR) and cd into it. + +```none +cd $NACL_DIR +``` + +Then fetch the source code. + +```none +fetch nacl +``` + +This command sets up a .gclient config file, fetches the Native Client sources +from git, then reads the DEPS file checked into native client's git repository, +and fetches the dependencies from their git repos. +If you will be committing, you will also want to set up 'git cl', the +depot_tools code review and commit tool. + +```none +cd $DEPOT_TOOLS +git cl config # just hit return at all the prompts +``` + +If you want to build 32 bit nacl on a x86_64 system, you also need to: + +```none +cd $NACL_DIR +sudo native_client/tools/linux.x86_64.prep.sh +``` + +Your workflow might be like the following: + +**Update your master branch** + +```none +cd $NACL_DIR +cd native_client +git checkout master +git pull +gclient sync +``` + +The the 'git pull' command updates your origin/master branch to match the server +and merges it into your local checked-out master branch. The 'gclient sync' +command will pull down the dependencies specified in the DEPS file. If you use a +local master branch in this way, you should not make local commits to it, or +'git pull' will complain about non-fast-forward merges. + +**Create a new branch for a new CL** + +```none +git checkout -b my_feature origin/master +``` + +(This is equivalent to git branch my_feature origin/master; git checkout +my_feature) + +**Hack away, committing to git whenever you like** + +```none +emacs $file +git commit -a (roughly equivalent to git add $file; git commit) +emacs $file +git commit -a +./scons $tests +``` + +I like to at least have a commit for every time I run a test (or try job) that +takes sufficiently long that I won't sit and wait for it. That way when I come +back and look at the results, I'm sure to have a snapshot of my code that was +tested, even if I make new edits while the test is running. + +**Send a try job** + +```none +git try +``` + +The 'git try' command will try whatever state you have committed in your local +git repo (it will complain if you have uncommitted changes). + +If you use 'git cl try' it will try whatever patchset you have currently +uploaded to Rietveld (see 'git cl upload' below). + +**Send out for code review** + +```none + git cl upload +``` + +This creates a new CL and associates it with the current branch (all commits on +this branch are now assumed to be part of this CL). It then uploads it to the +code review server. git cl upload also supports the -m option for the patch +message, -r for reviewers, --cc for extra people to CC in the email, and a few +others. If you commit a new change and run 'git cl upload' again, it will upload +a new patchset to the existing CL. + +**Wait for the review to come back.** + +In the meantime, you can switch to another branch and work on something else. + +```none +git fetch origin +git checkout -b my_next_feature origin/master +``` + +The above sequence will base your next CL off of the current master. +Alternatively you can base your new CL on your first one by omitting the last +argument to 'git checkout'. + +**That mean reviewer wanted changes!** + +Edit based on results of review, then re-upload for more review + +```none +git checkout my_feature +emacs $file +git commit -a +git cl upload +``` + +**Got LGTM!** + +We are almost ready to commit to the server. However, while you were waiting, +there were other commits to the master, so we need to rebase my_feature against +the new HEAD and make sure everything still works. First, update the local +master: + +```none +git checkout master +git pull +gclient sync +``` + +Then, rebase your local changes off the new master: + +```none +git checkout my_feature +git rebase origin/master +``` + +Test, try and update as needed: + +```none +./scons <tests> +git try +``` + +Everything works! Commit it: + +```none +git cl land +``` + +'git cl land' squashes all the changes you made on your branch into a single +diff and commits them to the master branch in a single commit. + +Now you can update your local master again (to include the change you just +committed) and start a new branch for your next CL. + +```none +git checkout master +git pull +gclient sync +git checkout -b my_even_newer_feature origin/master +``` + +If you have a CL already in flight (especially one that was branched off of your +previous feature branch rather than master), you will probably want to rebase it +against master now. After you have updated your master branch as above, + +```none +git checkout my_next_feature +git rebase origin/master +```
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/how-to-write-assembler-for-x86-nacl-platform/index.md b/chromium/docs/website/site/nativeclient/how-tos/how-to-write-assembler-for-x86-nacl-platform/index.md new file mode 100644 index 00000000000..b3f35c86131 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/how-to-write-assembler-for-x86-nacl-platform/index.md @@ -0,0 +1,339 @@ +--- +breadcrumbs: +- - /nativeclient + - Native Client +- - /nativeclient/how-tos + - '2: How Tos' +page_name: how-to-write-assembler-for-x86-nacl-platform +title: How to write assembler for x86 NaCl platform. +--- + +Before we'll go any further let me remid you that NaCl is OS-independent but +CPU-dependent technology while pNaCl is both OS-independent and CPU-independent +technology. Assembler is, of course, CPU-dependent and as such is not suitable +for pNaCl. + +Ok. So we are dealing with NaCl and want to write some kind of assembler +program. + +First of all, I don't plan to explain here how to write your program entirley in +assembler languge. + +It's doable, but quite hard and rarely needed. I'll concentrate on a case of +C/C++ program “with some assebler on the side”. + +Ok, so we want to call some assembler instruction not available via intrinsic. +Let's use cpuid for our simple example. + +$ cat cpuid.c + +#include <stdint.h> + +#include <stdio.h> + +int main() { + +volatile uint32_t reg\[4\]; + +__asm__ __volatile__( + +"cpuid" + +: "=a"(reg\[3\]), "=b"(reg\[0\]), "=c"(reg\[2\]), "=d"(reg\[1\]) + +: "a"(0) + +: "cc"); + +printf("%s\\n", (char \*)reg); + +} + +$ pepper_33/toolchain/linux_x86_newlib/bin/i686-nacl-gcc cpuid.c -o +cpuid-32.nexe + +$ pepper_33/toolchain/linux_x86_newlib/bin/x86_64-nacl-gcc cpuid.c -o +cpuid-64.nexe + +$ pepper_33/tools/sel_ldr.py cpuid-32.nexe + +DEBUG MODE ENABLED (bypass acl) + +GenuineIntel + +$ pepper_33/tools/sel_ldr.py cpuid-64.nexe + +DEBUG MODE ENABLED (bypass acl) + +GenuineIntel + +Looks like we can easily call cpuid from our NaCl program. How cool is that? +Well, cool enough to write some simple program. In 32 bit mode. If you are +lucky. In 64 bit mode. If you **very** lucky. + +Why? It's easy: only provably safe code can be executed on NaCl platform. And +sooner or later you'll write code which will be declared UNSAFE by NaCl and +it'll refuse to run it. In particular NaCl does not allow you to use arbitrary +instructions in your code. Only “safe” instructions are allowed. + +Where is the list of safe instructions? [Here it +is.](https://codereview.chromium.org/49183002/patch/2530001/2540004) This file +is created automatically and lists all single instructions allowed in x86 32 bit +NaCl mode. If you use instructions from it - you are golden, if you use +instructions not mentioned there then validator will reject your code. + +There are a lot of instructions in this list and you can do a lot of things +using them, but couple of instructions are suspiciously missing: call and ret. +Well, call is there but only as call %eip (which basically means “call with any +32bit offset” since script used to generate said list always uses offset equal +to zero for the simplification), but ret is not present at all—and this **not** +an error in script! + +Why would you need a call without ret? How could you return from function? And +can you ever call function indirecly? Contemporary technologies use function +pointers (in different forms) quite extensively. The answer to this question +brings us to a *superinstruction* notion. + +In 32 bit case there are exactly two *superinstructions*: naclcall and nacljmp. +They can be used with any 32 bit general purpose register (and only register, +never memory!) to do an indirect jump. And i686-nacl-as also gives you the +naclret macro which simply calls pop %ecx and then nacljmp %ecx (%ecx is picked +because it's neither caller-saved register not callee-saved register in x86 ELF +ABI). + +There are nothing magical in naclret, but naclcall and nacljmp **are** magical. +How come? Let's see: + +$ cat nacljmp.s + +nacljmp %eax + +$ pepper_33/toolchain/linux_x86_newlib/bin/i686-nacl-as nacljmp.s -o nacljmp.o + +$ pepper_33/toolchain/linux_x86_newlib/bin/i686-nacl-objdump -d nacljmp.o + +nacljmp.o: file format elf32-i386-nacl + +Disassembly of section .text: + +00000000 <.text>: + +0: 83 e0 e0 and $0xffffffe0,%eax + +3: ff e0 jmp \*%eax + +As you can see this *superinstruction* actually combines two different +instructions: and and jmp. This combination guarantees that target address for +nacljmp is always aligned: you can not use nacljmp (or naclcall) to jump in the +middle of 32-byte *bundle*. And i686-nacl-as guarantees that instructions in +your code will never straggle boundary of such *bundle*. These two facts +combined mean that code can be **statically** disassebled and verified. Which in +turn means that NaCl validator does not effect performance of your code at all: +it does it's work once, and then your code is executed by CPU directly without +additional overhead (bundles and lack of ret will create some small overhead, of +course, but it's very small). That's really, really cool. There is one tiny +problem though: what happens if address which you are using as a target is not +actually aligned? IOW: how can call work in this scheme. The answer is simple: +call is magical in i686-nacl-as, too (and naclcall is doubly magical): +i686-nacl-as always moves it to the end of bundle which means that address in +stack is properly aligned. + +And now our description of 32 bit nacl assembler is essentially complete. You +have the list of safe instructions, you use naclcall, nacljmp and naclret where +needed and that's it. + +Now we are switching to 64 bit case. Before we'll discuss it we need to think a +bit. All our manipulations work if **all** the code in your process adheres to +the NaCl rules… but not all code in NaCl process image are like that! NaCl +loaders include bunch of code compiled with a normal (non-NaCl) compiler and, +more importantly, it's linked with system libraries which most definitely can +not be recompiled with NaCl compiler (well… under Linux they could, but this +approach will not work with MacOS or Windows). One jump to stray aligned ret—and +the whole system is compromised. How **that** problem is solved? In 32 bit case +the answer is simple: ***segment registers***! *Segment registers* are used to +limit the reach of your code and that means that *untrusted code*, indeed, can +not call *trusted code* (at least directly). There are some tiny pieces of +*trusted code* injected in *untrusted zone* (*trampolines* and *springboards*) +which are used to manage communication between trusted code and untrusted code +but you never deal with these directly. + +But in 64 bit case this plan will not work! There are no segments in 64 bit +mode! + +Right - and this is why 64 bit mode is significantly more involved and +complicated. [Here is the list of safe +instructions](https://codereview.chromium.org/49183002/patch/2530001/2540005). +Let's take a look on a simple mov instruction. In 32 bit mode it was described +as + +Instruction: 89 XX mov \[%eax..%edi\],\[%eax..%edi or memory\] + +Very simple instruction straight from Intel's (or AMD) manual. Any 32 bit +general-purpose register can be moved to general-purpose register or memory. In +64 bit case the same instruction is described quite differently: + +Instruction: \[REX:40..47\]? 89 XX mov \[%eax..%r15d\],\[%eax..%ebx|%esi..%r14d +or memory\] + +That is: any 32 bit register can be moved to any 32bit register… except for +%rbp, %rsp and %r15. Uhm... Why? What makes these registers special? Answer: +they point to the *untrusted zone*. %r15 always points to the beginning of the +untrusted zone (and can not be changed) while %rbp and %rsp can point to +arbitrary point in the *untrusted zone*—but can only be changed by a limited set +of instructions. + +Why do we do that? How can it limit memory accesses and make sure they never +reach out of the *unstrusted zone*? Does at mean that you can only access memory +placed on a fixed distance from %r15, %rbp, or %rsp? It'll be quite inefficient! + +Yes, it'll be inefficiant and that's why we introduce yet another concept: +concept of restricted register. Conceptually restricted register is just a +register which is guaranteed to be in the interval from 0 to 4'294'967'295. But, +again, we don't try to create complex data models at the validation time. +Instead we have a very simple rule: one instruction can produce restricted +register while another one can consume restricted register—and these two +instructions must be *immediately adjacent in the same bundle*. Here we use the +interesting property of x86-64 ISA: any instruction which stores to 32bit +register automatically cleans up top half of the corresponding 64bit register. +That's what notes input_rr=… and output_rr=… mean in the safe list. They show +which instruction produce restricted register and which instructions consume +restricted register. Note that while many instructions can produce %rbp and/or +%rsp as restricted register only few instruction accept %rbp and/or %rsp as +restricted register. Which means that most %rbp and/or %rsp modifications are +done as two-step operation: first you are doing something with %**e**bp or +%**e**sp, then you immediatery add %**r**15 to %**r**bp or %**r**sp using lea or +add. + +This is all well and good, but here we have a complication: validator knows that +such tightly tied instructions must reside in a single bundle, but +x86_64-nacl-as does not know that! It will happily place these two instructions +into a different bundles and then code will be rejected by validator. + +How can we solve that problem? This is done with human's assistance. If you want +to “glue two instruction together” you need to use the following construct: + +.bundle_lock + +lea (%rax,%rbx),%ecx + +mov (%rbp,%rcx),%edx + +mov (%r15,%rdx),%rax + +.bundle_unlock + +There are couple of interesting things to note here: + +* lea with 32 bit address registers is forbidden, use 64 bit version + with 32 bit register as destination—it's shorter and is just as + effective. +* you can chain more than two instructions together—but you can not + reuse restricted register again. This sequence will be rejected: + + .bundle_lock + + lea (%rax,%rbx),%ecx + + mov (%rbp,%rcx),%edx + + mov (%r15,%rcx),%rax + + .bundle_unlock + +This is all well and good but how can you do that in the inline assembler when +you refer the arguments? When you use %0 will give you either 32 bit register or +64 bit register (depending on what size argument was supplied to asm directive) +and here we often need to deal with 32 bit registers and their 64 bit siblings! + +Actually GCC always had the appropriate mechanism, it's not NaCl-specific at +all, it's just such mix of sizes is not common in “normal” programs. Consider: + +$ cat sizes_test.c + +int foo() { + +int i; + +long long ll; + +asm("mov %q0,%0"::"r"(i)); + +asm("mov %q0,%0"::"r"(ll)); + +asm("mov %k0,%0"::"r"(i)); + +asm("mov %k0,%0"::"r"(ll)); + +} + +$ gcc -S -O2 sizes_test.c -o- + +… + +foo: + +.LFB0: + +.cfi_startproc + +movl $1, %eax + +#APP + +# 4 "sizes_test.c" 1 + +mov %rax,%eax + +# 0 "" 2 + +#NO_APP + +movl $1, %eax + +#APP + +# 5 "sizes_test.c" 1 + +mov %rax,%rax + +# 0 "" 2 + +# 6 "sizes_test.c" 1 + +mov %eax,%eax + +# 0 "" 2 + +#NO_APP + +movl $1, %eax + +#APP + +# 7 "sizes_test.c" 1 + +mov %eax,%rax + +# 0 "" 2 + +#NO_APP + +ret + +.cfi_endproc + +… + +As you can see it's not hard to ask assembler to produce 32 bit or 64 bit +registers on demand. Just keep in mind that NaCl used ILP32 model which means +that by default it'll produce 32 bit registers there! Which probably means that +you'll use q modifier significanly more often then k modifier. + +Note that .bundle_lock/.bundle_unlock machinery is only available in NaCl SDK +starting from PPAPI 33. Before that you were forced to use %nacl pseudo-prefix +and and bunch of special instructions to produce validateable code [as explaines +in the SFI +document](http://www.chromium.org/nativeclient/design-documents/nacl-sfi-model-on-x86-64-systems). +This approach was slower (because it was impossible to combine address +calculation with register restriction) and more cryptic, but if you need to deal +with PPAPI 32 or below then it's your only choice.
\ No newline at end of file diff --git a/chromium/docs/website/site/nativeclient/how-tos/index.md b/chromium/docs/website/site/nativeclient/how-tos/index.md new file mode 100644 index 00000000000..68fe1e61c73 --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/index.md @@ -0,0 +1,9 @@ +--- +breadcrumbs: +- - /nativeclient + - Native Client +page_name: how-tos +title: '2: How Tos' +--- + +{% subpages collections.all %} diff --git a/chromium/docs/website/site/nativeclient/how-tos/working-on-the-git-toolchain-repos/index.md b/chromium/docs/website/site/nativeclient/how-tos/working-on-the-git-toolchain-repos/index.md new file mode 100644 index 00000000000..5b381209dde --- /dev/null +++ b/chromium/docs/website/site/nativeclient/how-tos/working-on-the-git-toolchain-repos/index.md @@ -0,0 +1,105 @@ +--- +breadcrumbs: +- - /nativeclient + - Native Client +- - /nativeclient/how-tos + - '2: How Tos' +page_name: working-on-the-git-toolchain-repos +title: Working on the git toolchain repos +--- + +Everybody who might ever need to touch the repositories that were formerly + +at git.chromium.org should start by doing the account setup that Anush + +posted about: http://www.chromium.org/chromium-os/developer-guide/gerrit-guide + +You can use your existing SSH key you were using with git.chromium.org + +(that's what I did) or generate a fresh one if you prefer. Then you + +should put this bit into your ~/.ssh/config: + +Host gerrit.chromium.org + +Port 29418 + +User <your-gerrit-username> + +IdentityFile %d/.ssh/chromium + +For sanity's sake, your gerrit username will be the same as your + +chromium.org username which will be the same as your google.com username. + +I did it that way even though I don't like my google.com username much + +(and even though I am insane). + +This config assumes that you are using your SSH key from before and/or that + +you generated it with "ssh-keygen -f ~/.ssh/chromium". Adjust file names + +to taste if you are nonconformist. Make sure that the bit you paste into + +the account setup web form for your SSH key is instead the contents of + +~/.ssh/chromium.pub (your public key, not your private key). + +Once you have done the account setup, then you can ask someone to add you + +to the nacl-toolchain-committers group. For the moment, you can ask me. + +When other more adminy people get their gerrit accounts set up so I can + +add them to the nacl-admin group, you should ask them instead of me. + +The content for our repos has been migrated over from the + +gitrw.chromium.org server, and nobody can push there anymore. Note that + +the read-only http://git.chromium.org mirrors are still stale (lacking + +two commits I pushed yesterday), and will probably never be updated again. + +But that's OK! + +The new repos are live. The read-only URLs are: + +http://gerrit.chromium.org/gerrit/p/native_client/nacl-glibc.git + +http://gerrit.chromium.org/gerrit/p/native_client/nacl-binutils.git + +http://gerrit.chromium.org/gerrit/p/native_client/nacl-gcc.git + +http://gerrit.chromium.org/gerrit/p/native_client/nacl-newlib.git + +I will look into changing the toolchain builder crapola to pull from those. + +The URLs for writing are: + +ssh://gerrit.chromium.org/native_client/nacl-glibc.git + +ssh://gerrit.chromium.org/native_client/nacl-binutils.git + +ssh://gerrit.chromium.org/native_client/nacl-gcc.git + +ssh://gerrit.chromium.org/native_client/nacl-newlib.git + +To keep life simple, you can just do a fresh 'git clone' from one of the + +ssh URLs. (You only need a gerrit account and not committer privs to be + +able to clone that way.) It's also possible to set things up to pull from + +http:// urls but push to ssh:// urls, but that is stranger and I don't + +really know why you'd bother with it. + +If you have an existing git checkout, you can fix the URLs just by changing + +them in the .git/config file in each checkout. There is a way to do this + +with the 'git config' command, but really I'd just edit the file. It ain't + +rocket science.
\ No newline at end of file |
