Update documentation on cobalt.dev

cobalt/site/docs/gen/cobalt/doc/cvals.md

@@ -123,6 +123,18 @@ Here are examples of its usage:
     compatibility violations encountered.
 *   **Count.XHR** - The total number of xhr::XMLHttpRequest in existence
     globally.
+*   **Count.MainWebModule.AnimatedImage.Active** - The total number of currently
+    active animated image decoders. Same image from a single URL source rendered
+    multiple times across the content counts as one decoder.
+*   **Count.MainWebModule.AnimatedImage.DecodedFrames** - Total number of decoded
+    frames across all active image decoders. This number resets only when
+    WebModule gets re-created - e.g. page reload, navigation.
+*   **Count.MainWebModule.AnimatedImage.DecodingUnderruns** - Total number of
+    frames when animated image decoding has fallen behind real-time, as defined
+    by image frame exposure times. This indicates a CPU bottleneck.
+*   **Count.MainWebModule.AnimatedImage.DecodingOverruns** - Total number of
+    frames when animated image decoding has been attempted too early, before
+    next frame exposure time. This indicates a timing issue in platform.
 
 ### Event
 
@@ -435,3 +447,17 @@ query):
     stopped playing animations.
 *   **Time.Renderer.Rasterize.NewRenderTree** - Time when the most recent render
     tree was first rasterized.
+
+### Starboard
+
+#### PublicCVals
+
+*   **Starboard.FileWrite.Success** - Count of successful file writes.
+*   **Starboard.FileWrite.Fail** - Count of failed file writes.
+*   **Starboard.FileWrite.BytesWritten** - Bytes written to file.
+*   **Starboard.StorageWriteRecord.Success** - Count of successful storage
+    record writes.
+*   **Starboard.StorageWriteRecord.Fail** - Count of failed storage record
+    writes.
+*   **Starboard.StorageWriteRecord.BytesWritten** - Bytes written to storage
+    record.

cobalt/site/docs/gen/starboard/doc/evergreen/cobalt_evergreen_overview.md

@@ -94,38 +94,46 @@ Evergreen](resources/cobalt_evergreen_overview_vs_non_evergreen.png)
 
 ### Building Cobalt Evergreen Components
 
-Cobalt Evergreen requires that there are two separate build(`gyp`)
-configurations used due to the separation of the Cobalt core(`libcobalt.so`) and
-the platform-specific Starboard layer(`loader_app`). As a result, you will have
-to initiate a separate gyp process for each. This is required since the Cobalt
-core binary is built with the Google toolchain settings and the
-platform-specific Starboard layer is built with partner toolchain
-configurations.
+Because of its separation of the Cobalt core (`libcobalt.so`) and platform-
+specific Starboard layers, Cobalt Evergreen requires two build configurations.
+This means there are two relevant GN platforms defined in the build code, and
+that `gn gen` must be run twice to generate ninja files for two separate
+platforms.
 
-Cobalt Evergreen is built by a separate gyp platform using the Google toolchain:
+#### Configuring your port for Evergreen
 
-```
-$ cobalt/build/gn.py -p evergreen-arm-softfp -c qa
-$ ninja -C out/evergreen-arm-softfp_qa cobalt
-```
+The Evergreen platforms for the different supported architectures, which are
+used to build Cobalt core (`libcobalt.so`), are maintained by Google. So, no
+changes are needed by the partner here.
 
-Which produces a shared library `libcobalt.so` targeted for specific
-architecture, ABI and Starboard version.
+However, a few small changes are needed in the partner's port, which is used to
+build the partner-built components, to make it compatible with Evergreen.
 
-The gyp variable `sb_evergreen` is set to 1 when building `libcobalt.so`.
+First, partners should set `sb_is_evergreen_compatible = true` in the platform's
+`platform_configuration/configuration.gni` file. (Please DO NOT set
+`sb_is_evergreen` to `true`, as this should only be set in the Evergreen
+platforms that are maintained by Google and used to build Cobalt core.)
 
