NaCl documentation: miscellaneous FAQ improvements

native_client_sdk/src/doc/faq.rst

 ##########################
 Frequently Asked Questions
 ##########################
 
 .. contents::
   :local:
   :backlinks: none
   :depth: 2
 
 This document answers some frequently asked questions about Native
@@ skipping 52 matching lines @@
 .. TODO Expand on the PNaCl performance section in another document, and
 .. 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 about the 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?
---------------------------------
+When should I use Portable Native Client instead of Native Cient?

[binji, 2014/07/09 21:54:17]

sp: Client

[JF, 2014/07/09 22:01:38]

Done.

+-----------------------------------------------------------------
+
+See :doc:`NaCl and PNaCl <nacl-and-pnacl>`. In short: PNaCl works on the Open

[binji, 2014/07/09 21:54:17]

I think I prefer "open web" to "Open Web platform". Although I guess there is
http://en.wikipedia.org/wiki/Open_Web_Platform

[JF, 2014/07/09 22:01:38]

The wording is from Erik :)

+Web platform delivered by Chrome whereas NaCl only works on the Chrome Web
+Store.
+
+When should I use Portable Native Client / Native Cient?

[binji, 2014/07/09 21:54:17]

sp: Client

[JF, 2014/07/09 22:01:38]

Done.

+--------------------------------------------------------
 
 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.
+* Porting existing applications or software components, written in C/C++ or
+  virtual machines written in C/C++, for use in a web application.
+* Using compute-intensive applications, including threads and SIMD, such as:
 
-Native Client is a versatile technology; we expect that it will also be
+  * Scientific computing.
+  * Handling multimedia for a web application.
+  * Various aspects of web-based games, including physics engines and AI.
+
+* Running untrusted code on a server or within an application (such as a plugin
+  system for a game).
+
+Portable Native Client and Native Client are versatile technologies which are
 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 Portable Native Client?
 -------------------------------------------------
 
 Fast! The SPEC2k benchmarks (C, C++ and floating-point benchmarks) give
 the following overhead for optimized PNaCl compared to regular optimized
 LLVM:
 
 +--------+-----+
 | x86-32 | 15% |
 +--------+-----+
 | x86-64 | 25% |
 +--------+-----+
 |  ARM   | 10% |
 +--------+-----+
 
 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.
 
 Note that PNaCl supports performance features that are often used in
 native code such as :ref:`threading <language_support_threading>` and
 :ref:`Portable SIMD Vectors <portable_simd_vectors>`.
 
 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
