summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorjfb@chromium.org <jfb@chromium.org@0039d316-1c4b-4281-b951-d872f2087c98>2013-10-30 21:16:06 +0000
committerjfb@chromium.org <jfb@chromium.org@0039d316-1c4b-4281-b951-d872f2087c98>2013-10-30 21:16:06 +0000
commitfb49bcc32f14a55270c412272d7bf9626625e1bf (patch)
tree72a2dbe7382961c424d270bc0f7bea6ac2b24d3d
parenta8d66beb6681399041b1c75b271fbac2cb490156 (diff)
downloadchromium_src-fb49bcc32f14a55270c412272d7bf9626625e1bf.zip
chromium_src-fb49bcc32f14a55270c412272d7bf9626625e1bf.tar.gz
chromium_src-fb49bcc32f14a55270c412272d7bf9626625e1bf.tar.bz2
PNaCl docs: miscellaneous updates
- Remove some TODOs. - Add more cross-links. - Remove xaos/mame/sdl port links (won't be done for M31, will document naclports and Christian's work instead). - Document more C/C++ language feature support as well as future directions that were missing. - Format the language support document more consistently. R= eliben@chromium.org, mackinlay@chromium.org BUG= https://code.google.com/p/nativeclient/issues/detail?id=3634 NOTRY=true (documentation change) Review URL: https://codereview.chromium.org/52983002 git-svn-id: svn://svn.chromium.org/chrome/trunk/src@231929 0039d316-1c4b-4281-b951-d872f2087c98
-rw-r--r--native_client_sdk/src/doc/devguide/devcycle/building.rst3
-rw-r--r--native_client_sdk/src/doc/faq.rst8
-rw-r--r--native_client_sdk/src/doc/publications-and-presentations.rst43
-rw-r--r--native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst116
4 files changed, 89 insertions, 81 deletions
diff --git a/native_client_sdk/src/doc/devguide/devcycle/building.rst b/native_client_sdk/src/doc/devguide/devcycle/building.rst
index 5ad73d8..8d5ab3d 100644
--- a/native_client_sdk/src/doc/devguide/devcycle/building.rst
+++ b/native_client_sdk/src/doc/devguide/devcycle/building.rst
@@ -79,7 +79,8 @@ The GCC-based Native Client SDK only has support for
C++11 library support is only complete in libc++ but other non-library
language features should work regardless of which standard library is
used. The ``-std=[c++98|c++11]`` command line argument can be used to
-indicate which C++ language standard to use.
+indicate which C++ language standard to use (or ``-std=gnu++11`` with
+non-standard extensions).
SDK toolchains
--------------
diff --git a/native_client_sdk/src/doc/faq.rst b/native_client_sdk/src/doc/faq.rst
index ee6ee51..6ac764d 100644
--- a/native_client_sdk/src/doc/faq.rst
+++ b/native_client_sdk/src/doc/faq.rst
@@ -220,6 +220,8 @@ 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.
-------------------------------------------------------------------
@@ -307,13 +309,13 @@ barriers, atomic read/modify/write, compare-and-exchange, etc...), thus
allowing your Native Client application to utilize several CPU cores.
Note that this allows you to modify datastructures concurrently without
needing to copy them, which is often a limitation of shared-nothing
-systems.
+systems. For more information see :ref:`memory model and atomics
+<memory_model_and_atomics>` and :ref:`threading
+<language_support_threading>`.
Native Client doesn't support HTML5 Web Workers directly but can
interact with JavaScript code which does.
-.. TODO Add link to relevant documentation, once written.
-
Coming Soon
===========
diff --git a/native_client_sdk/src/doc/publications-and-presentations.rst b/native_client_sdk/src/doc/publications-and-presentations.rst
index 5d27f0c3..ccf5dc7 100644
--- a/native_client_sdk/src/doc/publications-and-presentations.rst
+++ b/native_client_sdk/src/doc/publications-and-presentations.rst
@@ -155,46 +155,3 @@ to Linux and Macintosh in lieu of native ports. They describe the
porting process on their blog.
`Read more <http://carbongames.com/2012/01/Native-Client>`__
-
-Porting XaoS
-^^^^^^^^^^^^
-
-Google engineers ported `XaoS <http://xaos.sourceforge.net/english.php>`_, an
-interactive graphical exploration tool for fractals, to Native Client. Many of
-the porting problems they encountered are quite common, and the techniques
-described here should help with similar porting efforts. Some of the background
-information might also benefit those who are writing new Native Client
-applications.
-
-`Read more
-<https://developers.google.com/native-client/community/porting/xaos>`__
-
-.. TODO Fix link once it is ReST-ified.
-
-Porting MAME
-^^^^^^^^^^^^
-
-Multiple Arcade Machine Emulator (`MAME <http://mamedev.org>`_) is an
-emulator for a large number of classic arcade games. Google engineers
-ported it to Native Client. This article discusses the overall porting
-strategy, dealing with ``newlib`` incompatibilities, and handling
-binaries that are built and run as part of the build process.
-
-`Read more
-<https://developers.google.com/native-client/community/porting/MAME>`__
-
-.. TODO Fix link once it is ReST-ified.
-
-How to Port SDL Games
-^^^^^^^^^^^^^^^^^^^^^
-
-`Simple Directmedia Layer <http://www.libsdl.org>`_ (SDL) is a popular
-library that many games and applications use to access sound and video
-capabilities on end-user machines. Native Client bindings for SDL are
-available on naclports, making it possible to port SDL-based games to
-Native Client. This article by Google engineers describes how to
-complete such a port, focusing on writing the glue code for fusing your
-game with the Pepper APIs.
-
-`Read more
-<https://developers.google.com/native-client/community/porting/SDLgames>`__
diff --git a/native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst b/native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst
index 8e9244b..bcbce53 100644
--- a/native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst
+++ b/native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst
@@ -10,21 +10,28 @@ PNaCl C/C++ Language Support
Source language support
=======================
-The currently supported languages are C and C++. The PNaCl toolchain is based on
-Clang 3.3, which fully supports C++11 and most of C11. A detailed status of the
-language support is available `here <http://clang.llvm.org/cxx_status.html>`_.
+The currently supported languages are C and C++. The PNaCl toolchain is
+based on Clang 3.3, which fully supports C++11 and most of C11. A
+detailed status of the language support is available `here
+<http://clang.llvm.org/cxx_status.html>`_.
+
+For information on using languages other than C/C++, see the :ref:`FAQ
+section on other languages <other_languages>`.
As for the standard libraries, the PNaCl toolchain is currently based on
-``libstdc++`` version 4.6.1, and the ``newlib`` standard C library (version is
-available through the macro ``NEWLIB_VERSION``). Experimental ``libc++`` support
-is also included; see :ref:`building_cpp_libraries` for more details.
+``libstdc++`` version 4.6.1, and the ``newlib`` standard C library
+(version is available through the macro ``NEWLIB_VERSION``).
+Experimental ``libc++`` support is also included; see
+:ref:`building_cpp_libraries` for more details.
Preprocessor definitions
------------------------
-When compiling C/C++ code, the PNaCl toolchain defines the ``__pnacl__`` macro.
-In addition, ``__native_client__`` is defined for compatibility with other NaCl
-toolchains.
+When compiling C/C++ code, the PNaCl toolchain defines the ``__pnacl__``
+macro. In addition, ``__native_client__`` is defined for compatibility
+with other NaCl toolchains.
+
+.. _memory_model_and_atomics:
Memory Model and Atomics
========================
@@ -54,7 +61,7 @@ C++11 header ``<atomic>``.
The PNaCl toolchain supports concurrent memory accesses through legacy
GCC-style ``__sync_*`` builtins, as well as through C11/C++11 atomic
-primitives. ``volatile`` memory accesses can also be used, though these
+primitives. ``volatile`` memory accesses can also be used, though these
are discouraged. See `Volatile Memory Accesses`_.
PNaCl supports concurrency and parallelism with some restrictions:
@@ -88,36 +95,38 @@ can be done through regular C/C++ code.
Atomic Memory Ordering Constraints
----------------------------------
-Atomics follow the same ordering constraints as in regular C11/C++11, but all
-accesses are promoted to sequential consistency (the strongest memory ordering)
-at pexe creation time. We plan to support more of the C11/C++11 memory orderings
-in the future.
+Atomics follow the same ordering constraints as in regular C11/C++11,
+but all accesses are promoted to sequential consistency (the strongest
+memory ordering) at pexe creation time. We plan to support more of the
+C11/C++11 memory orderings in the future.
Some additional restrictions, following the C11/C++11 standards:
- Atomic accesses must at least be naturally aligned.
-- Some accesses may not actually be atomic on certain platforms, requiring an
- implementation that uses global locks.
-- An atomic memory location must always be accessed with atomic primitives, and
- these primitives must always be of the same bit size for that location.
+- Some accesses may not actually be atomic on certain platforms,
+ requiring an implementation that uses global locks.
+- An atomic memory location must always be accessed with atomic
+ primitives, and these primitives must always be of the same bit size
+ for that location.
- Not all memory orderings are valid for all atomic operations.
Volatile Memory Accesses
------------------------
-The C11/C++11 standards mandate that ``volatile`` accesses execute in program
-order (but are not fences, so other memory operations can reorder around them),
-are not necessarily atomic, and can’t be elided. They can be separated into
-smaller width accesses.
-
-Before any optimizations occur, the PNaCl toolchain transforms ``volatile``
-loads and stores into sequentially consistent ``volatile`` atomic loads and
-stores, and applies regular compiler optimizations along the above guidelines.
-This orders ``volatiles`` according to the atomic rules, and means that fences
-(including ``__sync_synchronize``) act in a better-defined manner. Regular
-memory accesses still do not have ordering guarantees with ``volatile`` and
-atomic accesses, though the internal representation of ``__sync_synchronize``
-attempts to prevent reordering of memory accesses to objects which may escape.
+The C11/C++11 standards mandate that ``volatile`` accesses execute in
+program order (but are not fences, so other memory operations can
+reorder around them), are not necessarily atomic, and can’t be
+elided. They can be separated into smaller width accesses.
+
+Before any optimizations occur, the PNaCl toolchain transforms
+``volatile`` loads and stores into sequentially consistent ``volatile``
+atomic loads and stores, and applies regular compiler optimizations
+along the above guidelines. This orders ``volatiles`` according to the
+atomic rules, and means that fences (including ``__sync_synchronize``)
+act in a better-defined manner. Regular memory accesses still do not
+have ordering guarantees with ``volatile`` and atomic accesses, though
+the internal representation of ``__sync_synchronize`` attempts to
+prevent reordering of memory accesses to objects which may escape.
Relaxed ordering could be used instead, but for the first release it is
more conservative to apply sequential consistency. Future releases may
@@ -143,6 +152,12 @@ libraries as well as POSIX threads.
Communication between threads should use atomic primitives as described
in `Memory Model and Atomics`_.
+``setjmp`` and ``longjmp``
+==========================
+
+PNaCl and NaCl support ``setjmp`` and ``longjmp`` without any
+restrictions beyond C's.
+
Inline Assembly
===============
@@ -154,21 +169,54 @@ PNaCl this barrier is only guaranteed to order ``volatile`` and atomic
memory accesses, though in practice the implementation attempts to also
prevent reordering of memory accesses to objects which may escape.
+NaCl supports a fairly wide subset of inline assembly through GCC's
+inline assembly syntax, with the restriction that the sandboxing model
+for the target architecture has to be respected.
+
Future Directions
=================
+SIMD
+----
+
+PNaCl currently doesn't support SIMD. We plan to add SIMD support in the
+very near future.
+
+NaCl supports SIMD.
+
Inter-Process Communication
---------------------------
Inter-process communication through shared memory is currently not
-supported by PNaCl. When implemented, it may be limited to operations
-which are lock-free on the current platform (``is_lock_free``
+supported by PNaCl/NaCl. When implemented, it may be limited to
+operations which are lock-free on the current platform (``is_lock_free``
methods). It will rely on the address-free properly discussed in `Memory
Model for Concurrent Operations`_.
Signal Handling
---------------
-Untrusted signal handling currently isn't supported by PNaCl. When
+Signal handling from user code currently isn't supported by PNaCl. When
supported, the impact of ``volatile`` and atomics for same-thread signal
handling will need to be carefully detailed.
+
+NaCl supports signal handling.
+
+Exception Handling
+------------------
+
+PNaCl currently doesn't support exception handling. It supports the
+usual ``-fno-exceptions`` flag, and by default it transforms all
+``throw`` statements into ``abort``. We plan to add exception-handling
+support in the very near future, and zero-cost exception handling soon
+thereafter.
+
+NaCl supports exception handling.
+
+Computed ``goto``
+-----------------
+
+PNaCl currently doesn't support computed ``goto``, a non-standard
+extension to C used by some interpreters.
+
+NaCl supports computed ``goto``.