-The partner port of Starboard is built with the partner’s toolchain and is
-linked into the `loader_app` which knows how to dynamically load
-`libcobalt.so`, and the `crashpad_handler` which handles crashes.
+Second, in the platform's `toolchain/BUILD.gn` file partners should copy their
+"target" toolchain to add a "native_target" toolchain that is identical except
+that it sets `is_starboard = false` and `is_native_target_build = true`.
+
+For example:
 
 ```
-$ cobalt/build/gn.py -p <partner_port_name> -c qa
-$ ninja -C out/<partner_port_name>_qa loader_app crashpad_handler
+gcc_toolchain("target") {
+  ...
+}
+
+gcc_toolchain("native_target") {
+  ...
+  is_starboard = false
+  is_native_target_build = true
+}
 ```
 
-Partners should set `sb_evergreen_compatible` to 1 in their gyp platform config.
-DO NOT set the `sb_evergreen` to 1 in your platform-specific configuration as it
-is used only by Cobalt when building with the Google toolchain.
+This "native_target" toolchain is required in order to build the
+`crashpad_handler` binary, which should NOT use the Starboard porting layer.
 
 Additionally, partners should install crash handlers as instructed in the
 [Installing Crash Handlers for Cobalt guide](../crash_handlers.md).
@@ -135,7 +143,7 @@ Evergreen:
 
 *   `kSbSystemPathStorageDirectory`
     *   Dedicated location for storing Cobalt Evergreen-related binaries
-    *   This path must be writable and have at least 96MB of reserved space for
+    *   This path must be writable and have at least 64MB of reserved space for
         Evergreen updates. Please see the “Platforms Requirements” section below
         for more details.
 *   `kSbMemoryMapProtectExec`
@@ -156,7 +164,36 @@ your platform unless it is not one of our supported architectures:
 If your target architecture falls outside the support list above, please reach
 out to us for guidance.
 
-#### Adding Crash Handlers to Evergreen
+#### Build commands
+
+As mentioned, the Google-maintained Evergreen toolchain is used to build Cobalt
+core (`libcobalt.so`). For example:
+
+```
+$ gn gen out/evergreen-arm-softfp_qa --args="target_platform=\"evergreen-arm-softfp\" build_type=\"qa\" target_cpu=\"arm\" target_os=\"linux\" sb_api_version=15"
+$ ninja -C out/evergreen-arm-softfp_qa cobalt_install
+```
+
+This produces a `libcobalt.so` shared library targeted for a specific
+architecture, ABI, and Starboard version.
+
+Note: `sb_api_version` defaults to the latest supported Starboard version in the
+current branch.
+
+
+The partner port of Starboard is built with the partner’s "target" toolchain and
+is linked into the `loader_app`, which knows how to dynamically load
+`libcobalt.so`. And the `crashpad_handler` binary is built with the partner's
+"native_target" toolchain. For example:
+
+```
+$ gn gen out/<partner_port_name>_qa --args='target_platform="<partner_port_name>" build_type="qa" sb_api_version=15'
+$ ninja -C out/<partner_port_name>_qa loader_app
+$ ninja -C out/<partner_port_name>_qa native_target/crashpad_handler
+```
+
+Note that when building `crashpad_handler`, a special prefix is used to have
+Ninja compile the target in the non-default, "native_target" toolchain.
 
 ### What is an example for how this would help me?
 
@@ -199,12 +236,12 @@ Supported Javascript Engines
 
 *   V8
 
-Additional reserved storage (96MB) is required for Evergreen binaries. We expect
+Additional reserved storage (64MB) is required for Evergreen binaries. We expect
 Evergreen implementations to have an initial Cobalt preloaded on the device and
 an additional reserved space for additional Cobalt update storage.
 
 *   Initial Cobalt binary deployment - 64MB
-*   Additional Cobalt update storage - 96MB
+*   Additional Cobalt update storage - 64MB
     *   Required for 2 update slots under `kSbSystemPathStorageDirectory`
 
 As Cobalt Evergreen is intended to be updated from Google Cloud architecture

cobalt/site/docs/reference/starboard/modules/13/event.md

@@ -159,8 +159,7 @@ the type of the value pointed to by that data argument, if any.
 *   `kSbEventTypeUser`
 
     A user change event, which means a new user signed-in or signed-out, or the
-    current user changed. No data argument, call SbUserGetSignedIn() and
-    SbUserGetCurrent() to get the latest changes.
+    current user changed. No data argument.
 *   `kSbEventTypeLink`
 
     A navigational link has come from the system, and the application should

cobalt/site/docs/reference/starboard/modules/13/memory.md

@@ -125,8 +125,7 @@ void* SbMemoryAllocateChecked(size_t size)
 
 ### SbMemoryAllocateNoReport ###
 
