Using Encoded Types

From RTSC-Pedia

Jump to: navigation, search
revision tip
—— LANDSCAPE orientation
[printable version]  [offline version]offline version generated on 18-Nov-2017 00:11 UTC

Using Encoded Types

How to create and use encoded types


TODO:  belongs in the XDCtools User's Guide as a "WHATIS" + "HOWTO"

Contents

Introduction

RTSC modules have a dual existence: they exist in the meta-domain and (optionally) in the target-domain. On the other hand, modules have a single specification file. So, by default, a single specification results in the generation of two bindings: one for the meta-domain and one for the target domain. In most cases, the representation of types declared in the module's specification have an obvious representation in the target-domain.

However, there are situations where the module producer wants the target-domain representation of a type to differ from the default target-domain representation. For example, you need the representation of a target type to be a single integer whereas in the meta-domain (where there are virtually no performance constraints) the type is a multi-field structure. In these situations, you can declare the type to be "encoded" and take control of the target-domain representation of values having the specified encoded type.

Implementing An Encoded Type

When a type is declared with the @Encoded attribute the module must:

  1. have custom headers that declare the C type (see @CustomHeader), and
  2. have a meta-domain file that defines functions that describe the alignment, sizeof and encoding of the type.
Module's Custom C/C++ Header

Module's Custom C/C++ Header.  The module's custom headers, Mod__prologue.h and Mod__epilogue.h, must declare the C type for the type declared in the module's specification.

For example, the following declaration appears in the xdc.runtime.Log module's Log__prologue.h header.

 
typedef xdc_Bits32 xdc_runtime_Log_Event;
Module's Meta-Domain Implementation

Module's Meta-Domain Implementation.  The Mod module's meta-domain implementation file, Mod.xs, must define the following three functions for each encoded type EType:

  1. EType$alignof() - returns an integral target alignment value for the type in MAUs,
  2. EType$sizeof() - returns an integral target size value for the type in MAUs, and
  3. EType$encode(desc) - returns a string containing a C expression that evaluates to a C initializer that represents the value of the meta-domain value desc. This expression is used to initialize the type whenever something of this type needs to be statically initialized within a generated C file (such as the .c file generated by the configuration tool).

For example, the following definitions appear in the xdc.runtime.Log module's Log.xs file.

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
/*
 *  ======== Event$alignof ========
 *  Return alignment required for an encoded value of an EventDesc
 */
function Event$alignof()
{
    return (Program.build.target.stdTypes.t_Int32.align);
}
 
/*
 *  ======== Event$encode ========
 *  Return a C expression that evaluates to the encoded value of an EventDesc
 */
function Event$encode(desc)
{
    var encodedDesc = "0";
    if (desc) {
        encodedDesc = "(((xdc_runtime_Log_Event)" + desc.$private.id
            + ") << 16 | " + (desc.mask & 0xFFFF) + ")";
    }
    return (encodedDesc);
}
 
/*
 *  ======== Event$sizeof ========
 *  Return sizeof the encoded value of an EventDesc
 */
function Event$sizeof()
{
    return (Program.build.target.stdTypes.t_Int32.size);
}
[printable version]  [offline version]offline version generated on 18-Nov-2017 00:11 UTC
Copyright © 2008 The Eclipse Foundation. All Rights Reserved
Personal tools
package reference