PNaCl doc: Remove TODOs from FAQ, update perf numbers

native_client_sdk/src/doc/faq.rst

 .. _faq:
 
 ##########################
 Frequently Asked Questions
 ##########################
 
 .. contents::
   :local:
   :backlinks: none
   :depth: 2
@@ skipping 45 matching lines @@
   model which adapts to novel attacks, without affecting
   already-released applications.
 * **Convenience:** Developers only need to ship a single ``.pexe`` file,
   not one ``.nexe`` file per supported architecture.
 * **Portability:** Developers and users don't need to worry about
   already-released applications not working on new hardware: PNaCl
   already supports all architectures NaCl does, and as PNaCl evolves it
   gains support for new processors and fully uses their capabilities.
 
 .. TODO Expand on the PNaCl performance section in another document, and
-.. link to it here.
+.. link to it here. How does one profile PNaCl code? What are common
+.. causes of slowness? How can code be made faster? What's the best way
+.. to use Pepper's asynchronous APIs? What do I need to know about
+.. threads and inter-thread communications? Can I use SIMD or other
+.. processor-specific instructions? What aboutt he GPU?
 
 For more details, refer to the :doc:`history behind and comparison of
 NaCl and PNaCl <nacl-and-pnacl>`.
 
 When should I use Native Client?
 --------------------------------
 
 The following are some typical use cases. For details, see the
 :doc:`Technical Overview <overview>`.
 
 * Porting existing software components for use in a web application.
 * Porting legacy desktop applications.
 * Handling browser-side encryption and decryption for an enterprise
   application.
 * Handling multimedia for a web application.
 * Handling various aspects of web-based games, including physics engines
   and AI.
 
 Native Client is a versatile technology; we expect that it will also be
 used in many other contexts outside of Chrome.
 
 When should I use Portable Native Client?
 -----------------------------------------
 
 See :doc:`NaCl and PNaCl <nacl-and-pnacl>`. In short: PNaCl works on the
 open web whereas NaCl only works on the Chrome Web Store.
 
-How fast does code run in Native Client?
-----------------------------------------
+How fast does code run in Portable Native Client?
+-------------------------------------------------
 
-Fast! Benchmarks on x86-32 measured an average performance overhead of
-less than 5% compared to native C/C++ on applications such as Quake,
-bzip2, and Google Earth. For details of those benchmarks, see `Native
-Client: A Sandbox for Portable, Untrusted x86 Code
-<https://src.chromium.org/viewvc/native_client/data/docs_tarball/nacl/googleclient/native_client/documentation/nacl_paper.pdf>`_
-(PDF).
+Fast! The SPEC2k benchmarks (C, C++ and floating-point benchmarks) give
+the following overhead for optimized PNaCl compared to regular optimized
+LLVM:
 
-Benchmarks on x86-64 and ARM measured an average performance overhead of
-less than 5% on ARM and 7% on x86-64; however, benchmark performance was
-bimodal for x86-64, so different use cases are likely to achieve either
-significantly better or significantly worse performance than that
-average. For details, see `Adapting Software Fault Isolation to
-Contemporary CPU Architectures
-<https://nativeclient.googlecode.com/svn/data/site/NaCl_SFI.pdf>`_ (PDF).
++--------+-----+
+| x86-32 | 15% |
++--------+-----+
+| x86-64 | 20% |
++--------+-----+
+|  ARM   | 10% |
++--------+-----+
 
-.. TODO Update performance numbers.
+Note that benchmark performance is sometimes bimodal, so different use
+cases are likely to achieve better or worse performance than the above
+averages. For example floating-point heavy code usually exhibits much
+lower overheads whereas very branch-heavy code often performs worse.
+
+For details, see:
+
+* `Adapting Software Fault Isolation to Contemporary CPU Architectures
+  <https://nativeclient.googlecode.com/svn/data/site/NaCl_SFI.pdf>`_
+  (PDF).
+* `Native Client: A Sandbox for Portable, Untrusted x86 Code
+  <https://src.chromium.org/viewvc/native_client/data/docs_tarball/nacl/googleclient/native_client/documentation/nacl_paper.pdf>`_
+  (PDF).
 
 If your code isn't performing as close to native speed as you'd expect,
 :doc:`let us know <help>`!
 
+.. TODO Link to the non-existent performance page! (see above todo).
+
 Why use Portable Native Client instead of *<technology X>*?
 -----------------------------------------------------------
 
 Many other technologies can be compared to Portable Native Client:
 Flash, Java, Silverlight, ActiveX, .NET, asm.js, etc...
 
 Different technologies have different strengths and weaknesses. In
 appropriate contexts, Portable Native Client can be faster, more secure,
 and/or more compatible across operating systems and architectures than
 other technologies.
