blob: da5f972aa63847ffa2464ef5e6bd0db43a61f14b [file] [log] [blame] [view]
# Memory Tuning #
Cobalt is designed to choose sensible parameters for memory-related options and
parameters through a system called "AutoMem".
On startup, AutoMem will print a memory table to the output console detailing
the memory allocations that will be assigned to the various subsystems in
cobalt.
As an example, at the cost of performance you can reduce CPU memory on your
platform by 5MB and GPU memory usage on your platform by 10MB using these
command line flags:
`cobalt --reduce_cpu_memory_by=5MB --reduce_gpu_memory_by=10MB`
Some settings will be "fixed" while others will be "flexible" so that their
memory consumption will scale down for memory constrained platforms.
Read on for more information.
**IMPORTANT**
*Setting `--max_cobalt_cpu_usage` and `--max_cobalt_gpu_usage` on the
command line is a beta feature. When reducing memory, please use
`--reduce_cpu_memory_by` and `--reduce_gpu_memory_by`.*
### Memory Settings Table ###
A table similar to the one below, will be printed on startup.
~~~
AutoMem:
SETTING NAME VALUE TYPE SOURCE
________________________________________________________________________________
| | | | | |
| image_cache_size_in_bytes | 33554432 | 32.0 MB | GPU | AutoSet |
|______________________________________|_____________|__________|______|_________|
| | | | | |
| javascript_gc_threshold_in_bytes | 8388608 | 8.0 MB | CPU | Build |
|______________________________________|_____________|__________|______|_________|
| | | | | |
| misc_cobalt_cpu_size_in_bytes | 124780544 | 119.0 MB | CPU | AutoSet |
|______________________________________|_____________|__________|______|_________|
| | | | | |
| misc_cobalt_gpu_size_in_bytes | 25165824 | 24.0 MB | GPU | AutoSet |
|______________________________________|_____________|__________|______|_________|
| | | | | |
| remote_typeface_cache_size_in_bytes | 4194304 | 4.0 MB | CPU | Build |
|______________________________________|_____________|__________|______|_________|
| | | | | |
| skia_atlas_texture_dimensions | 4096x8192x2 | 64.0 MB | GPU | Build |
|______________________________________|_____________|__________|______|_________|
| | | | | |
| skia_cache_size_in_bytes | 4194304 | 4.0 MB | GPU | Build |
|______________________________________|_____________|__________|______|_________|
| | | | | |
| software_surface_cache_size_in_bytes | N/A | N/A | N/A | N/A |
|______________________________________|_____________|__________|______|_________|
~~~
This table shows the breakdown of how much memory is being allocated to each
sub-system, the type, and where it came from.
**SETTING NAME:** This is the name of the memory setting. If a setting can be
manually set through the command line or the build system, then it will be
accessible by using this name. For example adding the command line argument
`--image_cache_size_in_bytes=25165824` will manually set the Image Cache Size to
24 megabytes. Also note that this is also equivalent:
`--image_cache_size_in_bytes=24MB`. Note that the numerical value can include
the suffix kb/mb/gb to specify kilo/mega/giga-bytes. The numerical value can
be a floating point value. For example `--image_cache_size_in_bytes=.1GB` is
equivalent to `--image_cache_size_in_bytes=100MB`.
**VALUE:** This two column value has a first setting that describes what the
actual value is, and the second column is the amount of memory that the setting
consumes. This first setting gives hints on what kind of values the
setting can be set to via the command line. For example,
`skia_atlas_texture_dimensions` accepts texture sizes on the command line, such
as: `--skia_atlas_texture_dimensions=2048x4096x2`
**TYPE:** This specifies whether the setting consumes GPU or CPU memory.
For example, the Image Cache will decode images to buffers to the GPU memory
and therefore it is the classified as the GPU memory type.
**SOURCE:** This specifies where the memory setting came from. It will either
be set from a specific place or automatically generated from Cobalt.
* Values for **SOURCE**:
* `Starboard API`
* The value used was reported by the result of a Starboard API function call.
* Example: `SbSystemGetUsedCPUMemory()`
* `Build`
* Specified by the platform specific `*.gyp(i)` build file.
* For example: see `image_cache_size_in_bytes` in [`build/config/base.gypi`](../build/config/base.gypi)
* `CmdLine`
* Read the memory setting value from the command line.
* For example: `cobalt --image_cache_size_in_bytes=24MB`.
* `AutoSet`
* No value was specified and therefore Cobalt calculated the default value
automatically based on system parameters. For example many caches
will be chosen proportionally to the size of the UI resolution.
* `AutoSet (Constrained)`
* This value was AutoSet to a default value, but then was reduced in
response to `max_cobalt_cpu_usage` or `max_cobalt_gpu_usage being` set too low.
This will also trigger in response to `reduce_cpu_memory_by` or
`reduce_cpu_memory_by` being set. See "Memory Scaling" section below.
### Maximum Memory Table ###
This second table is also printed at startup and details the sum of memory and
maximum memory limits as reported by cobalt.
~~~
MEMORY SOURCE TOTAL SETTINGS CONSUME
____________________________________________________________________
| | | | |
| max_cobalt_cpu_usage | Starboard API | 256.0 MB | 131.0 MB |
|______________________|_______________|__________|__________________|
| | | | |
| max_cobalt_gpu_usage | Starboard API | 768.0 MB | 124.0 MB |
|______________________|_______________|__________|__________________|
~~~
This table shows the limits for CPU and GPU memory consumption and also how
much memory is being consumed for each memory type.
**MEMORY**: This is the name of the memory limit. If you want to change this
setting manually then use the name on the command line. For example
`--max_cobalt_cpu_usage=150MB` will set Cobalt to 150MB limit for CPU
memory. If the sum of CPU memory exceeds this limit then memory settings of the
same type will reduce their memory usage.
**SOURCE**: This value indicates where the value came from.
* `Starboard API`
* `max_cobalt_cpu_usage`: This value was found from SbSystemGetTotalCPUMemory().
* `max_cobalt_gpu_usage`: This value was found from SbSystemGetTotalGPUMemory().
* `CmdLine`
* `max_cobalt_cpu_usage`: --max_cobalt_cpu_usage was used as a command argument.
* `max_cobalt_gpu_usage`: --max_cobalt_gpu_usage was used as a command argument.
* `Build`
* `max_cobalt_cpu_usage`: max_cobalt_cpu_usage was specified in a platform gyp file.
* `max_cobalt_gpu_usage`: max_cobalt_gpu_usage was specified in a platform gyp file.
**TOTAL**: Represents the maximum available memory for settings. This value
came from **SOURCE**.
**SETTINGS CONSUME**: This value indicates the consumption of memory for the
current memory type.
For `max_cobalt_cpu_usage`, `Starboard API` indicates that this value came from
`SbSystemGetTotalCPUMemory()` If this source value is `Starboard API` then this
value came from `SbSystemGetTotalCPUMemory()` (for CPU) or
`SbSystemGetTotalGPUMemory()` for GPU).
If the available memory for the Cobalt is less than the amount of memory
consumed by the settings, then any settings that are AutoSet AND adjustable
will reduce their memory consumption. When this happens, look for the string
*`AutoSet (Constrained)`* in the first table.
## Setting Maximum Memory Values ##
The max cpu and gpu memory of the system can be set either by command line or
by modifying the gyp build file.
Command Line:
* `--max_cobalt_cpu_usage=160MB`
* `--max_cobalt_gpu_usage=160MB`
Build settings:
* `starboard/<PLATFORM>/gyp_configuration.gypi`
* `max_cobalt_cpu_usage`
* `max_cobalt_gpu_usage`
Command Line settings will override build settings.
### Memory Scaling ###
There are two primary ways in which the memory consumption settings will scale down.
One is by specifying `--max_cobalt_cpu_usage` (or `max_cobalt_gpu_usage`) to a
particular value (e.g. `--max_cobalt_cpu_usage=160MB`).
`--max_cobalt_cpu_usage` (and `--max_cobalt_gpu_usage`) will trigger the memory
to scale down whenever the memory settings memory consumption exceed the maximum
**TOTAL** value. The memory settings will be scaled down until their consumption is
less than or equal the maximum allowed value **TOTAL**. See also **SETTINGS CONSUME**.
Another way to scale down the memory size is by passing the flags
`--reduce_cpu_memory_by=XX` and `--reduce_gpu_memory_by=XX` which will:
1) Ignore the `--max_cobalt_cpu_usage` and `--max_cobalt_gpu_usage`.
2) Use the current memory consumption of the settings and then reduce that by
the amount.
For example, if cobalt uses 160MB of CPU memory then passing in
`--reduce_cpu_memory_by=10MB` to the command line will attempt to reduce the
footprint of cobalt by 10MB to 150MB. Note that this reduction is an an attempt,
and it's possible this attempt will fail if the memory reduction is too aggressive
or if memory settings have been explicitly set via the build or command line.
*Forcing a Memory Setting to be flexible*
If a memory setting is set via a build setting, then it's possible to make it
flexible via the command line by setting the value to "autoset". For example,
`--image_cache_size_in_bytes=auto` will allow `image_cache_size_in_bytes` to be
flexible by disabling the value being set by a build setting.
### Memory Warnings ###
Cobalt will periodically check to see if the memory consumed by the application
is less than the `--max_cobalt_cpu_usage` and `--max_cobalt_gpu_usage` amount.
If the cpu/gpu exceeds this maximum value then an error message will be logged
once to stdout for cpu and/or gpu memory systems.
### Example 1 - Configuring for a memory restricted platform ###
Let's say that we are configuring platform called "XXX":
We will configure XXX such that:
* `image_cache_size_in_bytes` will be set to 32MB in the build settings.
* `skia_atlas_texture_dimensions` will be set to `2048x2048x2` in the build settings.
* `max_cobalt_cpu_usage` will be set to 160MB on the command line.
**Configuring `image_cache_size_in_bytes` to be 32MB:**
* in `starboard\<PLATFORM>\gyp_configuration.gypi`
* add `'image_cache_size_in_bytes': 32 * 1024 * 1024,`
**Configuring `skia_atlas_texture_dimensions` to be 2048x2048x2:**
* in `src\starboard\XXX\gyp_configuration.gypi`
* add `'skia_glyph_atlas_width': '2048'`
* add `'skia_glyph_atlas_height': '2048'`
* (note that the third dimension is assumed)
**Configuring `max_cobalt_cpu_usage` to be 160MB:**
* `cobalt --max_cobalt_cpu_usage=160MB`
### Example 2 - Configuring for a memory-plentiful platform ###
The following command line will give a lot of memory to image cache and give
500MB to `max_cobalt_cpu_usage` and `max_cobalt_gpu_usage`.
~~~
cobalt --max_cobalt_cpu_usage=500MB --max_cobalt_gpu_usage=500MB
--image_cache_size_in_bytes=80MB
~~~
## API Reference ##
#### Memory System API ####
* `max_cobalt_cpu_usage`
* This setting will set the maximum cpu memory that the app will consume.
CPU Memory settings will scale down their consumption in order to stay under
the `max_cobalt_cpu_usage`. If memory consumption exceeds this value during
runtime then a memory warning will be printed to stdout.
* Set via command line or else build system or else starboard.
* starboard value will bind to `SbSystemGetTotalCPUMemory()`.
* `max_cobalt_gpu_usage`
* This setting will set the maximum gpu memory that the app will consume.
GPU Memory settings will scale down their consumption in order to stay under
the `max_cobalt_gpu_usage`. If memory consumption exceeds this value during
runtime then a memory warning will be printed to stdout.
* Set via command line or else build system or else starboard.
* starboard value will bind to `SbSystemGetTotalGPUMemory()`.
* Note that `SbSystemGetTotalGPUMemory()` is optional. If no value exists
for `max_cobalt_gpu_usage` in build/commandline/starboard settings then no
GPU memory checking is performed.
* `reduce_cpu_memory_by`
* This setting will trigger CPU memory consumption to be reduced by the amount
specified. *This overrides the memory scaling behavior of `max_cobalt_cpu_usage`*.
But this will not affect memory checking of `max_cobalt_cpu_usage` otherwise.
* Set via command line or else the platform gyp build file.
* `reduce_cpu_memory_by`
* This setting will trigger GPU memory consumption to be reduced by the amount
specified. *This overrides the memory scaling behavior of `max_cobalt_gpu_usage`*.
But this will not affect memory checking of `max_cobalt_gpu_usage` otherwise.
* Set via command line or else the platform gyp build file.
#### Memory Setting API ####
* `image_cache_size_in_bytes`
* See documentation *Image cache capacity* in `performance_tuning.md` for what
this setting does.
* Set via command line, or else build system, or else automatically by Cobalt.
* `javascript_gc_threshold_in_bytes`
* See documentation *Garbage collection trigger threshold* in `performance_tuning.md`
for what this setting does.
* Set via command line, or else build system, or else automatically by Cobalt.
* `remote_typeface_cache_size_in_bytes`
* Determines the capacity of the remote typefaces cache which manages all typefaces
downloaded from a web page.
* Set via command line, or else build system, or else automatically by Cobalt.
* `skia_atlas_texture_dimensions`
* Determines the size in pixels of the glyph atlas where rendered glyphs are
cached. The resulting memory usage is 2 bytes of GPU memory per pixel.
When a value is used that is too small, thrashing may occur that will
result in visible stutter. Such thrashing is more likely to occur when CJK
language glyphs are rendered and when the size of the glyphs in pixels is
larger, such as for higher resolution displays.
The negative default values indicates to the Cobalt that these settings
should be automatically set.
* Set via command line, or else build system, or else automatically by Cobalt.
* Note that in the gyp build system, this setting is represented as two values:
* `skia_glyph_atlas_width` and
* `skia_glyph_atlas_height`
* `skia_cache_size_in_bytes`
* See documentation *Glyph atlas size* in `performance_tuning.md` for what this
setting does.
* Set via command line, or else build system or else automatically by Cobalt.
* `software_surface_cache_size_in_bytes`
* See documentation *Scratch Surface cache capacity* in `performance_tuning.md`
for what this setting does.
* Set via command line, or else build system, or else automatically by Cobalt.
#### Units for Command Line Settings ####
Memory values passed into Cobalt via command line arguments support units such
kb, mb, and gb for kilo-byte, megabyte, gigabytes. These units are case insensitive.
For example, these are all equivalent on the command line:
`--image_cache_size_in_bytes=67108864`
`--image_cache_size_in_bytes=65536kb`
`--image_cache_size_in_bytes=64mb`
`--image_cache_size_in_bytes=.0625gb`