-Same as SbMemoryAllocate() but will not report memory to the tracker. Avoid
-using this unless absolutely necessary.
+DEPRECATED: Same as SbMemoryAllocate().
 
 #### Declaration ####
 
@@ -185,8 +184,7 @@ void SbMemoryDeallocateAligned(void *memory)
 
 ### SbMemoryDeallocateNoReport ###
 
-Same as SbMemoryDeallocate() but will not report memory deallocation to the
-tracker. This function must be matched with SbMemoryAllocateNoReport().
+DEPRECATED: Same as SbMemoryDeallocate()
 
 #### Declaration ####
 

cobalt/site/docs/reference/starboard/modules/13/memory_reporter.md

@@ -3,7 +3,7 @@ layout: doc
 title: "Starboard Module Reference: memory_reporter.h"
 ---
 
-Provides an interface for memory reporting.
+DEPRECATED: Provides an interface for memory reporting.
 
 ## Typedefs ##
 
@@ -84,6 +84,9 @@ context };
 Sets the MemoryReporter. Any previous memory reporter is unset. No lifetime
 management is done internally on input pointer.
 
+NOTE: This module is unused starting with Starboard 15 and will be removed in
+the future.
+
 Returns true if the memory reporter was set with no errors. If an error was
 reported then check the log for why it failed.
 

cobalt/site/docs/reference/starboard/modules/13/storage.md

@@ -3,14 +3,14 @@ layout: doc
 title: "Starboard Module Reference: storage.h"
 ---
 
-Defines a user-based Storage API. This is a simple, all-at-once BLOB storage and
-retrieval API that is intended for robust long-term, per-user storage. Some
-platforms have different mechanisms for this kind of storage, so this API exists
-to allow a client application to access this kind of storage.
-
-Note that there can be only one storage record per user and, thus, a maximum of
-one open storage record can exist for each user. Attempting to open a second
-record for a user will result in undefined behavior.
+Defines a Storage API. This is a simple, all-at-once BLOB storage and retrieval
+API that is intended for robust long-term storage. Some platforms have different
+mechanisms for this kind of storage, so this API exists to allow a client
+application to access this kind of storage.
+
+Note that there can be only one storage record and, thus, a maximum of one open
+storage record can exist. Attempting to open a second record will result in
+undefined behavior.
 
 These APIs are NOT expected to be thread-safe, so either call them from a single
 thread, or perform proper synchronization around all calls.

cobalt/site/docs/reference/starboard/modules/14/event.md

@@ -159,8 +159,7 @@ the type of the value pointed to by that data argument, if any.
 *   `kSbEventTypeUser`
 
     A user change event, which means a new user signed-in or signed-out, or the
-    current user changed. No data argument, call SbUserGetSignedIn() and
-    SbUserGetCurrent() to get the latest changes.
+    current user changed. No data argument.
 *   `kSbEventTypeLink`
 
     A navigational link has come from the system, and the application should

cobalt/site/docs/reference/starboard/modules/14/memory.md

@@ -125,8 +125,7 @@ void* SbMemoryAllocateChecked(size_t size)
 
 ### SbMemoryAllocateNoReport ###
 
-Same as SbMemoryAllocate() but will not report memory to the tracker. Avoid
-using this unless absolutely necessary.
+DEPRECATED: Same as SbMemoryAllocate().
 
 #### Declaration ####
 
@@ -185,8 +184,7 @@ void SbMemoryDeallocateAligned(void *memory)
 
 ### SbMemoryDeallocateNoReport ###
 
-Same as SbMemoryDeallocate() but will not report memory deallocation to the
-tracker. This function must be matched with SbMemoryAllocateNoReport().
+DEPRECATED: Same as SbMemoryDeallocate()
 
 #### Declaration ####
 

cobalt/site/docs/reference/starboard/modules/14/memory_reporter.md

@@ -3,7 +3,7 @@ layout: doc
 title: "Starboard Module Reference: memory_reporter.h"
 ---
 
-Provides an interface for memory reporting.
+DEPRECATED: Provides an interface for memory reporting.
 
 ## Typedefs ##
 
@@ -84,6 +84,9 @@ context };
 Sets the MemoryReporter. Any previous memory reporter is unset. No lifetime
 management is done internally on input pointer.
 
