Created PNaCl translation documenation and updated old NaCl documents. BUG=#396 R=phosek@chromium.org Review URL: https://codereview.chromium.org/1402363014 .
diff --git a/mojo/nacl/nonsfi/README.md b/mojo/nacl/nonsfi/README.md index 3ecae5a..3fcd413 100644 --- a/mojo/nacl/nonsfi/README.md +++ b/mojo/nacl/nonsfi/README.md
@@ -11,6 +11,9 @@ The boolean indicating if they are built is "mojo_use_nacl_nonsfi", defined inside the BUILD files. +Building Non-SFI NaCl +--------------------- + Build Mojo (all following commands assume you are in the root of the mojo repository): @@ -19,9 +22,44 @@ $ ./mojo/tools/mojob.py build ``` -Doing this build step will automatically create a pexe of unit tests, at -`./out/Debug/newlib_pnacl/monacl_test.pexe`. To translate a pexe into a -non-SFI nexe: +Doing this build step will automatically create the necessary content handlers +and pexes. + +Translating and Running Pexes +----------------------------- + +When portable executable files (pexes) are generated by mojo, they are created +as `.pexe.mojo` files. These pexes are generated by building a gn target with +the `mojo_native_application` template with a PNaCl toolchain. + +The "pexe" part of the name comes from the fact that they are portable, and the +"mojo" part of the name comes from the fact that they have the line `#!mojo +mojo:content_handler_nonsfi_pexe` prepended to them, so the appropriate pexe +content handler can be found by the Mojo Shell. + +To run the `FOOBAR.pexe.mojo` pexe (aka, to translate and execute it), run the +following: + +``` +$ ./out/Debug/mojo_shell --enable-multiprocess ./out/Debug/FOOBAR.pexe.mojo +``` + +or, alternatively, for a version compatible with Android: + +``` +$ ./mojo/devtools/common/mojo_run --enable-multiprocess mojo:FOOBAR.pexe +[--android] +``` + +For more information on the process of translating and handling nexes and pexes, +refer to the `services/nacl` directory. + +Manually Translating Pexes and Running Nexes +-------------------------------------------- + +A raw pexe of unit tests will be built, at +`./out/Debug/newlib_pnacl/monacl_test.pexe`. To manually translate this pexe +into a non-SFI nexe: ``` $ ./native_client/toolchain/linux_x86/pnacl_newlib/bin/pnacl-translate \ @@ -29,9 +67,9 @@ ``` Now, you should have the fully translated nexe (called -"FOOBAR.nexe"). You can run the nexe through the monacl shell +`FOOBAR.nexe`). You can run the nexe through the monacl shell (a minimal, "nexe-only" shell, which loads the nexe ELF file -- see - monacl_shell_nonsfi.cc): + `monacl_shell_nonsfi.cc`): ``` $ ./out/Debug/clang_x86/monacl_shell_nonsfi FOOBAR.nexe @@ -43,19 +81,13 @@ this content (i.e., how does the mojo_shell know it is dealing with a nonsfi nexe?). -The BUILD.gn files in Mojo automatically make this pexe, translate it to a -nexe, and prepend a line ("#!mojo mojo:content_handler_nonsfi_nexe") to the -front of the file, at which point it is also runnable through the mojo_shell. +The BUILD.gn files in Mojo automatically make the "monacl_test" pexe, translate +it to a nexe, and prepend a line (`#!mojo mojo:content_handler_nonsfi_nexe`) to +the front of the file, at which point it is also runnable through the +mojo_shell. These files, which start with this "#!" line, are ".mojo" files. The nexes can be run like this: ``` $ ./out/Debug/mojo_shell --enable-multiprocess out/Debug/FOOBAR.mojo ``` - -TODO -==== - -* Use subzero (a NaCl project to improve translation speed) for pexe -translation. -* Enable caching of translated pexes.
diff --git a/services/nacl/README.md b/services/nacl/README.md new file mode 100644 index 0000000..d2a1e2c --- /dev/null +++ b/services/nacl/README.md
@@ -0,0 +1,73 @@ +About +===== + +This directory contains the services required to execute both nexes and pexes. + +Using +===== + +For information about how to build and use nexes and pexes from within Mojo, +refer to the `mojo/nacl` directory. + +Non-SFI Nexe Content Handler +---------------------------- + +The nexe content handler is simple. It: + +1. Acquires the desired nexe and dumps it into a temporary file, +2. Accesses the MojoHandle connecting the content handler to the shell, and +3. Launches the Non-SFI nexe. + +Non-SFI Pexe Content Handler +---------------------------- + +The pexe content handler is slightly more complex. Although it is similar +in structure to the Non-SFI nexe content handler, it has an additional step +between item 1 and 2: convert the incoming pexe into a nexe. + +This pexe to nexe translation requires two steps: compilation and linking. +For each of these steps, a helper service is launched. These helper services +are actually executed as nexes -- `pnacl_llc.nexe` and `ld.nexe`. The +translation done by these nexes is executed as part of a callback to IRT +functions, `nacl_irt_private_pnacl_translator_compile`, and +`nacl_irt_private_pnacl_translator_link`. This makes communication between +the content handler and these helper nexes more complicated. + +For the full picture of the compilation process: + +* PexeContentHandler + * Create a message pipe, which has a parent and child handle + * Call `PexeCompilerStart`, passing in the child end of the message pipe. This + contacts a new service which is responsible for launching `pnacl_llc.nexe`. +* PexeCompiler (new process) + * Launch the pnacl_llc nexe using the child end of the pipe received from the + PexeContentHandler + * The pnacl_llc nexe uses the IRT to make a call to ServeTranslateRequest + (defined in `mojo/nacl/nonsfi/irt_pnacl_translator_compile.cc`). This creates + the `PexeCompiler` service, which is ready to handle a single request. It is + bound to the child end of the pipe. +* Meanwhile, back in the PexeContentHandler: + * Bind the parent end of the pipe to a `PexeCompiler` service. Now, + `PexeCompile` can be called with inputs defined by a mojom interface, and + outputs can be received via callback + * Call `PexeCompile`, passing in the name of the pexe, and receiving the + object files created by compilation +* Meanwhile, back in the pnacl_llc nexe: + * Actually do the requested compilation, and pass back the newly created + object files + +The linking process works similarly, but utilizes a different interface which +lets it receive object files and return a linked nexe. + +Once both the compilation and linking steps have been completed, the +PexeContentHandler is able to launch the requested nexe. + +TODO +==== + +* Turn the NexeContentHandler, PexeContentHandler, PexeCompiler, and +PexeLinker services into "anti-singletons". When each service is requested, a +unique process must be created. +* Use subzero (a NaCl project to improve translation speed) for pexe +translation. +* Enable caching of translated pexes.