[Docs] Move MemoryInfra overview into repository

components/tracing/docs/memory_infra.md

Index: components/tracing/docs/memory_infra.md
diff --git a/components/tracing/docs/memory_infra.md b/components/tracing/docs/memory_infra.md
new file mode 100644
index 0000000000000000000000000000000000000000..5ce2c159b27a1b1973e75046ec65ecce140f0983
--- /dev/null
+++ b/components/tracing/docs/memory_infra.md
@@ -0,0 +1,154 @@
+# MemoryInfra
+
+MemoryInfra is a timeline-based profiling system integrated in chrome://tracing.
+It aims at creating Chrome-scale memory measurement tooling so that on any
+Chrome in the world --- desktop, mobile, Chrome OS or any other --- with the
+click of a button you can understand where memory is being used in your system.
+
+[TOC]
+
+## Getting Started
+
+ * Get a bleeding-edge or tip-of-tree build of Chrome.
+ * [Record a trace as usual][record-trace]: open [chrome://tracing][tracing] on
+   Desktop Chrome or [chrome://inspect?tracing][inspect-tracing] to trace Chrome
+   for Android.
+ * Make sure to enable the **memory-infra** category on the right.
+   ![Tick the memory-infra checkbox when recording a trace.][memory-infra-box]
+ * For now, some subsystems only work if Chrome is started with the
+   `--no-sandbox` flag. 
+   <!-- TODO(primiano) TODO(ssid): https://crbug.com/461788 -->
+
+[record-trace]:     https://sites.google.com/a/chromium.org/dev/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs
+[tracing]:          chrome://tracing
+[inspect-tracing]:  chrome://inspect?tracing
+[memory-infra-box]: images/record-trace-memory-infra.png
+
+After recording a trace, you will see the **timeline view**. Timeline view
+shows:
+
+ * Total resident memory grouped by process (at the top).
+ * Total resident memory grouped by subsystem (at the top).
+ * Allocated memory per subsystem for every process.
+
+Click one of the ![M][m-blue] dots to bring up the **analysis view**. Click
+on a cell in analysis view to reveal more information about its subsystem.
+PartitionAlloc for instance, has more details about its partitions.
+
+![Component details for PartitionAlloc][partalloc-details]
+
+The purple ![M][m-purple] dots represent heavy dumps. In these dumps, components
+can provide more details than in the regular dumps. The full details of the
+MemoryInfra UI are explained in its [design doc][mi-ui-doc].
+
+[m-blue]:            images/m-blue.png
+[partalloc-details]: images/partalloc-details.png
+[m-purple]:          images/m-purple.png
+[mi-ui-doc]:         https://docs.google.com/document/d/1b5BSBEd1oB-3zj_CBAQWiQZ0cmI0HmjmXG-5iNveLqw/edit
+
+## Columns
+
+**Columns in blue** reflect the amount of actual _physical memory_ used by the
+process. This is what exerts memory pressure on the system.
+
+ * **Total Resident**: (undocumented).

[Primiano Tucci (use gerrit), 2016/01/18 15:45:28]

I'd replace all these (undocumented) with TODO: document

[Ruud van Asseldonk, 2016/01/18 16:25:21]

Done.

+ * **Peak Total Resident**: (undocumented).
+ * **PSS**: (undocumented).
+ * **Private Dirty**: (undocumented).
+ * **Swapped**: (undocumented).
+
+**Columns in black** reflect the amount of _virtual memory_ requested by various

[Primiano Tucci (use gerrit), 2016/01/18 15:45:28]

_virtual memory_ : not really: these provide the best estimation they can
provide for resident memory requested by the various subsystems.

[Ruud van Asseldonk, 2016/01/18 16:25:21]

Fixed.

+subsystems of Chrome.
+
+ * **Blink GC**: Memory used by [Oilpan][oilpan].
+ * **CC**: Memory used by the compositor.
+   See [cc/memory][cc-memory] for the full details.
+ * **Discardable**: (undocumented).
+ * **Font Caches**: (undocumented).
+ * **GPU**: (undocumented).
+ * **GPU Memory Buffer**: (undocumented).
+ * **LevelDB**: (undocumented).
+ * **Malloc**: Memory allocated by calls to `malloc`, or `new` for most
+     non-Blink objects.
+ * **PartitionAlloc**: Memory allocated via [PartitionAlloc][partalloc].
+   Blink objects that are not managed by Oilpan are allocated with
+   PartitionAlloc.
+ * **Skia**: (undocumented).
+ * **SQLite**: (undocumented).
+ * **V8**: (undocumented).
+ * **Web Cache**: (undocumented).
+
+The **tracing column in gray** reports memory that is used to collect all of the
+above information. This memory would not be used if tracing were not enabled.

[Primiano Tucci (use gerrit), 2016/01/18 15:45:28]

Add: and is properly discounted from both malloc and the resident (Blue) columns

[Ruud van Asseldonk, 2016/01/18 16:25:21]

Done.

+
+<!-- TODO(primiano): Improve this. https://crbug.com/??? -->
+
+[oilpan]:    /third_party/WebKit/Source/platform/heap/BlinkGCDesign.md
+[cc-memory]: /cc/memory.md
+[partalloc]: /third_party/WebKit/Source/wtf/PartitionAlloc.md
+
+To illustrate the difference between physical and virtual memory, consider the

[Primiano Tucci (use gerrit), 2016/01/18 15:45:28]

Remove this section about physical and virtual. I'd like people to not thing
about that.

[Ruud van Asseldonk, 2016/01/18 16:25:21]

Done.

+following example:
+
+```c
+size_t kPageSize = 4096;
+char* p = (char*)malloc(256 * kPageSize);
+for (size_t i = 0; i < kPageSize; ++i)
+  p[i] = 'X';
+```
+
+Here the malloc dumper would report that 1 MiB of virtual address space has been
+allocated, but only 1 KiB of that would be reported in the resident column. The
+rest of the memory is never touched, so the operating system does not need to
+back it by physical memory.
+
+## Rationale
+
+Another memory profiler? What is wrong with tool X?
+Most of the existing tools:
+
+ * Are hard to get working with Chrome. (Massive symbols, require OS-specific
+   tricks.)
+ * Lack Chrome-related context.
+ * Don't deal with multi-process scenarios.
+
+MemoryInfra leverages the existing tracing infrastructure in Chrome and provides
+contextual data:
+
+ * **It speaks Chrome slang.**
+   The Chromium codebase is instrumented. Its memory subsystems (allocators,
+   caches, etc.) uniformly report their stats into the trace in a way that can
+   be understood by Chrome developers. No more
+   `__gnu_cxx::new_allocator< std::_Rb_tree_node< std::pair< std::string const, base::Value*>>> ::allocate`.
+ * **Timeline data that can be correlated with other events.**
+   Did memory suddenly increase during a specific Blink / V8 / HTML parsing
+   event? Which subsystem increased? Did memory not go down as expected after
+   closing a tab? Which other threads were active during a bloat?
+ * **Works out of the box on desktop and mobile.**
+   No recompilations with unmaintained `GYP_DEFINES`, no time-consuming
+   symbolizations stages. All the logic is already into Chrome, ready to dump at
+   any time.
+ * **The same technology is used for telemetry and the ChromePerf dashboard.**
+   See [the slides][chromeperf-slides] and take a look at
+   [some ChromePerf dashboards][chromeperf].
+
+[chromeperf-slides]: https://docs.google.com/presentation/d/1OyxyT1sfg50lA36A7ibZ7-bBRXI1kVlvCW0W9qAmM_0/present?slide=id.gde150139b_0_137
+[chromeperf]:        https://chromeperf.appspot.com/report?sid=3b54e60c9951656574e19252fadeca846813afe04453c98a49136af4c8820b8d
+
+## Development
+
+MemoryInfra is based on a simple and extensible architecture. See
+[the slides][dp-slides] on how to get your subsystem reported in MemoryInfra,
+or take a look at one of the existing examples such as
+[malloc_dump_provider.cc][malloc-dp]. Don't hesitate to contact
+[tracing@chromium.org][mailtracing] for questions and support.
+
+[dp-slides]:   https://docs.google.com/presentation/d/1GI3HY3Mm5-Mvp6eZyVB0JiaJ-u3L1MMJeKHJg4lxjEI/present?slide=id.g995514d5c_1_45
+[malloc-dp]:   https://chromium.googlesource.com/chromium/src.git/+/master/base/trace_event/malloc_dump_provider.cc
+[mailtracing]: mailto:tracing@chromium.org
+
+Design documents:
+
+ * [Architectural](https://drive.google.com/a/google.com/embeddedfolderview?id=0B3KuDeqD-lVJfmp0cW1VcE5XVWNxZndxelV5T19kT2NFSndYZlNFbkFpc3pSa2VDN0hlMm8)

[Primiano Tucci (use gerrit), 2016/01/18 15:45:28]

Hmm I'd like you kept the <iframes> here, as reduce one level of indirection.

[Ruud van Asseldonk, 2016/01/18 16:25:21]

Done, so the one person who actually looks at these can reach them one click
faster ;)

+ * [Chrome-side design docs](https://drive.google.com/a/google.com/embeddedfolderview?id=0B3KuDeqD-lVJfndSa2dleUQtMnZDeWpPZk1JV0QtbVM5STkwWms4YThzQ0pGTmU1QU9kNVk)
+ * [Catapult-side design docs](https://drive.google.com/a/google.com/embeddedfolderview?id=0B3KuDeqD-lVJfm10bXd5YmRNWUpKOElOWS0xdU1tMmV1S3F4aHo0ZDJLTmtGRy1qVnQtVWM)