Sedona

Index | Prev | Next

Platform Definition

Overview

One of Sedona Framework's strengths is the portability of Sedona and 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. The process for customizing the SVM is streamlined by encapsulating the platform-specific information into a platform definition file.

When you run sedonac on a platform definition file, it will produce the following output:

  1. All the native method source code is staged so that a native toolchain can be used to build the SVM.
  2. A platform manifest is produced and staged for later packaging into a PAR file.

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 that serves three major purposes:

  1. Specify the unique platform id for platforms using this SVM.
  2. Declare properties needed for building the SVM. Such properties include endianness, block size, and pointer size. If you want your SVM to support a kit that contains native methods, you must declare those dependencies as well, and specify the locations of the source code for the native methods.
  3. Declare 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="metadata.xml" />
  <manifestInclude>
    <contact email="jdoe@acme.com" url="http://www.acme.com/sedona/help.html" />
  </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" />
</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.

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

Index | Prev | Next