

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:

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

Note

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:

Specifies a unique platform id that will be reported by platforms using this SVM.
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.
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
  
  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.

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.

Last update: April 28, 2020