Adds lots of Mojo documentation

Adds documentation for Mojo IPC conversion and Mojo public system
libraries for C and C++. Also updates Service Manager and client
library documentation.

BUG=
TBR=yzshen@chromium.org,ben@chromium.org

Review-Url: https://codereview.chromium.org/2783223004
Cr-Commit-Position: refs/heads/master@{#461306}

mojo/README.md

@@ -1,7 +1,142 @@
-Mojo
-====
+# ![Mojo Graphic](https://goo.gl/6CdlbH) Mojo
+This document is a subset of the [Mojo documentation](/mojo).
 
-[Mojo](https://www.chromium.org/developers/design-documents/mojo) is an IPC &
-binding mechanism for Chromium.
+[TOC]
+
+## Getting Started With Mojo
+
+To get started using Mojo in applications which already support it (such as
+Chrome), the fastest path forward will be to look at the bindings documentation
+for your language of choice ([**C++**](#C_Bindings),
+[**JavaScript**](#JavaScript-Bindings), or [**Java**](#Java-Bindings)) as well
+as the documentation for the
+[**Mojom IDL and bindings generator**](/mojo/public/tools/bindings).
+
+If you're looking for information on creating and/or connecting to services, see
+the top-level [Services documentation](/services).
+
+For specific details regarding the conversion of old things to new things, check
+out [Converting Legacy Chrome IPC To Mojo](/ipc).
+
+## System Overview
+
+Mojo is a layered collection of runtime libraries providing a platform-agnostic
+abstraction of common IPC primitives, a message IDL format, and a bindings
+library with code generation for multiple target languages to facilitate
+convenient message passing across arbitrary inter- and intra-process boundaries.
+
+The documentation here is segmented according to the different isolated layers
+and libraries comprising the system. The basic hierarchy of features is as
+follows:
+
+![Mojo Library Layering: EDK on bottom, different language bindings on top, public system support APIs in the middle](https://docs.google.com/drawings/d/1aNbLfF-fejgzxCxH_b8xAaCVvftW8BGTH_EHD7nvU1w/pub?w=570&h=327)
+
+## Embedder Development Kit (EDK)
+Every process to be interconnected via Mojo IPC is called a **Mojo embedder**
+and needs to embed the
+[**Embedder Development Kit (EDK)**](/mojo/edk/embedder) library. The EDK
+exposes the means for an embedder to physically connect one process to another
+using any supported native IPC primitive (*e.g.,* a UNIX domain socket or
+Windows named pipe) on the host platform.
+
+Details regarding where and how an application process actually embeds and
+configures the EDK are generaly hidden from the rest of the application code,
+and applications instead use the public System and Bindings APIs to get things
+done within processes that embed Mojo.
+
+## C System API
+Once the EDK is initialized within a process, the public
+[**C System API**](/mojo/public/c/system) is usable on any thread for the
+remainder of the process's lifetime. This is a lightweight API with a relatively
+small (and eventually stable) ABI. Typically this API is not used directly, but
+it is the foundation upon which all remaining upper layers are built. It exposes
+the fundamental capabilities to create and interact with various types of Mojo
+handles including **message pipes**, **data pipes**, and **shared buffers**.
+
+## High-Level System APIs
+
+There is a relatively small, higher-level system API for each supported
+language, built upon the low-level C API. Like the C API, direct usage of these
+system APIs is rare compared to the bindings APIs, but it is sometimes desirable
+or necessary.
+
+### C++
+The [**C++ System API**](/mojo/public/cpp/system) provides a layer of
+C++ helper classes and functions to make safe System API usage easier:
+strongly-typed handle scopers, synchronous waiting operations, system handle
+wrapping and unwrapping helpers, common handle operations, and utilities for
+more easily watching handle state changes.
+
+### JavaScript
+The [**JavaScript APIs**](/mojo/public/js) are WIP. :)
+
+### Java
+The [**Java System API**](/mojo/public/java/system) provides helper classes for
+working with Mojo primitives, covering all basic functionality of the low-level
+C API.
+
+## High-Level Bindings APIs
+Typically developers do not use raw message pipe I/O directly, but instead
+define some set of interfaces which are used to generate code that message pipe
+usage feel like a more idiomatic method-calling interface in the target
+language of choice. This is the bindings layer.
+
+### Mojom IDL and Bindings Generator
+Interfaces are defined using the [**Mojom IDL**](/mojo/public/tools/bindings),
+which can be fed to the [**bindings generator**](/mojo/public/tools/bindings) to
+generate code in various supported languages. Generated code manages
+serialization and deserialization of messages between interface clients and
+implementations, simplifying the code -- and ultimately hiding the message pipe
+-- on either side of an interface connection.
+
+### C++ Bindings
+By far the most commonly used API defined by Mojo, the
+[**C++ Bindings API**](/mojo/public/cpp/bindings) exposes a robust set of
+features for interacting with message pipes via generated C++ bindings code,
+including support for sets of related bindings endpoints, associated interfaces,
+nested sync IPC, versioning, bad-message reporting, arbitrary message filter
+injection, and convenient test facilities.
+
+### JavaScript Bindings
+The [**JavaScript APIs**](/mojo/public/js) are WIP. :)
+
+### Java Bindings
+The [**Java Bindings API**](/mojo/public/java/bindings) provides helper classes
+for working with Java code emitted by the bindings generator.
+
+## FAQ
+
+### Why not protobuf? Why a new thing?
+There are number of potentially decent answers to this question, but the
+deal-breaker is that a useful IPC mechanism must support transfer of native
+object handles (*e.g.* file descriptors) across process boundaries. Other
+non-new IPC things that do support this capability (*e.g.* D-Bus) have their own
+substantial deficiencies.
+
+### Are message pipes expensive?
+No. As an implementation detail, creating a message pipe is essentially
+generating two random numbers and stuffing them into a hash table, along with a
+few tiny heap allocations.
+
+### So really, can I create like, thousands of them?
+Yes! Nobody will mind. Create millions if you like. (OK but maybe don't.)
+
+### Can I use in-process message pipes?
+Yes, and message pipe usage is identical regardless of whether the pipe actually
+crosses a process boundary -- in fact this detail is intentionally obscured.
+
+Message pipes which don't cross a process boundary are efficient: sent messages
+are never copied, and a write on one end will synchronously modify the message
+queue on the other end. When working with generated C++ bindings, for example,
+the net result is that an `InterfacePtr` on one thread sending a message to a
+`Binding` on another thread (or even the same thread) is effectively a
+`PostTask` to the `Binding`'s `TaskRunner` with the added -- but often small --
+costs of serialization, deserialization, validation, and some internal routing
+logic.
+
+### What about ____?
+
+Please post questions to
+[`chromium-mojo@chromium.org`](https://groups.google.com/a/chromium.org/forum/#!forum/chromium-mojo)!
+The list is quite responsive.
 
-TODO(rockot): Describe the important subdirectories.

mojo/edk/embedder/README.md

@@ -1,4 +1,9 @@
-# Mojo Embedder Development Kit (EDK)
+# ![Mojo Graphic](https://goo.gl/6CdlbH) Mojo Embedder Development Kit (EDK)
+This document is a subset of the [Mojo documentation](/mojo).
+
+[TOC]
+
+## Overview
 
 The Mojo EDK is a (binary-unstable) API which enables a process to use Mojo both
 internally and for IPC to other Mojo-embedding processes.
@@ -8,6 +13,12 @@ confusingly) a direct dependency on the GN `//mojo/edk/system` target. Despite
 this fact, you should never reference any of the headers in `mojo/edk/system`
 directly, as everything there is considered to be an internal detail of the EDK.
 
+**NOTE:** Unless you are introducing a new binary entry point into the system
+(*e.g.,* a new executable with a new `main()` definition), you probably don't
+need to know anything about the EDK API. Most processes defined in the Chrome
+repo today already fully initialize the EDK so that Mojo's other public APIs
+"just work" out of the box.
+
 ## Basic Initialization
 
 In order to use Mojo in a given process, it's necessary to call
@@ -320,8 +331,16 @@ interface Foo {
 Once you've bootstrapped your process connection with a real mojom interface,
 you can avoid any further mucking around with EDK APIs or raw message pipe
 handles, as everything beyond this point - including the passing of other
-interface pipes - can be handled eloquently using public bindings APIs.
+interface pipes - can be handled eloquently using
+[public bindings APIs](/mojo#High-Level-Bindings-APIs).
+
+## Setting System Properties
+
+The public Mojo C System API exposes a
+[**`MojoGetProperty`**](/mojo/public/c/system#MojoGetProperty) function for
+querying global, embedder-defined property values. These can be set by calling:
+
+```
+mojo::edk::SetProperty(MojoPropertyType type, const void* value)
+```
 
-See [additional Mojo documentation](
-    https://www.chromium.org/developers/design-documents/mojo) for more
-information.

mojo/edk/system/dispatcher.h

@@ -54,7 +54,6 @@ class MOJO_SYSTEM_IMPL_EXPORT Dispatcher
     DATA_PIPE_PRODUCER,
     DATA_PIPE_CONSUMER,
     SHARED_BUFFER,
-    WAIT_SET,
     WATCHER,
 
     // "Private" types (not exposed via the public interface):