From 721548bab1ecc842b7ee7b4783116f9e81728033 Mon Sep 17 00:00:00 2001 From: Oscar Vestlie Date: Wed, 30 Aug 2023 14:49:29 -0700 Subject: [PATCH 1/2] Update documentation on cobalt.dev with changes since the last update. b/297516260 --- cobalt/site/docs/gen/cobalt/doc/cvals.md | 26 ++++ .../evergreen/cobalt_evergreen_overview.md | 91 ++++++++---- .../reference/starboard/gn-configuration.md | 1 + .../reference/starboard/modules/13/event.md | 3 +- .../reference/starboard/modules/13/memory.md | 6 +- .../starboard/modules/13/memory_reporter.md | 5 +- .../reference/starboard/modules/13/storage.md | 16 +-- .../reference/starboard/modules/14/event.md | 3 +- .../reference/starboard/modules/14/memory.md | 6 +- .../starboard/modules/14/memory_reporter.md | 5 +- .../reference/starboard/modules/14/storage.md | 16 +-- .../reference/starboard/modules/15/event.md | 3 +- .../reference/starboard/modules/15/memory.md | 6 +- .../starboard/modules/15/memory_reporter.md | 5 +- .../reference/starboard/modules/15/storage.md | 16 +-- .../reference/starboard/modules/byte_swap.md | 75 ++++++++++ .../modules/configuration_constants.md | 4 + .../reference/starboard/modules/memory.md | 6 +- .../starboard/modules/memory_reporter.md | 5 +- .../reference/starboard/modules/storage.md | 37 ++--- .../docs/reference/starboard/modules/user.md | 133 ++++++++++++++++++ 21 files changed, 374 insertions(+), 94 deletions(-) create mode 100644 cobalt/site/docs/reference/starboard/modules/byte_swap.md create mode 100644 cobalt/site/docs/reference/starboard/modules/user.md diff --git a/cobalt/site/docs/gen/cobalt/doc/cvals.md b/cobalt/site/docs/gen/cobalt/doc/cvals.md index 665c6a17f13e..8f50772b1ec0 100644 --- a/cobalt/site/docs/gen/cobalt/doc/cvals.md +++ b/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. diff --git a/cobalt/site/docs/gen/starboard/doc/evergreen/cobalt_evergreen_overview.md b/cobalt/site/docs/gen/starboard/doc/evergreen/cobalt_evergreen_overview.md index 98de330fa0e5..9ef512b16f8c 100644 --- a/cobalt/site/docs/gen/starboard/doc/evergreen/cobalt_evergreen_overview.md +++ b/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 -c qa -$ ninja -C out/_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/_qa --args='target_platform="" build_type="qa" sb_api_version=15' +$ ninja -C out/_qa loader_app +$ ninja -C out/_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 diff --git a/cobalt/site/docs/reference/starboard/gn-configuration.md b/cobalt/site/docs/reference/starboard/gn-configuration.md index 18db1eea7eea..f4572b913bae 100644 --- a/cobalt/site/docs/reference/starboard/gn-configuration.md +++ b/cobalt/site/docs/reference/starboard/gn-configuration.md @@ -35,6 +35,7 @@ title: "Starboard: configuration.gni Reference Guide" | **`sb_filter_based_player`**

Used to indicate that the player is filter based.

The default value is `true`. | | **`sb_is_evergreen`**

Whether this is an Evergreen build.

The default value is `false`. | | **`sb_is_evergreen_compatible`**

Whether this is an Evergreen compatible platform. A compatible platform can run the elf_loader and launch the Evergreen build.

The default value is `false`. | +| **`sb_is_modular`**

Whether this is a modular build.

The default value is `false`. | | **`sb_libevent_method`**

The event polling mechanism available on this platform to support libevent. Platforms may redefine to 'poll' if necessary. Other mechanisms, e.g. devpoll, kqueue, select, are not yet supported.

The default value is `"epoll"`. | | **`sb_static_contents_output_data_dir`**

Directory path to static contents' data.

The default value is `"/project_out_dir/content/data"`. | | **`sb_use_no_rtti`**

Whether or not to disable run-time type information (adding no_rtti flag).