-  <http://research.google.com/pubs/pub34913.html>`_ (PDF).
+* `PNaCl SIMD: Speed on the Web`_.
+* `Adapting Software Fault Isolation to Contemporary CPU Architectures`_ (PDF).
+* `Native Client: A Sandbox for Portable, Untrusted x86 Code`_ (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:
@@ skipping 15 matching lines @@
 or otherwise bypass the JavaScript security model. For more information,
 see later sections of this FAQ.
 
 
 Development Environments and Tools
 ==================================
 
 What development environment and development operating system do you recommend?
 -------------------------------------------------------------------------------
 
-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_, and we're working on
-self-hosting a full development environment on Portable Native Client.
+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_ or our `experimental development environment which runs within NaCl`_,

[binji, 2014/07/09 21:54:17]

seems like a long link, but OK

[JF, 2014/07/09 22:01:38]

Acknowledged.

+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 :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>`_.
+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`_.
 
 
 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 <nacl_project_>`_. Right
@@ skipping 24 matching lines @@
 With Portable Native Client we deliver a system that has comparable
 portability to JavaScript and can adapt to new instruction set
 architectures without requiring recompilation. The web is better when
 it's platform-independent, and we'd like it to stay that way.
 
 .. _other_languages:
 
 Do I have to use C or C++? I'd really like to use another language.
 -------------------------------------------------------------------
 
-Right now only C and C++ are supported directly by the toolchain in the
-SDK. C# and other languages in the .NET family are supported via the
-`Mono port <https://github.com/elijahtaylor/mono>`_ for Native
-Client. Moreover, there are several ongoing projects to support
-additional language runtimes (e.g. `naclports supports Lua, Python and
-Ruby
-<https://code.google.com/p/naclports/source/browse#svn%2Ftrunk%2Fsrc%2Fexamples%2Ftools>`_)
-as well as to compile more languages to LLVM's intermediate
-representation (e.g. support Haskell with `GHC
-<http://www.haskell.org/ghc/docs/latest/html/users_guide/code-generators.html>`_
-or support Fortran with `flang
-<https://flang-gsoc.blogspot.ie/2013/09/end-of-gsoc-report.html>`_), or
+Right now only C and C++ are supported directly by the toolchain in the SDK. C#
+and other languages in the .NET family are supported via the `Mono port`_ for
+Native Client. Moreover, there are several ongoing projects to support
+additional language runtimes (e.g. `naclports supports Lua, Python and Ruby`_)
+as well as to compile more languages to LLVM's intermediate representation
+(e.g. support Halide_, Haskell with GHC_ or support Fortran with flang_), or
 transpile languages to C/C++ (source-to-source compilation).
 
 If you're interested in getting other languages working, please contact the
-Native Client team by way of the `native-client-discuss mailing list
-<https://groups.google.com/group/native-client-discuss>`_.
+Native Client team by way of the native-client-discuss_ mailing list.
 
-Will you only support Chrome? What about other browsers?
---------------------------------------------------------
+Do you only support Chrome? What about other browsers?
+------------------------------------------------------
 
 We aim to support multiple browsers. However, a number of features that
 we consider requirements for a production-quality system that keeps the
 user safe are difficult to implement without help from the
 browser. Specific examples are an out-of-process plugin architecture and
 appropriate interfaces for integrated 3D graphics. We have worked
 closely with Chromium developers to deliver these features and we are
 eager to collaborate with developers from other browsers.
 
 What's the difference between NPAPI and Pepper?
 -----------------------------------------------
 
 :doc:`Pepper <pepper_stable/index>` (also known as PPAPI) is a new API that
 lets Native Client modules communicate with the browser. Pepper supports
 various features that don't have robust support in NPAPI, such as event
 handling, out-of-process plugins, and asynchronous interfaces. Native
 Client has transitioned from using NPAPI to using Pepper.
 
 Is NPAPI part of the Native Client SDK?
 ---------------------------------------
 
-NPAPI is not supported by the Native Client SDK, and is `deprecated in
-Chrome
-<http://blog.chromium.org/2013/09/saying-goodbye-to-our-old-friend-npapi.html>`_.
+NPAPI is not supported by the Native Client SDK, and is `deprecated in Chrome`_.
 
 Does Native Client support SIMD vector instructions?
 ----------------------------------------------------
 
 Native Client currently supports SSE on x86 and NEON on ARM. Support for
 AVX on x86 is under way.
 
 Portable Native Client supports portable SIMD vectors, as detailed in
 :ref:`Portable SIMD Vectors <portable_simd_vectors>`.
 
 Can I use Native Client for 3D graphics?
 ----------------------------------------
 
-Yes. Native Client supports `OpenGL ES 2.0
-<https://www.khronos.org/opengles/>`_.
+Yes. Native Client supports `OpenGL ES 2.0`_.
 
 To alert the user regarding their hardware platform's 3D feature set
 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
-`GLES2 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).
+Some GL extensions are exposed to Native Client applications, see the `GLES2
+file`_.  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).
 
 .. TODO Improve documentation for GL extensions.
 
 Does Native Client support concurrency/parallelism?
 ---------------------------------------------------
 
 Native Client and Portable Native Client both support pthreads,
 C11/C++11 threads, and low-level synchronization primitives (mutex,
 barriers, atomic read/modify/write, compare-and-exchange, etc...), thus
 allowing your Native Client application to utilize several CPU cores.
@@ skipping 31 matching lines @@
 What happens to my data when I use Native Client?
 -------------------------------------------------
 
 Users can opt-in to sending usage statistics and crash information in
 Chrome, which includes usage statistics and crash information about
 Native Client. Crashes in your code won't otherwise send your
 information to Google: Google counts the number of such crashes, but
 does so anonymously without sending your application's data or its debug
 information.
 
-For additional information about privacy and Chrome, see the `Google
-Chrome privacy policy
-<https://www.google.com/chrome/intl/en/privacy.html>`_ and the `Google
-Chrome Terms of Service
-<https://www.google.com/chrome/intl/en/eula_text.html>`_.
+For additional information about privacy and Chrome, see the `Google Chrome
+privacy policy`_ and the `Google Chrome Terms of Service`_.
 
 How does Native Client prevent sandboxed code from doing Bad Things?
 --------------------------------------------------------------------
 
 Native Client's sandbox works by validating the untrusted code (the
 compiled Native Client module) before running it. The validator checks
 the following:
 
 * **Data integrity:** No loads or stores are permitted outside of the
   data sandbox. In particular this means that once loaded into memory,
   the binary is not writable. This is enforced by operating system
   protection mechanisms. While new instructions can be inserted at
   runtime to support things like JIT compilers, such instructions will
   be subject to runtime verification according to the following
   constraints before they are executed.
 * **No unsafe instructions:** The validator ensures that the Native
   Client application does not contain any unsafe instructions. Examples
   of unsafe instructions are ``syscall``, ``int``, and ``lds``.
 * **Control flow integrity:** The validator ensures that all direct and
   indirect branches target a safe instruction.
 
 The beauty of the Native Client sandbox is in reducing "safe" code to a
 few simple rules that can be verified by a small trusted validator: the
 compiler isn't trusted. The same applies to Portable Native Client where
 even the ``.pexe`` to ``.nexe`` translator, a simplified compiler
 backend, isn't trusted: it is validated before executing, and so is its
 output.
 
