Move Ozone developer documentation into the chromium tree

docs/ozone_overview.md

Index: docs/ozone_overview.md
diff --git a/docs/ozone_overview.md b/docs/ozone_overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..5ea2f24f6ba30a7d86b06db2efafa8ad780f79f4
--- /dev/null
+++ b/docs/ozone_overview.md
@@ -0,0 +1,277 @@
+# Ozone Overview
+
+Ozone is a platform abstraction layer beneath the Aura window system that is
+used for low level input and graphics. Once complete, the abstraction will

[rjkroege, 2016/10/28 20:22:13]

The abstraction is complete already for internal-window uses. Do you want to
explain this difference perhaps?

[fwang, 2016/10/31 10:42:51]

This was in the original doc, I did not change it. Let's do that in follow-up
changes.

+support underlying systems ranging from embedded SoC targets to new
+X11-alternative window systems on Linux such as Wayland or Mir to bring up Aura
+Chromium by providing an implementation of the platform interface.
+
+## Guiding Principles
+
+Our goal is to enable chromium to be used in a wide variety of projects by
+making porting to new platforms easy. To support this goal, ozone follows the
+following principles:
+
+1. **Interfaces, not ifdefs**. Differences between platforms are handled by
+   calling a platform-supplied object through an interface instead of using
+   conditional compilation. Platform internals remain encapsulated, and the
+   public interface acts as a firewall between the platform-neutral upper
+   layers (aura, blink, content, etc) and the platform-specific lower layers.
+   The platform layer is relatively centralized to minimize the number of
+   places ports need to add code.
+2. **Flexible interfaces**. The platform interfaces should encapsulate just what
+   chrome needs from the platform, with minimal constraints on the platform's
+   implementation as well as minimal constraints on usage from upper layers. An
+   overly prescriptive interface is less useful for porting because fewer ports
+   will be able to use it unmodified. Another way of stating is that the
+   platform layer should provide mechanism, not policy.
+3. **Runtime binding of platforms**. Avoiding conditional compilation in the
+   upper layers allows us to build multiple platforms into one binary and bind
+   them at runtime. We allow this and provide a command-line flag to select a
+   platform (`--ozone-platform`) if multiple are enabled. Each platform has a
+   unique build define (e.g. `ozone_platform_foo`) that can be turned on or off
+   independently.
+4. **Easy out-of-tree platforms**. Most ports begin as forks. Some of them
+   later merge their code upstream, others will have an extended life out of
+   tree. This is OK, and we should make this process easy to encourage ports,

[rjkroege, 2016/10/28 20:22:13]

something funny in this sentence?

[fwang, 2016/10/31 10:42:50]

This was in the original documentation too. Not sure my English is good enough
to make a better wording, so let's do it in follow-up changes too.

+   and to encourage frequent gardening of chromium changes into the downstream
+   project. If gardening an out-of-tree port is hard, then those projects will
+   simply ship outdated and potentially insecure chromium-derived code to users.
+   One way we support these projects is by providing a way to inject additional
+   platforms into the build by only patching one `ozone_extra.gni` file.
+
+## Ozone Platform Interface
+
+Ozone moves platform-specific code behind the following interfaces:
+
+* `PlatformWindow` represents a window in the windowing system underlying
+  chrome. Interaction with the windowing system (resize, maximize, close, etc)
+  as well as dispatch of input events happens via this interface. Under aura, a
+  `PlatformWindow` corresponds to a `WindowTreeHost`. Under mojo, it corresponds

[rjkroege, 2016/10/28 20:22:13]

What do you mean "under mojo"? You mean mus?

[fwang, 2016/10/31 10:42:51]

Again in the original documentation, no ideas what is meant here. In this CL, I
just added new interfaces and removed obsolete ones. To be honest I did not try
to check whether this paragraph is (still) correct.

+  to a `NativeViewport`. On bare hardware, the underlying windowing system is

[rjkroege, 2016/10/28 20:22:13]

What is a NativeViewport? This is at odds with my understanding. Per
https://cs.chromium.org/chromium/src/services/ui/ws/platform_display.cc?sq=pa...,
I claim that the ozone PlatformWindow is connected to a mus window server's
PlatformDisplay.