The default value is `false`. | diff --git a/cobalt/site/docs/reference/starboard/modules/13/event.md b/cobalt/site/docs/reference/starboard/modules/13/event.md index 01a9d24cadbf..5a30f4b2e8c3 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/event.md +++ b/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 diff --git a/cobalt/site/docs/reference/starboard/modules/13/memory.md b/cobalt/site/docs/reference/starboard/modules/13/memory.md index a094a66ff135..b094aa59a374 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/memory.md +++ b/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 #### diff --git a/cobalt/site/docs/reference/starboard/modules/13/memory_reporter.md b/cobalt/site/docs/reference/starboard/modules/13/memory_reporter.md index d67ef1aada3e..5e49693e70bc 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/memory_reporter.md +++ b/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. diff --git a/cobalt/site/docs/reference/starboard/modules/13/storage.md b/cobalt/site/docs/reference/starboard/modules/13/storage.md index db7e9509bd2b..1c08ed71b8eb 100644 --- a/cobalt/site/docs/reference/starboard/modules/13/storage.md +++ b/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. diff --git a/cobalt/site/docs/reference/starboard/modules/14/event.md b/cobalt/site/docs/reference/starboard/modules/14/event.md index 01a9d24cadbf..5a30f4b2e8c3 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/event.md +++ b/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 diff --git a/cobalt/site/docs/reference/starboard/modules/14/memory.md b/cobalt/site/docs/reference/starboard/modules/14/memory.md index a094a66ff135..b094aa59a374 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/memory.md +++ b/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 #### diff --git a/cobalt/site/docs/reference/starboard/modules/14/memory_reporter.md b/cobalt/site/docs/reference/starboard/modules/14/memory_reporter.md index d67ef1aada3e..5e49693e70bc 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/memory_reporter.md +++ b/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. diff --git a/cobalt/site/docs/reference/starboard/modules/14/storage.md b/cobalt/site/docs/reference/starboard/modules/14/storage.md index db7e9509bd2b..1c08ed71b8eb 100644 --- a/cobalt/site/docs/reference/starboard/modules/14/storage.md +++ b/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. diff --git a/cobalt/site/docs/reference/starboard/modules/15/event.md b/cobalt/site/docs/reference/starboard/modules/15/event.md index 58cb1f4d1390..16f8020480fd 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/event.md +++ b/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 diff --git a/cobalt/site/docs/reference/starboard/modules/15/memory.md b/cobalt/site/docs/reference/starboard/modules/15/memory.md index 2fbf7dc94346..0b1e04ad94a4 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/memory.md +++ b/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 #### diff --git a/cobalt/site/docs/reference/starboard/modules/15/memory_reporter.md b/cobalt/site/docs/reference/starboard/modules/15/memory_reporter.md index d67ef1aada3e..5e49693e70bc 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/memory_reporter.md +++ b/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. diff --git a/cobalt/site/docs/reference/starboard/modules/15/storage.md b/cobalt/site/docs/reference/starboard/modules/15/storage.md index db7e9509bd2b..1c08ed71b8eb 100644 --- a/cobalt/site/docs/reference/starboard/modules/15/storage.md +++ b/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. diff --git a/cobalt/site/docs/reference/starboard/modules/byte_swap.md b/cobalt/site/docs/reference/starboard/modules/byte_swap.md new file mode 100644 index 000000000000..c83927d5132d --- /dev/null +++ b/cobalt/site/docs/reference/starboard/modules/byte_swap.md @@ -0,0 +1,75 @@ +--- +layout: doc +title: "Starboard Module Reference: byte_swap.h" +--- + +Specifies functions for swapping byte order. These functions are used to deal +with endianness when performing I/O. + +## Functions ## + +### SbByteSwapS16 ### + +Unconditionally swaps the byte order in signed 16-bit `value`. `value`: The +value for which the byte order will be swapped. + +#### Declaration #### + +``` +int16_t SbByteSwapS16(int16_t value) +``` + +### SbByteSwapS32 ### + +Unconditionally swaps the byte order in signed 32-bit `value`. `value`: The +value for which the byte order will be swapped. + +#### Declaration #### + +``` +int32_t SbByteSwapS32(int32_t value) +``` + +### SbByteSwapS64 ### + +Unconditionally swaps the byte order in signed 64-bit `value`. `value`: The +value for which the byte order will be swapped. + +#### Declaration #### + +``` +int64_t SbByteSwapS64(int64_t value) +``` + +### SbByteSwapU16 ### + +Unconditionally swaps the byte order in unsigned 16-bit `value`. `value`: The +value for which the byte order will be swapped. + +#### Declaration #### + +``` +uint16_t SbByteSwapU16(uint16_t value) +``` + +### SbByteSwapU32 ### + +Unconditionally swaps the byte order in unsigned 32-bit `value`. `value`: The +value for which the byte order will be swapped. + +#### Declaration #### + +``` +uint32_t SbByteSwapU32(uint32_t value) +``` + +### SbByteSwapU64 ### + +Unconditionally swaps the byte order in unsigned 64-bit `value`. `value`: The +value for which the byte order will be swapped. + +#### Declaration #### + +``` +uint64_t SbByteSwapU64(uint64_t value) +``` diff --git a/cobalt/site/docs/reference/starboard/modules/configuration_constants.md b/cobalt/site/docs/reference/starboard/modules/configuration_constants.md index 78350bf815d2..99d92f822809 100644 --- a/cobalt/site/docs/reference/starboard/modules/configuration_constants.md +++ b/cobalt/site/docs/reference/starboard/modules/configuration_constants.md @@ -139,3 +139,7 @@ The string form of SB_PATH_SEP_CHAR. Specifies the preferred byte order of color channels in a pixel. Refer to starboard/configuration.h for the possible values. EGL/GLES platforms should generally prefer a byte order of RGBA, regardless of endianness. + +### kSbUserMaxSignedIn ### + +The maximum number of users that can be signed in at the same time. diff --git a/cobalt/site/docs/reference/starboard/modules/memory.md b/cobalt/site/docs/reference/starboard/modules/memory.md index 2fbf7dc94346..0b1e04ad94a4 100644 --- a/cobalt/site/docs/reference/starboard/modules/memory.md +++ b/cobalt/site/docs/reference/starboard/modules/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 #### diff --git a/cobalt/site/docs/reference/starboard/modules/memory_reporter.md b/cobalt/site/docs/reference/starboard/modules/memory_reporter.md index d67ef1aada3e..5e49693e70bc 100644 --- a/cobalt/site/docs/reference/starboard/modules/memory_reporter.md +++ b/cobalt/site/docs/reference/starboard/modules/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. diff --git a/cobalt/site/docs/reference/starboard/modules/storage.md b/cobalt/site/docs/reference/starboard/modules/storage.md index 878500721e7a..1c08ed71b8eb 100644 --- a/cobalt/site/docs/reference/starboard/modules/storage.md +++ b/cobalt/site/docs/reference/starboard/modules/storage.md @@ -3,14 +3,14 @@ layout: doc title: "Starboard Module Reference: storage.h" --- -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. +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. +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. @@ -55,22 +55,23 @@ bool SbStorageCloseRecord(SbStorageRecord record) ### SbStorageDeleteRecord ### -Deletes the `SbStorageRecord` named `name`. The return value +Deletes the `SbStorageRecord` for `user` named `name`. The return value indicates whether the record existed and was successfully deleted. If the record did not exist or could not be deleted, the function returns `false`. -If `name` is NULL, deletes the default storage record, like what +If `name` is NULL, deletes the default storage record for the user, like what would have been deleted with the previous version of SbStorageDeleteRecord. -This function must not be called while the storage record is open. This +This function must not be called while the user's storage record is open. This function performs blocking I/O on the calling thread. -`name`: The filesystem-safe name of the record to open. +`user`: The user for whom the record will be deleted. `name`: The filesystem- +safe name of the record to open. #### Declaration #### ``` -bool SbStorageDeleteRecord(const char *name) +bool SbStorageDeleteRecord(SbUser user, const char *name) ``` ### SbStorageGetRecordSize ### @@ -98,20 +99,22 @@ static bool SbStorageIsValidRecord(SbStorageRecord record) ### SbStorageOpenRecord ### -Opens and returns the SbStorageRecord named `name`, blocking I/O on -the calling thread until the open is completed. Will return an +Opens and returns the SbStorageRecord for `user` named `name`, blocking I/O on +the calling thread until the open is completed. If `user` is not a valid +`SbUser`, the function returns `kSbStorageInvalidRecord`. Will return an `SbStorageRecord` of size zero if the record does not yet exist. Opening an already-open `SbStorageRecord` has undefined behavior. -If `name` is NULL, opens the default storage record, like what +If `name` is NULL, opens the default storage record for the user, like what would have been saved with the previous version of SbStorageOpenRecord. -`name`: The filesystem-safe name of the record to open. +`user`: The user for which the storage record will be opened. `name`: The +filesystem-safe name of the record to open. #### Declaration #### ``` -SbStorageRecord SbStorageOpenRecord(const char *name) +SbStorageRecord SbStorageOpenRecord(SbUser user, const char *name) ``` ### SbStorageReadRecord ### diff --git a/cobalt/site/docs/reference/starboard/modules/user.md b/cobalt/site/docs/reference/starboard/modules/user.md new file mode 100644 index 000000000000..406e695c4a2e --- /dev/null +++ b/cobalt/site/docs/reference/starboard/modules/user.md @@ -0,0 +1,133 @@ +--- +layout: doc +title: "Starboard Module Reference: user.h" +--- + +Defines a user management API. This module defines functions only for managing +signed-in users. Platforms that do not have users must still implement this API, +always reporting a single user that is current and signed in. + +These APIs are NOT expected to be thread-safe, so either call them from a single +thread, or perform proper synchronization around all calls. + +## Macros ## + +### kSbUserInvalid ### + +Well-defined value for an invalid user. + +## Enums ## + +### SbUserPropertyId ### + +A set of string properties that can be queried on a user. + +#### Values #### + +* `kSbUserPropertyAvatarUrl` + + The URL to the avatar for a user. Avatars are not provided on all platforms. +* `kSbUserPropertyHomeDirectory` + + The path to a user's home directory, if supported on this platform. +* `kSbUserPropertyUserName` + + The username of a user, which may be the same as the User ID, or it may be + friendlier. +* `kSbUserPropertyUserId` + + A unique user ID of a user. + +## Typedefs ## + +### SbUser ### + +A handle to a user. + +#### Definition #### + +``` +typedef SbUserPrivate* SbUser +``` + +## Functions ## + +### SbUserGetCurrent ### + +Gets the current primary user, if one exists. This is the user that is +determined, in a platform-specific way, to be the primary user controlling the +application. For example, the determination might be made because that user +launched the app, though it should be made using whatever criteria are +appropriate for the platform. + +It is expected that there will be a unique SbUser per signed-in user, and that +the referenced objects will persist for the lifetime of the app. + +#### Declaration #### + +``` +SbUser SbUserGetCurrent() +``` + +### SbUserGetProperty ### + +Retrieves the value of `property_id` for `user` and places it in `out_value`. +The function returns: + +* `true` if the property value is retrieved successfully + +* `false` if `user` is invalid; if `property_id` isn't recognized, supported, + or set for `user`; or if `value_size` is too small. + +`user`: The user for which property size data is being retrieved. `property_id`: +The property for which the data is requested. `out_value`: The retrieved +property value. `value_size`: The size of the retrieved property value. + +#### Declaration #### + +``` +bool SbUserGetProperty(SbUser user, SbUserPropertyId property_id, char *out_value, int value_size) +``` + +### SbUserGetPropertySize ### + +Returns the size of the value of `property_id` for `user`, INCLUDING the +terminating null character. The function returns `0` if `user` is invalid or if +`property_id` is not recognized, supported, or set for the user. + +`user`: The user for which property size data is being retrieved. `property_id`: +The property for which the data is requested. + +#### Declaration #### + +``` +int SbUserGetPropertySize(SbUser user, SbUserPropertyId property_id) +``` + +### SbUserGetSignedIn ### + +Gets a list of up to `users_size` signed-in users and places the results in +`out_users`. The return value identifies the actual number of signed-in users, +which may be greater or less than `users_size`. + +It is expected that there will be a unique `SbUser` per signed-in user and that +the referenced objects will persist for the lifetime of the app. + +`out_users`: Handles for the retrieved users. `users_size`: The maximum number +of signed-in users to retrieve. + +#### Declaration #### + +``` +int SbUserGetSignedIn(SbUser *out_users, int users_size) +``` + +### SbUserIsValid ### + +Returns whether the given user handle is valid. + +#### Declaration #### + +``` +static bool SbUserIsValid(SbUser user) +``` From f2a5f7cf6608d12e4a43880548511e02d6587750 Mon Sep 17 00:00:00 2001 From: Oscar Vestlie Date: Wed, 30 Aug 2023 15:27:02 -0700 Subject: [PATCH 2/2] Remove sb_is_modular from gn configuration docs --- cobalt/site/docs/reference/starboard/gn-configuration.md | 1 - 1 file changed, 1 deletion(-) diff --git a/cobalt/site/docs/reference/starboard/gn-configuration.md b/cobalt/site/docs/reference/starboard/gn-configuration.md index f4572b913bae..18db1eea7eea 100644 --- a/cobalt/site/docs/reference/starboard/gn-configuration.md +++ b/cobalt/site/docs/reference/starboard/gn-configuration.md @@ -35,7 +35,6 @@ title: "Starboard: configuration.gni Reference Guide" | **`sb_filter_based_player`**

Used to indicate that the player is filter based.

The default value is `true`. | | **`sb_is_evergreen`**

Whether this is an Evergreen build.

The default value is `false`. | | **`sb_is_evergreen_compatible`**

Whether this is an Evergreen compatible platform. A compatible platform can run the elf_loader and launch the Evergreen build.

The default value is `false`. | -| **`sb_is_modular`**

Whether this is a modular build.

The default value is `false`. | | **`sb_libevent_method`**

The event polling mechanism available on this platform to support libevent. Platforms may redefine to 'poll' if necessary. Other mechanisms, e.g. devpoll, kqueue, select, are not yet supported.

The default value is `"epoll"`. | | **`sb_static_contents_output_data_dir`**

Directory path to static contents' data.

The default value is `"/project_out_dir/content/data"`. | | **`sb_use_no_rtti`**

Whether or not to disable run-time type information (adding no_rtti flag).

The default value is `false`. |