Updated documentation to point to the released spec.

README.md

@@ -1,17 +1,24 @@
 This folder contains the C++ source code for the P4-16 compiler.  This
-is a reference implementation of a compiler for the 2015 version of
-the P4 programming language, also called P4_16.  For the P4
-programming language see http://p4.org.
+is a reference implementation of a compiler for the 2016 version of
+the P4 programming language, also called P4-16.  The P4-16 draft spec
+is available at
+http://p4.org/wp-content/uploads/2016/12/P4_16-prerelease-Dec_16.html.
+For the P4 programming language see http://p4.org.
 
 The code contains three sample compiler back-ends:
-* p4c-bm2-ss: can be used to target the P4 simple_switch written using
+* p4c-bm2-ss: can be used to target the P4 `simple_switch` written using
   the BMv2 behavioral model https://github.com/p4lang/behavioral-model
 * p4c-ebpf: can be used to generate C code which can be compiled to EBPF
-  https://en.wikipedia.org/wiki/Berkeley_Packet_Filter
+  https://en.wikipedia.org/wiki/Berkeley_Packet_Filter and then loaded
+  in the Linux kernel for packet filtering
 * p4test: a source-to-source P4 translator which can be used for
-  testing, learning and debugging
-All these compilers can accept both P4_14 (i.e., P4 v1.0, v1.1) and
-P4_16 programs.
+  testing, learning compiler internals and debugging.
+
+Some of these compilers can accept both
+[P4-14](http://p4.org/wp-content/uploads/2016/11/p4-spec-latest.pdf)
+(i.e., P4 v1.0, v1.1) and
+[P4-16](http://p4.org/wp-content/uploads/2016/12/P4_16-prerelease-Dec_16.html)
+programs.
 
 The code and documentation are hosted in the following git repository:
 https://github.com/p4lang/p4c
@@ -33,17 +40,17 @@ following tools are required to build and run the compiler and tests:
 
 - Boehm-Weiser garbage-collector C++ library
 
-- Gnu Bison and Gnu Flex
+- GNU Bison and Flex (parser and lexical analyzer generators)
 
-- Gnu multiple precision library GMP
+- GNU multiple precision library GMP
 
 - C++ boost library (minimally used)
 
 - Python 2.7 for scripting (especially for running tests)
 
 The compiler is modular, and it contains multiple back-ends.  New ones can be added easily.
 Each back-end may have additional dependences.  This repository contains the following two
-back-ends; please read for installing more dependences:
+back-ends; please read the following documents for installing more dependences:
   * [BMv2](backends/bmv2/README.md)
   * [eBPF](backends/ebpf/README.md)
 
@@ -78,12 +85,13 @@ Installing on macOS:
   brew install gmp --c++11
   ```
 
-  By default, Homebrew doesn't link programs into `/usr/local/bin` if they would
-  conflict with a version provided by the base system. This includes Bison,
-  since an older version ships with macOS. `make check` depends on the newer
-  Bison we just installed from Homebrew (see #83), so you'll want to add it to
-  your `$PATH` one way or another. One simple way to do that is to request that
-  Homebrew link it into `/usr/local/bin`:
+  By default, Homebrew doesn't link programs into `/usr/local/bin` if
+  they would conflict with a version provided by the base system. This
+  includes Bison, since an older version ships with macOS. `make
+  check` depends on the newer Bison we just installed from Homebrew
+  (see [#83](http://github.com/p4lang/p4c/issues/83)), so you'll want
+  to add it to your `$PATH` one way or another. One simple way to do
+  that is to request that Homebrew link it into `/usr/local/bin`:
   ```
   brew link --force bison
   ```

backends/ebpf/README.md

@@ -27,7 +27,8 @@ http://www.sigcomm.org/ccr/papers/2014/July/0000000.0000004:
 
 P4 itself is protocol-independent but allows programmers to express a
 rich set of data plane behaviors and protocols.  This back-end only
-supports the newest version of the P4 programming language, P4_16. The
+supports the newest version of the P4 programming language,
+[P4_16](http://p4.org/wp-content/uploads/2016/12/P4_16-prerelease-Dec_16.html). The
 core P4 abstractions are:
 
 * Headers describe the format (the set of fields and their

docs/README.md

@@ -46,7 +46,7 @@ p4c
   http://p4.org/wp-content/uploads/2015/04/p4-latest.pdf
 
 * the P4_16 draft language is described in [this pdf
-  document](https://github.com/p4lang/p4-spec/wiki/P4-16-draft-spec.pdf).
+  document](http://p4.org/wp-content/uploads/2016/12/P4_16-prerelease-Dec_16.pdf).
   This language is still under revision.
 
 * the core design of the compiler intermediate representation (IR) and
@@ -65,91 +65,26 @@ p4c
   * Discussion of the three sample back-ends
 
 * Specific back-ends may have their own documentation; check the
-  `extensions` sub-folders, and also:
+  `extensions` sub-folders, and also the following supplied back-ends:
   * [BMv2](../backends/bmv2/README.md)
   * [eBPF](../backends/ebpf/README.md)
 
-# Coding conventions
-
-* Coding style is guided by the [following
-  rules](CodingStandardPhilosophy.md)
-
-* We use several (but not all) of the [Google C++ coding style
-  guidelines](https://google.github.io/styleguide/cppguide.html).
-  We have customized Google's `cpplint.py` tool for our
-  purposes.  The tool can be invoked with `make cpplint`.
-
-* watch out for `const`; it is very important.
-
-* use `override` whenever possible (new gcc versions enforce this)
-
-* never use `const_cast` and `reinterpret_cast`.
-
-* The C++ code is written to use a garbage-collector
-  * do not use any smart pointers, just raw pointers
-* Use our implementations and wrappers instead of standard classes:
-
-  * use `cstring` for constant strings.  For java programmers, `cstring`
-    should be used where you would use java.lang.String, and `std::string`
-    should be used where you would use StringBuilder or StringBuffer.
-
-  * use the `BUG()` macro to signal an exception.  This macro is
-    guaranteed to throw an exception.
-
-  * use `CHECK_NULL()` to validate that pointers are not nullptr
-
-  * use `BUG_CHECK()` instead of `assert`, and always supply an
-    informative error message
-
-  * use `::error()` and `::warning()` for error reporting.  They use the
-    `boost::format` for the format argument, which has some compatibility
-    for `printf` arguments.   These functions handle IR and SourceInfo
-    objects smartly.  Here is an example:
-
-```C++
-IR::NamedRef *ref;
-error("%1%: No header or metadata named '%2%'", ref->srcInfo, ref->name);
-```
-
-output:
-
-```
-../testdata/v1_errors/missing_decls1.p4(6): Error: No header or metadata named 'data'
-    if (data.b2 == 0) {
-        ^^^^
-```
-
-  * use `LOGn()` for log messages -- the `n` is an integer constant for
-    verbosity level.  These can be controlled on a per-source-file basis
-    with the -T option.  LOG1 should be used for general messages, so that
-    running with -T*:1 (turning on all LOG1 messages) is not too overwhelming.
-    LOG2 should be used to print information about the results of a module
-    that later passes may need to debug them.  Details of what a module
-    or pass is doing and looking at (only of interest when debugging that
-    code) should be at LOG4 or higher.
-
-  * use the `vector` and `array` wrappers for `std::vector` and `std::array`
-    (these do bounds checking on all accesses).
-
-  * use `ordered_map` and `ordered_set` when you need to iterate;
-    they provide deterministic iterators
-
 # How to contribute
 
 * do write unit test code
 * code has to be reviewed before it is merged
 * make sure all tests pass when you send a pull request (only PASS tests allowed)
 * make sure `make cpplint` produces no errors
 
-# Git usage
+## Git usage
 
 * To contribute: fork the p4lang/p4c repository on github
   (see https://help.github.com/articles/fork-a-repo/)
 * To merge a forked repository with the latest changes in the source use:
   `git fetch upstream; git merge upstream/master`
 * After committing changes, create a pull request (using the github web UI)
 
-# Debugging
+## Debugging
 
 * To debug the build process you can run `make V=1`
 
@@ -195,7 +130,7 @@ output:
   in file `pass_manager.cpp` above level 2, use the following compiler
   command-line option: `-Tnode:1,pass_manager:2`
 
-# Testing
+## Testing
 
 The testing infrastructure is based on autotools.  We use several
 small python and shell scripts to work around limitations of
@@ -215,3 +150,68 @@ autotools.
 
 * Code for running various compiler back-ends on p4 files is generated
   using a simple python script `tools/gen-tests.py`.
+
+## Coding conventions
+
+* Coding style is guided by the [following
+  rules](CodingStandardPhilosophy.md)
+
+* We use several (but not all) of the [Google C++ coding style
+  guidelines](https://google.github.io/styleguide/cppguide.html).
+  We have customized Google's `cpplint.py` tool for our
+  purposes.  The tool can be invoked with `make cpplint`.
+
+* watch out for `const`; it is very important.
+
+* use `override` whenever possible (new gcc versions enforce this)
+
+* never use `const_cast` and `reinterpret_cast`.
+
+* The C++ code is written to use a garbage-collector
+  * do not use any smart pointers, just raw pointers
+* Use our implementations and wrappers instead of standard classes:
+
+  * use `cstring` for constant strings.  For java programmers, `cstring`
+    should be used where you would use java.lang.String, and `std::string`
+    should be used where you would use StringBuilder or StringBuffer.
+
+  * use the `BUG()` macro to signal an exception.  This macro is
+    guaranteed to throw an exception.
+
+  * use `CHECK_NULL()` to validate that pointers are not nullptr
+
+  * use `BUG_CHECK()` instead of `assert`, and always supply an
+    informative error message
+
+  * use `::error()` and `::warning()` for error reporting.  They use the
+    `boost::format` for the format argument, which has some compatibility
+    for `printf` arguments.   These functions handle IR and SourceInfo
+    objects smartly.  Here is an example:
+
+```C++
+IR::NamedRef *ref;
+error("%1%: No header or metadata named '%2%'", ref->srcInfo, ref->name);
+```
+
+output:
+
+```
+../testdata/v1_errors/missing_decls1.p4(6): Error: No header or metadata named 'data'
+    if (data.b2 == 0) {
+        ^^^^
+```
+
+  * use `LOGn()` for log messages -- the `n` is an integer constant for
+    verbosity level.  These can be controlled on a per-source-file basis
+    with the -T option.  LOG1 should be used for general messages, so that
+    running with -T*:1 (turning on all LOG1 messages) is not too overwhelming.
+    LOG2 should be used to print information about the results of a module
+    that later passes may need to debug them.  Details of what a module
+    or pass is doing and looking at (only of interest when debugging that
+    code) should be at LOG4 or higher.
+
+  * use the `vector` and `array` wrappers for `std::vector` and `std::array`
+    (these do bounds checking on all accesses).
+
+  * use `ordered_map` and `ordered_set` when you need to iterate;
+    they provide deterministic iterators