5 files changed, 170 insertions, 17 deletions
diff --git a/doc/c-style-guide.md b/doc/c-style-guide.md
index d6f9bbd7d4..369bd56a46 100644
--- a/doc/c-style-guide.md
+++ b/doc/c-style-guide.md
@@ -9,16 +9,17 @@ Here we document style rules for C usage in the gRPC Core library.
 General
 -------
 
-- Layout rules are defined by clang-format, and all code should be passed through
-  clang-format. A (docker-based) script to do so is included in 
-  [tools/distrib/clang\_format\_code.sh] (../tools/distrib/clang_format_code.sh).
+- Layout rules are defined by clang-format, and all code should be passed
+  through clang-format. A (docker-based) script to do so is included in
+  [tools/distrib/clang\_format\_code.sh](../tools/distrib/clang_format_code.sh).
 
 Header Files
 ------------
 
-- Public header files (those in the include/grpc tree) should compile as pedantic C89
-- Public header files should be includable from C++ programs. That is, they should 
-  include the following:
+- Public header files (those in the include/grpc tree) should compile as
+  pedantic C89.
+- Public header files should be includable from C++ programs. That is, they
+  should include the following:
   ```c
   #ifdef __cplusplus
   extern "C" {
@@ -34,24 +35,34 @@ Header Files
 - All header files should have a #define guard to prevent multiple inclusion.
   To guarantee uniqueness they should be based on the file's path.
 
-  For public headers: include/grpc/grpc.h --> GRPC_GRPC_H
+  For public headers: `include/grpc/grpc.h` → `GRPC_GRPC_H`
+
+  For private headers:
+  `src/core/channel/channel_stack.h` →
+  `GRPC_INTERNAL_CORE_CHANNEL_CHANNEL_STACK_H`
+
+Variable Initialization
+-----------------------
+
+When declaring a (non-static) pointer variable, always initialize it to `NULL`.
+Even in the case of static pointer variables, it's recommended to explicitly
+initialize them to `NULL`.
 
-  For private headers: 
-  src/core/channel/channel_stack.h --> GRPC_INTERNAL_CORE_CHANNEL_CHANNEL_STACK_H
 
 C99 Features
 ------------
 
-- Variable sized arrays are not allowed
-- Do not use the 'inline' keyword
-- Flexible array members are allowed (https://en.wikipedia.org/wiki/Flexible_array_member)
+- Variable sized arrays are not allowed.
+- Do not use the 'inline' keyword.
+- Flexible array members are allowed
+  (https://en.wikipedia.org/wiki/Flexible_array_member).
 
 Comments
 --------
 
 Within public header files, only `/* */` comments are allowed.
 
-Within implementation files and private headers, either single line `//` 
+Within implementation files and private headers, either single line `//`
 or multi line `/* */` comments are allowed. Only one comment style per file is
 allowed however (i.e. if single line comments are used anywhere within a file,
 ALL comments within that file must be single line comments).
@@ -59,7 +70,15 @@ ALL comments within that file must be single line comments).
 Symbol Names
 ------------
 