@@ skipping 17 matching lines @@
 -------------------------------------------------------------------------------
 
 You can develop on Windows, Mac, or Linux, and the resulting Native
 Client or Portable Native Client application will run inside the Google
 Chrome browser on all those platforms as well as ChromeOS. You can also
 develop on ChromeOS with `Crouton
 <https://github.com/dnschneid/crouton>`_, and we're working on
 self-hosting a full development environment on Portable Native Client.
 
 Any editor+shell combination should work as well as IDEs like Eclipse,
-Visual Studio with the `Native Client Add-In
-<https://developers.google.com/native-client/dev/devguide/devcycle/vs-addin>`_
-on Windows, or Xcode on Mac OSX.
-
-.. TODO: update link to Visual Studio when ReST-ified.
+Visual Studio with the :doc:`Native Client Add-In
+<devguide/devcycle/vs-addin>` on Windows, or Xcode on Mac OSX.
 
 I'm not familiar with native development tools, can I still use the Native Client SDK?
 --------------------------------------------------------------------------------------
 
 You may find our :doc:`Tutorial <devguide/tutorial/index>` and :doc:`Building
 instructions <devguide/devcycle/building>` useful, and you can look at
 the code and Makefiles for the SDK examples to understand how the
 examples are built and run.
 
 You'll need to learn how to use some tools (like GCC, LLVM, make,
 Eclipse, Visual Studio, or Xcode) before you can get very far with the
 SDK. Try seaching for an `introduction to GCC
 <https://www.google.com/search?q=gcc+introduction>`_.
 
 
 Openness, and Supported Architectures and Languages
 ===================================================
 
 Is Native Client open? Is it a standard?
 ----------------------------------------
 
 Native Client is completely open: the executable format is open and the
 `source code is open <https://code.google.com/p/nativeclient/>`_. Right
 now the Native Client project is in its early stages, so it's premature
 to consider Native Client for standardization.
 
 We consistenly try to document our design and implementation and hope to
 standardize Portable Native Client when it gains more traction. A good
-example is our `PNaCl bitcode reference manual
-<http://www.chromium.org/nativeclient/pnacl/bitcode-abi>`_.
-
-.. TODO Update the above bitcode-abi link to a :doc: once 3693 is fixed.
+example is our :doc:`PNaCl bitcode reference manual
+<reference/pnacl-bitcode-abi>`.
 
 What are the supported instruction set architectures?
 -----------------------------------------------------
 
 Portable Native Client uses an architecture-independent format (the
 ``.pexe``) which can currently be translated to execute on processors
 with the x86-32, x86-64, and ARM instruction set architectures, as well
 as experimental support for MIPS. As new architectures come along and
 become popular we expect Portable Native Client to support them without
 developers having to recompile their code.
@@ skipping 66 matching lines @@
 Portable Native Client should support SIMD vectors in the near future.
 
 Can I use Native Client for 3D graphics?
 ----------------------------------------
 
 Yes. Native Client supports `OpenGL ES 2.0
 <https://www.khronos.org/opengles/>`_.
 
 
 To alert the user regarding their hardware platform's 3D feature set
-before loading a large NaCl application, see `Vetting the driver in
-Javascript
-<https://developers.google.com/native-client/devguide/coding/3D-graphics>`_.
-
-.. TODO Update link to point to the right place in the document once
-.. it's ReST-ified.
+before loading a large NaCl application, see :doc:`Vetting the driver in
+Javascript <devguide/coding/3D-graphics>`.
 
 Some GL extensions are exposed to Native Client applications, see the
 `GL ES 2 file
 <https://src.chromium.org/viewvc/chrome/trunk/src/ppapi/lib/gl/gles2/gles2.c>`_.
 This file is part of the GL wrapper supplied by the library
 ``ppapi_gles2`` which you'll want to include in your project.  In most
 cases extensions map to extensions available on other platforms, or
 differ very slightly (if they differ, the extension is usually CHROMIUM
 or ANGLE instead of EXT).
 
@@ skipping 268 matching lines @@
 * The ``.nexe`` files must have been compiled using SDK version 0.5 or
   greater.
 * You must load the correct ``.nexe`` file for your machine's specific
   instruction set architecture (x86-32, x86-64 or ARM). You can ensure
   you're loading the correct ``.nexe`` file by building a separate
   ``.nexe`` for each architecture, and using a ``.nmf`` manifest file to
   let the browser select the correct ``.nexe`` file. Note: the need to
   select a processor-specific ``.nexe`` goes away with Portable Native
   Client.
 * If things still aren't working, :doc:`ask for help <help>`!