[fwang, 2016/10/31 10:42:51]

Same here, let's handle that in follow-up CLs :-)

+  very simple and a platform window corresponds to a physical display.
+* `SurfaceFactoryOzone` is used to create surfaces for the Chrome compositor to
+  paint on using EGL/GLES2 or Skia.
+* `GpuPlatformSupportHost` provides the platform code
+  access to IPC between the browser & GPU processes. Some platforms need this
+  to provide additional services in the GPU process such as display
+  configuration.
+* `CursorFactoryOzone` is used to load & set platform cursors.
+* `OverlayManagerOzone` is used to manage overlays.
+* `InputController` allows to control input devices such as keyboard, mouse or
+  touchpad.
+* `SystemInputInjector` converts input into events and injects them to the
+  Ozone platform.
+* `NativeDisplayDelegate` is used to support display configuration & hotplug.
+
+## Ozone in Chromium
+
+Our implementation of Ozone required changes concentrated in these areas:
+
+* Cleaning up extensive assumptions about use of X11 throughout the tree,

[rjkroege, 2016/10/28 20:22:13]

I recall that this was vaguely tedious. :-)

[fwang, 2016/10/31 10:42:50]

:-)

+  protecting this code behind the `USE_X11` ifdef, and adding a new `USE_OZONE`
+  path that works in a relatively platform-neutral way by delegating to the
+  interfaces described above.
+* a `WindowTreeHostOzone` to send events into Aura and participate in display

[rjkroege, 2016/10/28 20:22:13]

We don't use this in mus.

[fwang, 2016/10/31 10:42:51]

I'll do yet another "in the original document, handle this later" reply.

+  management on the host system, and
+* an Ozone-specific flavor of `GLSurfaceEGL` which delegates allocation of
+  accelerated surfaces and refresh syncing to the provided implementation of
+  `SurfaceFactoryOzone`.
+
+## Porting with Ozone
+
+Users of the Ozone abstraction need to do the following, at minimum:
+
+* Write a subclass of `PlatformWindow`. This class (I'll call it
+  `PlatformWindowImpl`) is responsible for window system integration. It can
+  use `MessagePumpLibevent` to poll for events from file descriptors and then
+  invoke `PlatformWindowDelegate::DispatchEvent` to dispatch each event.
+* Write a subclass of `SurfaceFactoryOzone` that handles allocating accelerated
+  surfaces. I'll call this `SurfaceFactoryOzoneImpl`.
+* Write a subclass of `CursorFactoryOzone` to manage cursors, or use the
+  `BitmapCursorFactoryOzone` implementation if only bitmap cursors need to be
+  supported.
+* Write a subclass of `OverlayManagerOzone` or just use `StubOverlayManager` if
+  your platform does not support overlays.
+* Write a subclass of `NativeDisplayDelegate` if necessary or just use
+  `FakeDisplayDelegate`.
+* Write a subclass of `GpuPlatformSupportHost` or just use
+  `StubGpuPlatformSupportHost`.
+* Write a subclass of `InputController` or just use `StubInputController`.
+* Write a subclass of `SystemInputInjector` if necessary.
+* Write a subclass of `OzonePlatform` that owns instances of
+  the above subclasses and provide a static constructor function for these
+  objects. This constructor will be called when
+  your platform is selected and the returned objects will be used to provide
+  implementations of all the ozone platform interfaces.
+  If your platform does not need some of the interfaces then you can just
+  return a `Stub*` instance or a `nullptr`.
+
+## Adding an Ozone Platform to the build (instructions for out-of-tree ports)
+
+The recommended way to add your platform to the build is as follows. This walks
+through creating a new ozone platform called `foo`.
+
+1. Fork `chromium/src.git`.
+2. Add your implementation in `ui/ozone/platform/` alongside internal platforms.
+3. Patch `ui/ozone/ozone_extra.gni` to add your `foo` platform.
+
+## Building with Ozone
+
+### ChromeOS - ([waterfall](http://build.chromium.org/p/chromium.chromiumos/waterfall?builder=Linux+ChromiumOS+Ozone+Builder&builder=Linux+ChromiumOS+Ozone+Tests+%281%29&builder=Linux+ChromiumOS+Ozone+Tests+%282%29&reload=none))
+
+Building & running `chrome` (do this from the `src` directory):
+
+``` shell
+gn args out/OzoneChromeOS --args="use_ozone=true target_os=\"chromeos\""
+ninja -C out/OzoneChromeOS chrome
+./out/OzoneChromeOS/chrome --ozone-platform=x11 --no-sandbox

[rjkroege, 2016/10/28 20:22:13]

I think it's worth noting that other platforms are available and x11 is only an
example of one?

[fwang, 2016/10/31 10:42:50]

The original doc did that with "headless" without any explanation (BTW I changed
it to x11 since software rendering is not allowed on ChromeOS so headless does
not work) but yes I'll add a note.

[rjkroege, 2016/10/31 20:36:49]

headless runs on the builders.

[fwang, 2016/10/31 20:45:36]

Mmh, I don't think *chrome* runs in headless mode on ChromeOS, which was the
case provided in the original doc. IIUC, the builder only runs the headless
tests.

See also
https://groups.google.com/a/chromium.org/d/msg/ozone-dev/v84vr0MaQvE/m34EP3Zm...

+```
+
+### Embedded
+
+The following targets are currently working for embedded builds:
+
+* `content_shell`
+* various unit tests
+
+The following targets are currently NOT supported:
+
+* `ash_shell_with_content`
+* `chrome`
+
+Building & running `content_shell` (do this from the `src` directory):
+
+``` shell
+gn args out/OzoneEmbedded --args="use_ozone=true toolkit_views=false"
+ninja -C out/OzoneEmbedded content_shell
+./out/OzoneEmbedded/content_shell --no-sandbox \
+                                  --ozone-platform=headless \
+                                  --ozone-dump-file=/tmp/
+```
+
+### Linux Desktop - ([bug](http://crbug.com/295089))
+
+This is not supported by any of the in-tree platforms. Please see above and try
+a ChromeOS or embedded build for now.
+
+### GN Configuration notes

