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.
