| --- | |
| layout: doc | |
| title: "Porting Cobalt to your Platform with Starboard" | |
| --- | |
| This document provides step-by-step instructions for porting Cobalt to run | |
| on your platform. To do so, you'll use Starboard, which is Cobalt's porting | |
| layer and OS abstraction. Starboard encapsulates only the platform-specific | |
| functionality that Cobalt uses. | |
| To complete a port, you need to add code to the Cobalt source tree. We | |
| recognize that many porters will not want to actually share details of | |
| their Starboard implementation with external users. These porters likely | |
| have their own source control and will fork Cobalt into their software | |
| configuration management (SCM) tools. These instructions take that use | |
| case into account and explain how to add your port in a way that will not | |
| conflict with future Cobalt source code changes. | |
| ## Prerequisites | |
| To complete the instructions below, you first need to clone the Cobalt source | |
| code repository: | |
| ```sh | |
| $ git clone https://cobalt.googlesource.com/cobalt | |
| ``` | |
| If you prefer, you can instead complete the instructions for | |
| [setting up a Cobalt development environment on Linux]( | |
| /cobalt/development/setup-linux.html). Checking out the Cobalt source | |
| code is one step in that process. | |
| ## Porting steps | |
| ### 1. Enumerate and name your platform configurations | |
| Your first step is to define canonical names for your set of platform | |
| configurations. You will later use these names to organize the code | |
| for your platforms. | |
| A platform configuration has a one-to-one mapping to a production binary. | |
| As such, you will need to create a new platform configuration any time you | |
| need to produce a new binary. | |
| A platform configuration name has two components: | |
| * The `<family-name>` is a name that encompasses a group of products that | |
| you are porting to Starboard. | |
| * The `<binary-variant>` is a string that uniquely describes specifics | |
| of the binary being produced for that configuration. | |
| The recommended naming convention for a platform configuration is: | |
| <family-name>-<binary-variant> | |
| For example, suppose a company named BobCo produces a variety of BobBox | |
| devices. Some of the devices use big-endian MIPS chips, while others use | |
| little-endian MIPS chips. BobCo might define two platform configurations: | |
| * `bobbox-mipseb` | |
| * `bobbox-mipsel` | |
| In this example, `bobbox` is the family name and is used in both (all) | |
| of BobCo's platform configurations. The `binary-variant` for devices with | |
| big-endian MIPS chips is `mipseb`. For devices with little-endian MIPS chips, | |
| the `binary-variant` is `mipsel`. | |
| Starboard also supports sub-variant configurations to maximize your ability | |
| to share code between configurations. For example, if some of BobCo's devices | |
| that use little-endian chips use DirectFB, but other devices use OpenGL ES, | |
| BobCo could create two different configurations for little-endian chips: | |
| * `bobbox-mipsel-dfb` | |
| * `bobbox-mipsel-gles` | |
| ### 2. Add Source Tree Directories for your Starboard Port | |
| Add the following directories to the source tree for the `<family-name>` | |
| that you selected in step 1: | |
| * `src/third_party/starboard/<family-name>/` | |
| * `src/third_party/starboard/<family-name>/shared/` | |
| This subdirectory contains code that is shared between architectures | |
| within a product family. For example, if BobBox devices run on many | |
| different platforms, then BobCo needs to define a different configuration | |
| for each platform. However, if all of the configurations can use the same | |
| Starboard function implementation, BobCo can put that function in the | |
| `shared` directory to make it accessible in every binary variant. | |
| * `src/third_party/starboard/<family-name>/<binary-variant>/` | |
| You should create one directory for _each_ `<binary-variant>`. So, for | |
| example, BobCo could create the following directories: | |
| * `src/third_party/starboard/bobbox/shared/` | |
| * `src/third_party/starboard/bobbox/mipseb/` | |
| * `src/third_party/starboard/bobbox/mipsel/` | |
| * `src/third_party/starboard/bobbox/mipsel/dfb/` | |
| * `src/third_party/starboard/bobbox/mipsel/gles/` | |
| Again, functions that work for all of the configurations would go in the | |
| `shared` directory. Functions that work for all little-endian devices would go | |
| in the `mipsel` directory. And functions specific to little-endian devices | |
| that use DirectFB or that use OpenGL ES would go in the `mipsel/dfb` or | |
| `mipsel/gles` directory. | |
| ### 3. Add required `binary-variant` files | |
| Each `binary-variant` directory that you created in step 2 must contain | |
| the following files: | |
| * `atomic_public.h` | |
| * `configuration_public.h` | |
| * `gyp_configuration.gypi` | |
| * `gyp_configuration.py` | |
| * `starboard_platform.gyp` | |
| * `thread_types_public.h` | |
| We recommend that you copy the files from the Stub reference implementation, | |
| located at `src/third_party/stub/` to your `binary-variant` directories. | |
| In this approach, you will essentially start with a clean slate of stub | |
| interfaces that need to be modified to work with your platform. | |
| An alternate approach is to copy either the Desktop Linux or Raspberry Pi | |
| ports and then work backward to fix the things that don't compile or work | |
| on your platform. | |
| If you are copying the Stub implementation, you would run the following | |
| command for each `binary-variant` directory: | |
| ```sh | |
| cp -R src/starboard/stub | |
| src/third_party/starboard/<family-name>/<binary-variant> | |
| ``` | |
| After copying these files, you should be able to compile Cobalt and link it | |
| with your toolchain even though the code itself will not yet work. | |
| #### 3a. Additional files in the stub implementation | |
| The stub implementation contains three additional files that are not listed | |
| among the required files for each `binary-variant` directory: | |
| * `application_stub.cc` | |
| * `application_stub.h` | |
| * `main.cc` | |
| The Starboard `Application` class is designed to do the following: | |
| * Integrate a generic message loop function with a system message pump that | |
| can deliver either input or application lifecycle events like | |
| suspend/resume. | |
| * Provide a place for graceful platform-specific initialization and teardown. | |
| * Provide a universally accessible place to store global platform-specific | |
| state, such as managed UI windows. | |
| Thus, these files provide a framework for fulfilling Starboard's event | |
| dispatching requirements, even though they don't implement any specific | |
| Starboard interface and aren't strictly necessary for any given port. Even so, | |
| anyone who is porting Cobalt will likely need to adapt a copy of | |
| `application_stub.cc` and `application_stub.h` to their platforms needs. | |
| The `application` files do not necessarily need to be per-variant files. Even | |
| if you have multiple variants, it's still possible that you only need one copy | |
| of these files in your `shared` directory. Similarly, you might have a shared | |
| base class along with variant-specific subclasses. | |
| ### 4. Make required file modifications | |
| To port your code, you must make the following modifications to the files | |
| that you copied in step 3: | |
| 1. **`atomic_public.h`** - Ensure that this file points at the appropriate | |
| shared or custom implementation. | |
| 1. **`configuration_public.h`** - Adjust all of the [configuration values]( | |
| ../../reference/starboard/configuration-public.html) as appropriate for | |
| your platform. | |
| 1. **`gyp_configuration.py`** | |
| 1. Modify the `CreatePlatformConfig()` function to return the platform | |
| configuration that you defined in step 1. The example below shows that | |
| function as it appears in the Stub implementation and the Desktop | |
| Linux port: | |
| <pre> | |
| # Stub: | |
| def CreatePlatformConfig(): | |
| try: | |
| return PlatformConfig('<b>stub</b>') | |
| except RuntimeError as e: | |
| logging.critical(e) | |
| return None | |
| # Desktop Linux | |
| def CreatePlatformConfig(): | |
| try: | |
| return gyp_configuration.PlatformConfig('<b>linux-x64x11</b>') | |
| except RuntimeError as e: | |
| logging.critical(e) | |
| return None | |
| </pre> | |
| Note that the third line is the only one that is different. The | |
| key difference in terms of these instructions is changing `stub` | |
| to `linux-x64x11`. The Desktop Linux port also uses a shared copy | |
| of `gyp_configuration.py`, which is why the rest of the line is | |
| different. | |
| 1. In the `GetVariables` function, ensure that the `clang` variable | |
| is set to `1` if your toolchain uses clang: | |
| <pre> | |
| variables = super(PlatformConfig, self).GetVariables(configuration) | |
| <b>variables.update({'clang': 1,})</b> | |
| return variables | |
| </pre> | |
| 1. In the `GetEnvironmentVariables` function, set these dictionary values | |
| to the toolchain analogs for your platform. Note that "target platform" | |
| refers to the platform being targeted by the port (e.g. Android TV, | |
| Raspberry Pi) and "host platform" is the workstation platform running | |
| the cross-compiler to the target (e.g. desktop Linux, desktop Windows). | |
| * `CC` - the C compiler for the target platform. Example: `clang`. | |
| * `CXX` - the C++ compiler for the target platform. | |
| Example: `clang++`. | |
| * `CC_HOST` - the C compiler for the host platform. Example: `clang`. | |
| * `CXX_HOST` - the C++ compiler for the host platform. | |
| Example: `clang++`. | |
| * `LD_HOST` - the C++ linker for the host platform. | |
| Example: `clang++`. | |
| * `ARFLAGS_HOST` - Archiver flags for the host platform. The | |
| archiver is the toolchain program that creates static libraries. | |
| Example: `rcs`. | |
| * `ARTHINFLAGS_HOST` - Archiver flags for the host platform for | |
| creating "thin" archives, which are faster for intermediate | |
| libraries that aren't for direct publishing. Example: `rcsT`. | |
| 1. **`gyp_configuration.gypi`** | |
| 1. Update the value of the `default_configuration` property and the keys | |
| in the `configurations` property to be | |
| `<platform-configuration>_<build-type>` where: | |
| 1. `<platform-configuration>` is the value that you defined in step 1. | |
| 1. `<build-type>` is one of the following values: | |
| * `debug` | |
| * `devel` | |
| * `qa` | |
| * `gold` | |
| The following snippet from the configuration file shows how these | |
| properties appear in the Stub implementation. The Desktop Linux port | |
| replaces the string `stub` with `linux-x64x11` everywhere that it | |
| appears: | |
| ``` | |
| 'target_defaults': { | |
| 'default_configuration': 'stub_debug', | |
| 'configurations': { | |
| 'stub_debug': { | |
| 'inherit_from': ['debug_base'], | |
| }, | |
| 'stub_devel': { | |
| 'inherit_from': ['devel_base'], | |
| }, | |
| 'stub_qa': { | |
| 'inherit_from': ['qa_base'], | |
| }, | |
| 'stub_gold': { | |
| 'inherit_from': ['gold_base'], | |
| }, | |
| }, # end of configurations | |
| ... | |
| } | |
| ``` | |
| 1. Update the following properties in the `variables` dictionary: | |
| * `target_arch` - Identifies your architecture. Supported values | |
| are `arm`, `mips`, `ppc`, `x64`, and `x86`. | |
| * `target_os` - Set to `linux` if your platform is Linux-based. | |
| Otherwise, remove this variable. | |
| * `gl_type` - Set to `system_gles2` if you are using the system EGL | |
| + GLES2 implementation or to `system_gles3` if you are using the | |
| system EGL + GLES3 implementation. Otherwise, set the value to | |
| `none`. | |
| * `in_app_dial` - Enables (or disables) the DIAL server that runs | |
| inside Cobalt. (This server only runs when Cobalt is running.) | |
| The [DIAL protocol](http://www.dial-multiscreen.org/home) enables | |
| second-screen devices (like tablets and phones) to discover, | |
| launch, and interface with applications on first-screen devices | |
| (like televisions, set-top boxes, and Blu-ray players). | |
| * Set this value to `0` if you already have system-wide DIAL | |
| support. In that case, a DIAL server running inside Cobalt would | |
| be redundant. | |
| * Set this value to `1` if you want Cobalt to run a DIAL server | |
| whenever it is running. That server could only be used to | |
| connect with the current Cobalt application (e.g. YouTube). | |
| 1. Update your toolchain command-line flags and libraries. Ensure that | |
| you do not assume a particular workstation layout since that layout | |
| may vary from user to user. | |
| 1. Update the global defines in the `target_defaults.defines` dictionary, | |
| if necessary. | |
| 1. **`thread_types_public.h`** - Ensure that this file points at the | |
| appropriate shared or custom implementation. | |
| ### 5. Port modules to work on your platform | |
| The `starboard_platform.gyp` file points to all of the source files included | |
| in your new Starboard implementation. If you are starting with a copy of the | |
| Stub implementation, then that file will initially include a lot of files | |
| from the `src/starboard/shared/stub/` directory. Similarly, if you are starting | |
| starting with a copy of the Desktop Linux port, then that file will initially | |
| point to files in the `src/starboard/shared/posix` directory. | |
| The modules are defined so that each one has a set of functions, and each | |
| function is defined in its own file with a consistent naming convention. | |
| For example, the `SbSystemBreakIntoDebugger()` function is defined in the | |
| `system_break_into_debugger.cc` file. The list of files in the | |
| `src/starboard/shared/stub/` directory represents an authoritative list of | |
| supported functions. | |
| Function-by-function and module-by-module, you can now replace stub | |
| implementations with either custom implementations or with other ported | |
| implementations from the `src/starboard/shared/` directory until you have | |
| gone through all of the modules. As you do, update the | |
| `starboard_platform.gyp` file to identify the appropriate source files. | |
| Due to dependencies between modules, you will find it easier to get some | |
| modules to pass the NPLB tests before other modules. We recommend porting | |
| modules in the following order to account for such dependencies: | |
| 1. Configuration | |
| 1. main(), Application, and Event Pump - This is the call into `SbEventHandle`. | |
| 1. Memory | |
| 1. Byte Swap | |
| 1. Time | |
| 1. String/Character/Double | |
| 1. Log | |
| 1. File | |
| 1. Directory | |
| 1. System | |
| 1. Atomic | |
| 1. Thread & Thread Types | |
| 1. Mutex | |
| 1. Condition Variable | |
| 1. Once | |
| 1. Socket | |
| 1. SocketWaiter | |
| 1. Window | |
| 1. Input | |
| 1. Blitter (if applicable) | |
| 1. Audio Sink | |
| 1. Media & Player | |
| 1. DRM | |
| 1. TimeZone | |
| 1. User | |
| 1. Storage |