Sedona

Index | Prev | Next

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:

<compile> provides platform-specific parameters:

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

<nativeSource> designates a source path to native code:

<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.

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.

Index | Prev | Next