# Platform Definition

# Overview

One of Sedona Framework's strengths is the portability of Sedona apps across different hardware platforms. This is accomplished by building a custom version of the SVM for each supported platform, tailored to the specific underlying architecture. Details on the customization of the SVM will be covered in the Porting chapter. Here we cover how that process is streamlined, by encapsulating platform-specific information into a platform definition file.

When you run `sedonac` on a platform definition file, it will do the following:

1. Stage the native method source code so that a native toolchain can be used to build the SVM.
2. Produce a platform manifest and stage it for later packaging into a PAR file.

Note that `sedonac` does not actually build the SVM, it merely stages the native source files for convenient building with the native toolchain. See the Staging section for more details about how `sedonac` uses the platform definition to stage native source code and the platform manifest.

# Platform Definition XML

The platform definition file is an XML file created by a Sedona platform developer. It serves three major purposes:

1. Specifies a unique platform id that will be reported by platforms using this SVM.
2. Declares properties needed for building the SVM, such as endianness, block size, and pointer size.
   If you want your SVM to support a kit that contains native methods, you must declare that dependency as well, and specify the location of the source code for the native methods.
3. Declares arbitrary metadata about the platform. Sedona Framework tools can use this metadata to enhance the experience of working with a specific platform.

The following is an example platform definition file for a win32 platform.

    <sedonaPlatform vendor="Acme" id="acme-basicPlatform-win32-${sedona.env.version}">

      <compile endian="little" blockSize="4" refSize="4" debug="true" test="true">

        <!-- Native Kits -->
        <nativeKit depend="sys 1.0" />
        <nativeKit depend="inet 1.0" />
        <nativeKit depend="datetimeStd 1.0" />
        <nativeKit depend="acmePlatform 1.0" />

        <!-- Native Sources -->
        <nativeSource path="/src/vm" />
        <nativeSource path="/src/sys/native" />
        <nativeSource path="/src/sys/native/std" />
        <nativeSource path="/src/sys/native/win32" />
        <nativeSource path="/src/inet/native" />
        <nativeSource path="/src/inet/native/std" />
        <nativeSource path="/src/inet/native/sha1" />
        <nativeSource path="/src/datetimeStd/native/std" />
        <nativeSource path="/../acme/src/platforms/acmePlatform/native/win32" />
      </compile>

      <manifestInclude path="more_metadata.xml" />
      <manifestInclude>
        <contact email="jdoe@acme.com" url="http://www.acme.com/sedona/help.html" />
        <schemes>
          <!-- this platform implements the manifest transfer scheme "m:" -->
          <scheme id="m"/>
        </schemes>
      </manifestInclude>

    </sedonaPlatform>

<sedonaPlatform> top level element for the platform definition:

- vendor: (required) The vendor owning this platform.

- id: (optional)The id that uniquely identifies this platform. This id must be prefixed with the string "`vendor-`". In the example above the vendor is "Acme" and the id is prefixed with "acme-".

  `sedonac` will generate a C header file `sedonaPlatform.h` in the stage directory containing a macro `PLATFORM_ID` with the value of the resolved id. The resolved platform id must be returned by the corresponding platform's implementation of `sys::PlatformService.platformId()`. The generated header file is intended to help facilitate this.

  The platform id can generally have any format, but the `'-'` character in the platform id will be interpreted as a directory separator when storing the PAR file for that platform into the platform database. See the section on the Platform Database for more details.

  If the id is omitted, no `sedonaPlatform.h` will be generated, and the platform manifest generated by `sedonac` will not contain an id. The platform manifest is not valid when an id is missing. That is, a PAR file containing a platform manifest with no id will be rejected by sedonadev.org when an upload is attempted. It becomes the responsibility of the build toolchain to insert the appropriate id attribute into the platform manifest before generating a PAR file. For this reason, it is better to try and specify an id variable pattern in your platform definition.

  This attribute supports variable substitution. There are a number of variables that `sedonac` will recognize when compiling a platform definition. These two are the most commonly used:

  - ${stage.nativeChecksum}: `sedonac` will calculate a native checksum for all native methods that are supported by this platform SVM. This variable represents that checksum value.
    Note that this is NOT the same as a kit checksum. Kit checksums are used for checking component-level compatibility when connecting to a Sedona device. The native checksum is used when provisioning a device, to check native compatibility of a kit on a given platform; if the SVM doesn't support the kit's native methods then the kit shouldn't be loaded on that device.
  - ${sedona.env.version}: `sedonac` will look up the value of the environment variable `sedona.env.version` and substitute it wherever it occurs in the platform definition XML.

  See the section on Variable Substitution for other variables `sedonac` will recognize.

