Add doc explaining CC memory usage.

BUG=542400
CQ_INCLUDE_TRYBOTS=tryserver.blink:linux_blink_rel

Review URL: https://codereview.chromium.org/1507553004

Cr-Commit-Position: refs/heads/master@{#363923}

1 files changed, 125 insertions, 0 deletions

diff --git a/cc/memory.md b/cc/memory.md
new file mode 100644
index 0000000..1bac0f5
--- /dev/null
+++ b/cc/memory.md
@@ -0,0 +1,125 @@
+# Memory Usage in CC
+
+This document gives an overview of memory usage in the CC component, as well as
+information on how to analyze that memory.
+
+[TOC]
+
+## Types of Memory in Use
+
+CC uses a number of types of memory:
+
+1.  Malloc Memory - Standard system memory used for all manner of objects in CC.
+2.  Discardable Memory - Memory allocated by the discardable memory system.
+    Designed to be freeable by the system at any time (under memory pressure).
+    In most cases, only pinned discardable memory should be considered to
+    have a cost; however, the implementation of discardable memory is platform
+    dependent, and on certain platforms unpinned memory can contribute to
+    memory pressure to some degree.
+3.  Shared Memory - Memory which is allocated by the Browser and can safely
+    be transferred between processes. This memory is allocated by the browser
+    but may count against a renderer process depending on who logically "owns"
+    the memory.
+4.  GPU Memory - Memory which is allocated on the GPU and typically does not
+    count against system memory. This mainly includes OpenGL objects.
+
+## Categories Of Memory
+
+Memory-infra tracing will grab dumps of CC memory in several categories.
+
+### CC Category
+
+The CC category contains resource allocations made by ResourceProvider. All
+resource allocations are enumerated under cc/resource_memory. A subset of
+resources are used as tile memory, and are also enumerated under cc/tile_memory.
+For resources that appear in both cc/tile_memory and cc/resource_memory, the
+size will be attributed to cc/tile_memory (effective_size of cc/resource_memory
+will not include these resources).
+
+If the one-copy tile update path is in use, the cc category will also enumerate
+staging resources used as intermediates when drawing tiles. These resources are
+like tile_memory, in that they are shared with cc/resource_memory.
+
+Note that depending on the path being used, CC memory may be either shared
+memory or GPU memory:
+
+Path         | Tile Memory Type     | Staging Memory Type
+-------------|-------------------------------------------
+Bitmap       | Shared Memory        | N/A
+One Copy     | GPU Memory           | Shared Memory
+Zero Copy    | GPU or Shared Memory | N/A
+GPU          | GPU Memory           | N/A
+
+Note that these values can be determined from a memory-infra dump. For a given
+resource, hover over the small green arrow next to it's "size". This will show
+the other allocations that this resource is aliased with. If you see an
+allocation in the GPU process, the memory is generally GPU memory. Otherwise,
+the resource is typically Shared Memory.
+
+Tile and Staging memory managers are set up to evict any resource not used
+within 1s.
+
+### GPU Category
+
+This category lists the memory allocations needed to support CC's GPU path.
+Despite the name, the data in this category (within a Renderer process) is not
+GPU memory but Shared Memory.
+
+Allocations tracked here include GL command buffer support allocations such as:
+
+1.  Command Buffer Memory - memory used to send commands across the GL command
+    buffer. This is backed by Shared Memory.
+2.  Mapped Memory - memory used in certain image upload paths to share data
+    with the GPU process. This is backed by Shared Memory.
+3.  Transfer Buffer Memory - memory used to transfer data to the GPU - used in
+    different paths than mapped memory. Also backed by Shared Memory.
+
+### Discardable Category
+
+Cached images make use of Discardable memory. These allocations are managed by
+Skia and a better summary of these allocations can likely be found in the Skia
+category.
+
+### Malloc Category
+
+The malloc category shows a summary of all memory allocated through malloc.
+
+Currently the information here is not granular enough to be useful, and a
+good project would be to track down and instrument any large pools of memory
+using malloc.
+
+Some Skia caches also make use of malloc memory. For these allocations, a better
+summary can be seen in the Skia category.
+
+### Skia Category
+
+The Skia category shows all resources used by the Skia rendering system. These
+can be divided into a few subcategories. skia/gpu_resources/* includes all
+resources using GPU memory. All other categories draw from either Shared or
+malloc memory. To determine which type of memory a resource is using, hover
+over the green arrow next to its size. This will show the other allocations
+which the resource is aliased with.
+
+## Other Areas of Interest
+
+Many of the allocations under CC are aliased with memory in the Browser or GPU
+process. When investigating CC memory it may be worth looking at the following
+external categories:
+
+1.  GPU Process / GPU Category - All GPU resources allocated by CC have a
+    counterpart in the GPU/GPU category. This includes GL Textures, buffers, and
+    other GPU backed objects such as Native GPU Memory Buffers.
+2.  Browser Process / GpuMemoryBuffer Category - Resources backed by Shared
+    Memory GpuMemoryBuffers are allocated by the browser and will be tracked
+    in this category.
+3.  Browser Process / SharedMemory Category - Resources backed by Bitmap and
+    Shared Memory GpuMemoryBuffer objects are allocated by the browser and will
+    also tracked in this category.
+
+## Memory TODOs
+
+The following areas have insufficient memory instrumentation.
+
+1.  DisplayLists - DisplayLists can be quite large and are currently
+    un-instrumented. These use malloc memory and currently contribute to
+    malloc/allocated_objects/<unspecified>. [BUG](crbug.com/567465)