[rjkroege, 2016/10/28 20:22:13]

Awesome!

+
+You can turn properly implemented ozone platforms on and off by setting the
+corresponding flags in your GN configuration. For example
+`ozone_platform_headless=false ozone_platform_gbm=false` will turn off the
+headless and DRM/GBM platforms.
+This will result in a smaller binary and faster builds. To turn ALL platforms
+off by default, set `ozone_auto_platforms=false`.
+
+You can also specify a default platform to run by setting the `ozone_platform`
+build parameter. For example `ozone_platform="x11"` will make X11 the
+default platform when `--ozone-platform` is not passed to the program.
+If `ozone_auto_platforms` is true then `ozone_platform` is set to `headless`
+by default.
+
+## Running with Ozone
+
+Specify the platform you want to use at runtime using the `--ozone-platform`
+flag. During development you may need either to compile and use a sandbox,

[rjkroege, 2016/10/28 20:22:13]

The part of me beholden to security team would like you to emphasize that
turning off the sandbox is bad and developers should fix it as soon as possible.
And maybe remove --no-sandbox so that people who don't read this carefully don't
start thinking that --no-sandbox is ok.

[fwang, 2016/10/31 10:42:50]

OK, I'll put back --disable-setuid-sandbox everywhere as in the original doc. I
think Antonio was able to make some cases work by building a sandbox but I was
not so lucky (I always had to use --no-sandbox).

[rjkroege, 2016/10/31 20:36:49]

I think that additional words are needed in a future CL.

+to disable the setuid sandbox (using the `--disable-setuid-sandbox` flag) or to
+completly ignore the sandbox (using the `--no-sandbox` flag).
+
+For example, to run content_shell with the GBM platform:
+
+``` shell
+content_shell --no-sandbox --ozone-platform=gbm
+```
+
+Caveats:
+
+* `content_shell` always runs at 800x600 resolution

[rjkroege, 2016/10/28 20:22:13]

. at end?

[fwang, 2016/10/31 10:42:51]

Acknowledged.