<compile> provides platform-specific parameters:

- endian: (required) either "little" or "big" based on target processor.
- blockSize: (required) size of a scode block in bytes (see the source for `src/vm/sedona.h`)
- refSize: (required) size of a memory pointer in bytes for target processor (4 for 32-bit processor).
- debug: (optional) boolean to include debug meta-data in image. Defaults to false
- test: (optional) boolean to include test code in image. Defaults to false
- armDouble: (optional) set to true if using an ARM microprocessor where 64-bit doubles are stored using byte level little endian, word level big endian.

<nativeKit> indicates that this platform SVM implements the native methods from the specified kit.

- depend: (required) dependency as a kit name and version constraint.

<nativeSource> designates a source path to native code:

- path: (required) path to a folder with native code that must be built into the SVM image. The path must start with "/" and be relative to sedona_home.

  This attribute supports variable substitution.

<manifestInclude> (optional) is used to include arbitrary XML metadata in the generated platform manifest file. All XML elements that are children of the manifest include will be copied into the platform manifest.

Note: All XML namespace URIs that begin with `http://sedonadev.org/ns` are reserved by the Sedona Framework. Vendor specific XML elements should not use any such namespace URI.

- path: (optional) specifies the path to an external XML file to be included. The entire XML contents of that file will be copied into the platform manifest. (This could be used to include time-varying metadata into a platform definition file that stays fixed, or to include common metadata, such as contact info, shared by several related platforms.) If the path starts with "/" then the path is relative to sedona_home. Otherwise, the path is relative to the directory containing the platform definition.
- <schemes> (optional) The schemes child of the manifest include can be used to explicitly declare what schemes the platform supports. Each implemented scheme has the format `<scheme id="scheme"/>`. See the examples below for more details.

# Platform Manifest

In addition to staging the native source code, `sedonac` will stage a platform manifest XML file. This file will eventually be packaged into a PAR file for upload to sedonadev.org or installation into the local platform database. The following is an abridged version of the platformManifest.xml that might be generated for the platform definition above.

    <?xml version='1.0'?>
    <platformManifest
        platformId="acme-basicPlatform-win32-1.0.38"
        vendor="Acme"
        endian="little"
        blockSize="4"
        refSize="4"
        armDouble="false"
        debug="true"
        test="true"
    >

    <!-- Natives -->
    <natives>
      <nativeKit depend="sys 1.0" />
      <nativeKit depend="inet 1.0" />
      <nativeKit depend="datetimeStd 1.0" />
      <nativeKit depend="acmeBasicPlatform 1.0" />

      <nativeMethod qname="sys::Sys.platformType" id="0::0" />
      <nativeMethod qname="sys::Sys.copy" id="0::1" />
      <!-- ... -->
      <nativeMethod qname="acmeBasicPlatform::BasicPlatform.doPlatformId" id="1::0" />
      <nativeMethod qname="inet::TcpSocket.connect" id="2::0" />
      <nativeMethod qname="inet::TcpSocket.finishConnect" id="2::1" />
      <!-- ... -->
    </natives>

    <!-- Manifest Includes -->
    <manifestIncludes>
      <metadata foo="bar" />
      <contact email="jdoe@acme.com" url="http://www.acme.com/sedona/help.html" />
      <schemes>
        <!-- this platform implements the manifest transfer scheme -->
        <!-- If the packed attribute is 'true' (default), then all the kit manifests
             will be sent in a single zip file. If the packed attribute is anything else
             then each manifest will be zipped and sent one at a time.-->
        <scheme id="m" packed="true" />
      </schemes>
    </manifestIncludes>

    </platformManifest>

<platformManifest> top level element for the platform manifest. It contains all attributes from the platform definition root element and <compile> element. The id is the resolved platform id.

<natives> contains the native kit definitions from the platform definition and the list of native methods that the platform SVM will be able to support. Note: the `qname` attribute of the <nativeMethod> is for reference - tools should typically compare scode compatibility with a given platform SVM by comparing the native method id, not the `qname`.

<manifestIncludes> this element contains all the manifest include XML from the platform definition.