The Starboard ABI was introduced to provide a single, consistent method for specifying the Starboard API version and the ABI. This specification ensures that any two binaries, built with the same Starboard ABI and with arbitrary toolchains, are compatible.
Background
The Starboard ABI is the set of features, such as the Starboard API version or the sizes of data types, that collectively describes the relationship between the Starboard API and ABI of a binary. In the past, each of these features were inconsistently and ambiguously defined in a variety of files. This led to confusion, and made it difficult to track down the feature values for a platform. To simplify how Starboard is configured for a target platform, all of these features, and their concrete values, are now listed for each distinct target architecture in Starboard ABI files. These files provide a consistent, consolidated view of the values for each of these features, decoupling platform-specific details from architecture.
Goals
The overall goal of the Starboard ABI is to provide a way to implement and verify binary compatibility on a target platform, and this goal can be broken down into the following more concise motivations:
- Separate platform and architecture into distinct concepts.
- Establish a consistent set of values for the various features of each target architecture.
- Consolidate this set of features and their values in a consistent, predictable location.
- Provide the ability to validate the values of each feature in produced binaries.
Using Starboard ABI Files
With the Starboard ABI being the source of truth for all things architecture
related, each platform must now include a Starboard ABI file in its build (see
//starboard/sabi
for examples). Starboard ABI files are JSON, and should all contain identical
keys with the values being appropriate for the architecture. Each platform must
set the sabi_path GN variables in its
platform_configuration/configuration.gni file to return the path to the
desired Starboard ABI file (e.g.
//starboard/linux/x64x11/shared/platform_configuration/configuration.gni).
By default, an empty and invalid Starboard ABI file is provided.
Additionally, all platforms must include the //starboard/build/config/sabi
config from sabi/BUILD.gn
in their platform configs. This file will consume the specified Starboard ABI
file, resulting in the creation of a set of GN variables and preprocessor
macros. The preprocessor macros are passed directly to the compiler and replace
the macros you might be familiar with, such as SB_HAS_32_BIT_LONG.
The newly defined GN variables need to be transformed into toolchain specific flags; these flags are what actually makes the build result in a binary for the desired architecture. These flags will, in most cases, be identical to the flags already being used for building.
The process outlined above is shown in the diagram below.
Post-Starboard ABI File Cleanup
A number of GN variables and preprocessor macros should no longer be defined directly, and instead the Starboard ABI file will be used to define them. These definitions need to be removed.
From configuration_public.h:
SB_IS_ARCH_*SB_IS_BIG_ENDIANSB_IS_32_BITSB_IS_64_BITSB_HAS_32_BIT_LONGSB_HAS_64_BIT_LONGSB_HAS_32_BIT_POINTERSSB_HAS_64_BIT_POINTERS
FAQ
What Starboard ABI files are provided?
The Cobalt team provides, and maintains, Starboard ABI files for the following architectures:
- x86_64
- ARM v7 (32-bit)
- ARM v8 (64-bit)
If you find that no valid Starboard ABI file exists for your architecture, or that you need to change any values of a provided Starboard ABI file, please reach out to the Cobalt team to advise.
How can I verify that my build is configured correctly?
Similar to the process prior to Starboard ABI files, there are multiple levels of verification that occur:
- When configuring your build, the Starboard ABI file that was specified will have its values sanity checked against a provided schema.
- When building, a number of static assertions will assert correctness of a number of features generated from the Starboard ABI file against the features of the binary.
- The NPLB test suite has been expanded to include additional tests capable of verifying the remaining features of the binary.
Finally, binaries produced by the Cobalt team for your architecture, including NPLB, will be made available to ensure end-to-end correctness of the produced binaries.