+* For the GBM platform, you may need to terminate your X server (or any other
+  display server) prior to testing.
+
+## Ozone Platforms
+
+### Headless
+
+This platform
+draws graphical output to a PNG image (no GPU support; software rendering only)
+and will not output to the screen. You can set
+the path of the directory where to output the images
+by specifying `--ozone-dump-file=/path/to/output-directory` on the
+command line:
+
+``` shell
+content_shell --no-sandbox \
+              --ozone-platform=headless \
+              --ozone-dump-file=/tmp/
+```
+
+### DRM/GBM
+
+This is Linux direct rending with acceleration via mesa GBM & linux DRM/KMS
+(EGL/GLES2 accelerated rendering & modesetting in GPU process).

[rjkroege, 2016/10/28 20:22:13]

And is in production use on ChromeOS. And maybe add a link to some kind of
ChromeOS page?

I think it's worth adding that all ChromeOS builds of Chrome will compile and
attempt to use this. You can link to
https://www.chromium.org/chromium-os/how-tos-and-troubleshooting/building-chr...
for build instructions.

[fwang, 2016/10/31 10:42:51]

OK, I'll try to add these. Again, for this and other platforms I just copy the
original doc. I suspect for each of them we should give more details about the
platform and how to build it, but probably in follow-up CLs.

+
+### Cast
+
+This platform is used for
+[Chromecast](https://www.google.com/intl/en_us/chromecast/).
+
+### X11
+
+This platform provides support for the [X window system](https://www.x.org/).
+
+### Wayland
+
+This platform provides support for the
+[Wayland](http://wayland.freedesktop.org/) display protocol. It was
+initially developed by Intel as
+[a fork of chromium](https://github.com/01org/ozone-wayland)
+and then partially upstreamed.
+It is still actively being developed in the chromium tree, feel free to discuss
+with us on freenode.net, `#ozone-wayland` channel or on `ozone-dev`.
+
+In order to run an Ozone build of `chrome`, you currently (2016/10/28)
+need to compile it for ChromeOS, where software rendering is not allowed.
+Also, accelerated rendering only works in Ozone/Wayland when the UI and GPU
+components are running in the same process. Below are some quick build & run
+instructions. It is assumed that you are launching `chrome` from a Wayland
+environment such as `weston`.
+
+``` shell
+gn args out/OzoneWayland --args="use_ozone=true ozone_platform_wayland=true target_os=\"chromeos\""
+ninja -C out/OzoneWayland chrome
+./out/OzoneWayland/chrome --ozone-platform=wayland --in-process-gpu --no-sandbox
+```
+
+### Caca
+
+This platform
+draws graphical output to text using
+[libcaca](http://caca.zoy.org/wiki/libcaca)
+(no GPU support; software
+rendering only). In case you ever wanted to test embedded content shell on
+tty.
+It has been
+[removed from the tree](https://codereview.chromium.org/2445323002/) and is no
+longer maintained but you can try the
+[latest working revision](https://chromium.googlesource.com/chromium/src/+/0e64be9cf335ee3bea7c989702c5a9a0934af037/ui/ozone/platform/caca/).
+You need additional dependencies (libcaca shared library and development files)
+that are not provided in the sysroot. Here are quick instructions to build and
+run it:
+
+``` shell
+# Do this at revision 0e64be9cf335ee3bea7c989702c5a9a0934af037
+gclient sync --with_branch_heads
+gn args out/OzoneCaca \
+        --args="use_ozone=true ozone_platform_caca=true use_sysroot=false ozone_auto_platforms=false toolkit_views=false"
+ninja -C out/OzoneCaca content_shell
+./out/OzoneCaca/content_shell --no-sandbox
+```
+
+  Note: traditional TTYs are not the ideal browsing experience.<br/>
+  [![Picture of a workstation using Ozone/caca to display the Google home page in a text terminal](https://www.chromium.org/_/rsrc/1396307876689/developers/design-documents/ozone/IMG_20140331_151619.jpg?height=240&amp;width=320)](https://www.chromium.org/developers/design-documents/ozone/IMG_20140331_151619.jpg?attredirects=0)
+
+## Communication
+
+There is a public mailing list:
+[ozone-dev@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/ozone-dev)