-In addition to static analysis of untrusted code, the Native Client
-runtime also includes an outer sandbox that mediates system calls. For
-more details about both sandboxes, see `Native Client: A Sandbox for
-Portable, Untrusted x86 Code <http://research.google.com/pubs/pub34913.html>`_
+In addition to static analysis of untrusted code, the Native Client runtime also
+includes an outer sandbox that mediates system calls. For more details about
+both sandboxes, see `Native Client: A Sandbox for Portable, Untrusted x86 Code`_
 (PDF).
 
 How does Google know that the safety measures in Native Client are sufficient?
 ------------------------------------------------------------------------------
 
-Google has taken several steps to ensure that Native Client's security
-works, including:
+Google has taken several steps to ensure that Native Client's security works,
+including:
 
 * Open source, peer-reviewed papers describing the design.
 * A :doc:`security contest <community/security-contest/index>`.
 * Multiple internal and external security reviews.
 * The ongoing vigilance of our engineering and developer community.
 
-Google is committed to making Native Client safer than JavaScript and
-other popular browser technologies. If you have suggestions for security
-improvements, let the team know, by way of the `native-client-discuss
-mailing list <https://groups.google.com/group/native-client-discuss>`_.
+Google is committed to making Native Client safer than JavaScript and other
+popular browser technologies. If you have suggestions for security improvements,
+let the team know, by way of the native-client-discuss_.

[binji, 2014/07/09 21:54:17]

this reads weird.

should be: "by way of the native-client-discuss mailing list"?

[JF, 2014/07/09 22:01:38]

