Created PNaCl translation documenation and updated old NaCl documents.

services/nacl/README.md

Index: services/nacl/README.md
diff --git a/services/nacl/README.md b/services/nacl/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..f5421ef13771a2f223a97531488d507929ae40bf
--- /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

[Petr Hosek, 2015/11/11 17:26:17]

Nit: nexe

[Sean Klein, 2015/11/11 18:46:23]

Done.

+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_lcc.nexe" and "ld.nexe". The

[Petr Hosek, 2015/11/11 17:26:17]

"pnacl_llc.nexe"

[Sean Klein, 2015/11/11 18:46:23]

Done.

+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:
+
+* Pexe Content Handler

[Petr Hosek, 2015/11/11 17:26:17]

Nit: PexeContentHandler

[Sean Klein, 2015/11/11 18:46:24]

Done.

+  * 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.
+* PNaCl Compile (new process)

[Petr Hosek, 2015/11/11 17:26:17]

Nit: PexeCompiler

[Sean Klein, 2015/11/11 18:46:23]

Done.

+  * Launch the pnacl_llc nexe using the child end of the pipe received from the
+  pexe content handler
+  * 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 Pexe Content Handler:

[Petr Hosek, 2015/11/11 17:26:17]

Nit: PexeContentHandler

[Sean Klein, 2015/11/11 18:46:23]

Done.

+  * 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 pexe
+content handler is able to launch the requested nexe.
+
+TODO
+====
+
+* Turn the nexe content handler, pexe content handler, pnacl compile, and
+pnacl link 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.