From RTSC-Pedia

[printable version]  [offline version]

offline version generated on 04-Aug-2010 21:08 UTC

Using Encoded Types

How to create and use encoded types

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

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, 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 modules specification.

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 constant that represents the value of the meta-domain value desc

/*
 *  ======== 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 04-Aug-2010 21:08 UTC