Done.

 
 Development
 ===========
 
 How do I debug?
 ---------------
 
 Instructions on :ref:`debugging the SDK examples
 <debugging_the_sdk_examples>` using GDB are available. You can also
 debug Native Client modules with some :doc:`alternative approaches
@@ skipping 35 matching lines @@
 because of the inherent security risks and because the resulting
 application would not be portable across operating systems. Instead,
 Native Client provides portable cross-OS abstractions wrapping or
 proxying OS functionality or emulating UNIX system calls. For example,
 Native Client provides an ``mmap()`` system call that behaves much like
 the standard UNIX ``mmap()`` system call.
 
 Is my favorite third-party library available for Native Client?
 ---------------------------------------------------------------
 
-Google has ported several third-party libraries to Native Client; such
-libraries are available in the naclports_ project. We encourage you to
-contribute libraries to naclports, and/or to host your own ported
-libraries, and to `let the team know about it
-<https://groups.google.com/group/native-client-discuss>`_ when you do.
+Google has ported several third-party libraries to Native Client; such libraries
+are available in the naclports_ project. We encourage you to contribute
+libraries to naclports, and/or to host your own ported libraries, and to let the
+team know about it on native-client-discuss_ when you do.
 
 Do all the files in an application need to be served from the same domain?
 --------------------------------------------------------------------------
 
 The ``.nmf``, and ``.nexe`` or ``.pexe`` files must either be served from the
 same origin as the embedding page or an origin that has been configured
 correctly using CORS_.
 
 For applications installed from the Chrome Web Store the Web Store manifest
 must include the correct, verified domain of the embedding page.
@@ skipping 90 matching lines @@
   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>`!
 
+
+.. _`PNaCl SIMD: Speed on the Web`: https://www.youtube.com/watch?v=675znN6tntw&list=PLOU2XLYxmsIIwGK7v7jg3gQvIAWJzdat_
+.. _Adapting Software Fault Isolation to Contemporary CPU Architectures: https://nativeclient.googlecode.com/svn/data/site/NaCl_SFI.pdf
+.. _`Native Client: A Sandbox for Portable, Untrusted x86 Code`: http://research.google.com/pubs/pub34913.html
+.. _Crouton: https://github.com/dnschneid/crouton
+.. _experimental development environment which runs within NaCl: https://www.youtube.com/watch?v=OzNuzBDEWzk&list=PLOU2XLYxmsIIwGK7v7jg3gQvIAWJzdat_
+.. _introduction to GCC: https://www.google.com/search?q=gcc+introduction
+.. _Mono port: https://github.com/elijahtaylor/mono
+.. _naclports supports Lua, Python and Ruby: https://code.google.com/p/naclports/source/browse#svn%2Ftrunk%2Fsrc%2Fexamples%2Ftools
+.. _Halide: http://halide-lang.org/
+.. _GHC: http://www.haskell.org/ghc/docs/latest/html/users_guide/code-generators.html
+.. _flang: https://flang-gsoc.blogspot.ie/2013/09/end-of-gsoc-report.html
+.. _native-client-discuss: https://groups.google.com/group/native-client-discuss
+.. _deprecated in Chrome: http://blog.chromium.org/2013/09/saying-goodbye-to-our-old-friend-npapi.html
+.. _OpenGL ES 2.0: https://www.khronos.org/opengles/
+.. _GLES2 file: https://src.chromium.org/viewvc/chrome/trunk/src/ppapi/lib/gl/gles2/gles2.c

[binji, 2014/07/09 21:54:17]

I wonder if it would be better to point to cs.chromium.org?

[JF, 2014/07/09 22:01:38]

Done.

+.. _Google Chrome privacy policy: https://www.google.com/chrome/intl/en/privacy.html
+.. _Google Chrome Terms of Service: https://www.google.com/chrome/intl/en/eula_text.html
+.. _naclports: https://code.google.com/p/naclports
 .. _CORS: http://en.wikipedia.org/wiki/Cross-origin_resource_sharing
-.. _naclports: https://code.google.com/p/naclports
-.. _Crouton: https://github.com/dnschneid/crouton