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.

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
    • 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