-- Non-static functions must be prefixed by grpc_
-- static functions must not be prefixed by grpc_
-- enumeration values and #define names are uppercased, all others are lowercased
-- Multiple word identifiers use underscore as a delimiter (NEVER camel casing)
+- Non-static functions must be prefixed by `grpc_`
+- Static functions must *not* be prefixed by `grpc_`
+- Enumeration values and `#define` names must be uppercase. All other values
+  must be lowercase.
+- Multiple word identifiers use underscore as a delimiter, *never* camel
+  case. E.g. `variable_name`.
+
+Functions
+----------
+
+- The use of [`atexit()`](http://man7.org/linux/man-pages/man3/atexit.3.html) is
+  in forbidden in libgrpc.
diff --git a/doc/compression_cookbook.md b/doc/compression_cookbook.md
new file mode 100644
index 0000000000..c10a805f20
--- /dev/null
+++ b/doc/compression_cookbook.md
@@ -0,0 +1,133 @@
+# gRPC (Core) Compression Cookbook
+
+## Introduction
+
+This document describes compression as implemented by the gRPC C core. See [the
+full compression specification](compression.md) for details.
+
+### Intended Audience
+
+Wrapped languages developers, for the purposes of supporting compression by
+interacting with the C core.
+
+## Criteria for GA readiness
+
+1. Be able to set compression at [channel](#per-channel-settings),
+   [call](#per-call-settings) and [message](#per-message-settings) level.
+   In principle this API should be based on _compression levels_ as opposed to
+   algorithms. See the discussion [below](#level-vs-algorithms).
+1. Have unit tests covering [the cases from the
+   spec](https://github.com/grpc/grpc/blob/master/doc/compression.md#test-cases).
+1. Interop tests implemented and passing on Jenkins. The two relevant interop
+   test cases are
+   [large_compressed_unary](https://github.com/grpc/grpc/blob/master/doc/interop-test-descriptions.md#large_compressed_unary)
+   and
+   [server_compressed_streaming](https://github.com/grpc/grpc/blob/master/doc/interop-test-descriptions.md#server_compressed_streaming).
+
+## Summary Flowcharts
+
+The following flowcharts depict the evolution of a message, both _incoming_ and
+_outgoing_, irrespective of the client/server character of the call. Aspects
+still not symmetric between clients and servers (e.g. the [use of compression
+levels](https://github.com/grpc/grpc/blob/master/doc/compression.md#compression-levels-and-algorithms))
+are explicitly marked. The in-detail textual description for the different
+scenarios is described in subsequent sections.
+
+## Incoming Messages
+
+![image](images/compression_cookbook_incoming.png)
+
+## Outgoing Messages
+
+![image](images/compression_cookbook_outgoing.png)
+
+## Levels vs Algorithms
+
+As mentioned in [the relevant discussion on the spec
+document](https://github.com/grpc/grpc/blob/master/doc/compression.md#compression-levels-and-algorithms),
+compression _levels_ are the primary mechanism for compression selection _at the
+server side_. In the future, it'll also be at the client side. The use of levels
+abstracts away the intricacies of selecting a concrete algorithm supported by a
+peer, on top of removing the burden of choice from the developer.
+As of this writing (Q2 2016), clients can only specify compression _algorithms_.
+Clients will support levels as soon as an automatic retry/negotiation mechanism
+is in place.
+
+## Per Channel Settings
+
+Compression may be configured at channel creation. This is a convenience to
+avoid having to repeatedly configure compression for every call. Note that any
+compression setting on individual [calls](#per-call-settings) or
+[messages](#per-message-settings) overrides channel settings.
+
+The following aspects can be configured at channel-creation time via channel arguments:
+
+#### Disable Compression _Algorithms_
+
+Use the channel argument key
+`GRPC_COMPRESSION_CHANNEL_ENABLED_ALGORITHMS_BITSET` (from
+[`grpc/impl/codegen/compression_types.h`](https://github.com/grpc/grpc/blob/master/include/grpc/impl/codegen/compression_types.h)),
+takes a 32 bit bitset value. A set bit means the algorithm with that enum value
+according to `grpc_compression_algorithm` is _enabled_.
+For example, `GRPC_COMPRESS_GZIP` currently has a numeric value of 2. To
+enable/disable GZIP for a channel, one would set/clear the 3rd LSB (eg, 0b100 =
+0x4). Note that setting/clearing 0th position, that corresponding to
+`GRPC_COMPRESS_NONE`, has no effect, as no-compression (a.k.a. _identity_) is
+always supported.
+Incoming messages compressed (ie, encoded) with a disabled algorithm will result
+in the call being closed with `GRPC_STATUS_UNIMPLEMENTED`.
+
+#### Default Compression _Level_
+
+**(currently, Q2 2016, only applicable for server side channels. It's ignored
+for clients.)**
+Use the channel argument key `GRPC_COMPRESSION_CHANNEL_DEFAULT_LEVEL` (from
+[`grpc/impl/codegen/compression_types.h`](https://github.com/grpc/grpc/blob/master/include/grpc/impl/codegen/compression_types.h)),
+valued by an integer corresponding to a value from the `grpc_compression_level`
+enum.
+
+#### Default Compression _Algorithm_
+
+Use the channel argument key `GRPC_COMPRESSION_CHANNEL_DEFAULT_ALGORITHM` (from
+[`grpc/impl/codegen/compression_types.h`](https://github.com/grpc/grpc/blob/master/include/grpc/impl/codegen/compression_types.h)),
+valued by an integer corresponding to a value from the `grpc_compression_level`
+enum.
+
+## Per Call Settings
+
+### Compression **Level** in Call Responses
+
+The server requests a compression level via initial metadata. The
+`send_initial_metadata` `grpc_op` contains a `maybe_compression_level` field
+with two fields, `is_set` and `compression_level`. The former must be set when
+actively choosing a level to disambiguate the default value of zero (no
+compression) from the proactive selection of no compression.
+
+The core will receive the request for the compression level and automatically
+choose a compression algorithm based on its knowledge about the peer
+(communicated by the client via the `grpc-accept-encoding` header. Note that the
+absence of this header means no compression is supported by the client/peer).
+
+### Compression **Algorithm** in Call Responses
+
+**Server should avoid setting the compression algorithm directly**. Prefer
+setting compression levels unless there's a _very_ compelling reason to choose
+specific algorithms (benchmarking, testing).
+
+Selection of concrete compression algorithms is performed by adding a
+`(GRPC_COMPRESS_REQUEST_ALGORITHM_KEY, <algorithm-name>)` key-value pair to the
+initial metadata, where `GRPC_COMPRESS_REQUEST_ALGORITHM_KEY` is defined in
+[`grpc/impl/codegen/compression_types.h`](https://github.com/grpc/grpc/blob/master/include/grpc/impl/codegen/compression_types.h)),
+and `<algorithm-name>` is the human readable name of the algorithm as given in
+[the HTTP2 spec](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md)
+for `Message-Encoding` (e.g. gzip, identity, etc.). See
+[`grpc_compression_algorithm_name`](https://github.com/grpc/grpc/blob/master/src/core/lib/compression/compression.c)
+for the mapping between the `grpc_compression_algorithm` enum values and their
+textual representation.
+
+## Per Message Settings
+
+To disable compression for a specific message, the `flags` field of `grpc_op`
+instances of type `GRPC_OP_SEND_MESSAGE` must have its `GRPC_WRITE_NO_COMPRESS`
+bit set. Refer to
+[`grpc/impl/codegen/compression_types.h`](https://github.com/grpc/grpc/blob/master/include/grpc/impl/codegen/compression_types.h)),
diff --git a/doc/images/compression_cookbook_incoming.png b/doc/images/compression_cookbook_incoming.png
new file mode 100644
index 0000000000..84d6f558b6
--- /dev/null
+++ b/doc/images/compression_cookbook_incoming.png
diff --git a/doc/images/compression_cookbook_outgoing.png b/doc/images/compression_cookbook_outgoing.png
new file mode 100644
index 0000000000..59b995d154
--- /dev/null
+++ b/doc/images/compression_cookbook_outgoing.png
diff --git a/doc/statuscodes.md b/doc/statuscodes.md
index c918f9ed9a..1cd72df30a 100644
--- a/doc/statuscodes.md
+++ b/doc/statuscodes.md
@@ -18,6 +18,7 @@ Only a subset of the pre-defined status codes are generated by the gRPC librarie
 | Could not decompress, but compression algorithm supported (Server -> Client)	| INTERNAL | Client |
 | Compression mechanism used by client not supported at server	| UNIMPLEMENTED | Server |
 | Server temporarily out of resources (e.g., Flow-control resource limits reached) |	RESOURCE_EXHAUSTED | Server|
+| Client does not have enough memory to hold the server response | RESOURCE_EXHAUSTED | Client |
 | Flow-control protocol violation |	INTERNAL | Both |
 | Error parsing returned status	| UNKNOWN | Client |
 | Incorrect Auth metadata ( Credentials failed to get metadata, Incompatible credentials set on channel and call, Invalid host set in `:authority` metadata, etc.) | UNAUTHENTICATED | Both |