+NOTE: This module is unused starting with Starboard 15 and will be removed in
+the future.
+
 Returns true if the memory reporter was set with no errors. If an error was
 reported then check the log for why it failed.
 

cobalt/site/docs/reference/starboard/modules/14/storage.md

@@ -3,14 +3,14 @@ layout: doc
 title: "Starboard Module Reference: storage.h"
 ---
 
-Defines a user-based Storage API. This is a simple, all-at-once BLOB storage and
-retrieval API that is intended for robust long-term, per-user storage. Some
-platforms have different mechanisms for this kind of storage, so this API exists
-to allow a client application to access this kind of storage.
-
-Note that there can be only one storage record per user and, thus, a maximum of
-one open storage record can exist for each user. Attempting to open a second
-record for a user will result in undefined behavior.
+Defines a Storage API. This is a simple, all-at-once BLOB storage and retrieval
+API that is intended for robust long-term storage. Some platforms have different
+mechanisms for this kind of storage, so this API exists to allow a client
+application to access this kind of storage.
+
+Note that there can be only one storage record and, thus, a maximum of one open
+storage record can exist. Attempting to open a second record will result in
+undefined behavior.
 
 These APIs are NOT expected to be thread-safe, so either call them from a single
 thread, or perform proper synchronization around all calls.

cobalt/site/docs/reference/starboard/modules/15/event.md

@@ -159,8 +159,7 @@ the type of the value pointed to by that data argument, if any.
 *   `kSbEventTypeUser`
 
     A user change event, which means a new user signed-in or signed-out, or the
-    current user changed. No data argument, call SbUserGetSignedIn() and
-    SbUserGetCurrent() to get the latest changes.
+    current user changed. No data argument.
 *   `kSbEventTypeLink`
 
     A navigational link has come from the system, and the application should

cobalt/site/docs/reference/starboard/modules/15/memory.md

@@ -125,8 +125,7 @@ void* SbMemoryAllocateChecked(size_t size)
 
 ### SbMemoryAllocateNoReport ###
 
-Same as SbMemoryAllocate() but will not report memory to the tracker. Avoid
-using this unless absolutely necessary.
+DEPRECATED: Same as SbMemoryAllocate().
 
 #### Declaration ####
 
@@ -185,8 +184,7 @@ void SbMemoryDeallocateAligned(void *memory)
 
 ### SbMemoryDeallocateNoReport ###
 
-Same as SbMemoryDeallocate() but will not report memory deallocation to the
-tracker. This function must be matched with SbMemoryAllocateNoReport().
+DEPRECATED: Same as SbMemoryDeallocate()
 
 #### Declaration ####
 

cobalt/site/docs/reference/starboard/modules/15/memory_reporter.md

@@ -3,7 +3,7 @@ layout: doc
 title: "Starboard Module Reference: memory_reporter.h"
 ---
 
-Provides an interface for memory reporting.
+DEPRECATED: Provides an interface for memory reporting.
 
 ## Typedefs ##
 
@@ -84,6 +84,9 @@ context };
 Sets the MemoryReporter. Any previous memory reporter is unset. No lifetime
 management is done internally on input pointer.
 
+NOTE: This module is unused starting with Starboard 15 and will be removed in
+the future.
+
 Returns true if the memory reporter was set with no errors. If an error was
 reported then check the log for why it failed.
 

cobalt/site/docs/reference/starboard/modules/15/storage.md

@@ -3,14 +3,14 @@ layout: doc
 title: "Starboard Module Reference: storage.h"
 ---
 
-Defines a user-based Storage API. This is a simple, all-at-once BLOB storage and
-retrieval API that is intended for robust long-term, per-user storage. Some
-platforms have different mechanisms for this kind of storage, so this API exists
-to allow a client application to access this kind of storage.
-
-Note that there can be only one storage record per user and, thus, a maximum of
-one open storage record can exist for each user. Attempting to open a second
-record for a user will result in undefined behavior.
+Defines a Storage API. This is a simple, all-at-once BLOB storage and retrieval
+API that is intended for robust long-term storage. Some platforms have different
+mechanisms for this kind of storage, so this API exists to allow a client
+application to access this kind of storage.
+
+Note that there can be only one storage record and, thus, a maximum of one open
+storage record can exist. Attempting to open a second record will result in
+undefined behavior.
 
 These APIs are NOT expected to be thread-safe, so either call them from a single
 thread, or perform proper synchronization around all calls.