services/nacl/README.md

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.