C Language Binding

From RTSC-Pedia

Jump to: navigation, search
revision tip
—— LANDSCAPE orientation
[printable version]  [offline version]offline version generated on 21-Apr-2014 02:04 UTC

C Language Binding

Compile-time & run-time elements introduced by RTSC

Contents

Common public functions

The following functions are part of the public interface provided by all modules.

C - Module_getMask Get a module's diagnostics mask
C - Module_hasMask Check for a module diagnostics mask
C - Module_handle Get the instance handle for a constructed instance
C - Module_heap Get a module's heap
C - Module_id Get a module's unique ID
C - Module_setMask Set a module's diagnostics mask
C - Module_startupDone Query if a module's startup is complete

In addition, modules that support instance objects also provide the following functions.

C - construct Initialize a new instance object from a provided structure
C - create Allocate and initialize a new instance object and return its handle
C - destruct Finalize a previously constructed instance object
C - delete Finalize and free a previously allocated instance object
C - Handle_label Get an instance's label
C - Handle_name Get an instance's name
C - Object_count Get the number of statically created instances
C - Object_first Get the handle of the first dynamically created instance
C - Object_get Get the instance handle of a statically created instance
C - Object_heap Get a module's instance heap
C - Object_next Get the handle of the next dynamically created instance
C - Params_init Initialize new instance creation parameters
C - Params_copy Copy instance creation parameters

Modules that inherit from interfaces provide the following type-safe conversion operations.

C - Handle_downCast conditionally move one level down the inheritance hierarchy
C - Handle_upCast unconditionally move one level up the inheritance hierarchy

Internal functions

The following functions are "internal functions" implemented by modules in order to support module instance object creation and deletion (if necessary) as well as the common public functions listed above.

C - Instance_finalize Module's instance finalization function
C - Instance_init Module's instance initialization function
C - Module_startup Module's startup initialization function


Instance creation

Instance creation.  Both the module's instance create and construct functions call a common configuration generated "stub" named «Mod»__Object__create__S. In the case of construct, this stub is passed the address of a structure suitable to hold the module's instance state; otherwise, a NULL pointer is passed.

The generated stub calls a common method in xdc.runtime.Core to allocate the instance state from a heap (if necessary) and initialize runtime-specific fields to enable the instance to be tracked by the runtime. If this initialization completes successfully, the stub then calls the module's Instance_init function.

In some configurations, a module's generated creation stub simply raises an error via Error_raise. For example, if the module's memoryPolicy is set to STATIC_POLICY, calls to the module's instance create function triggers an error. This is done to ensure that, in the event that the application inadvertently calls an instance creation method, the system catches the error.

Instance deletion

Instance deletion.  A module's instance delete function calls a configuration generated "stub" named «Mod»__Object__delete__S. In contrast to create and construct, a module's destruct function calls a different generated stub named «Mod»__Object__destruct__S.

These generated stubs call a common method in xdc.runtime.Core to cleanup any runtime-specific state tracked by the runtime, call the module's finalize method, and delete the instance state (if necessary).

Module-specific functions

Module-wide functions

Module-wide functions.  The RTSC IDL allows you to specify "module-wide" functions; functions that are not associated with any particular instance that may be managed by the module. For example, the LoggerBuf_flushAll() function is declared in LoggerBuf.xdc and implemented in LoggerBuf.c as follows:

LoggerBuf.xdc
 
 
 
 
 module LoggerBuf {
     Void flushAll();
         :
}
LoggerBuf.c
 
 
 
 
 
 
#include "package/internal/LoggerBuf.xdc.h"
 
Void LoggerBuf_flushAll(Void)
{
    :
}

Clients of LoggerBuf_flushAll simply include the LoggerBuf module's public header and call LoggerBuf_flushAll() using the arguments specified in LoggerBuf.xdc.

client.c
 
 
 
#include <xdc/runtime/LoggerBuf.h>
    :
LoggerBuf_flushAll();
Instance functions

Instance functions.  The RTSC IDL allows you to specify module functions which operate on an instance type managed by the module. For example, the HeapMin_alloc() function is declared in HeapMin.xdc and implemented in HeapMin.c as follows:

HeapMin.xdc
 
 
 
 
 
 module HeapMin {
     instance:
     Void free(Ptr block, SizeT size);
         :
}
HeapMin.c
 
 
 
 
 
 
#include "package/internal/HeapMin.xdc.h"
 
Void HeapMin_free(HeapMin_Object *obj, Ptr block, SizeT size)
{
    :
}

Clients of HeapMin_free simply include the HeapMin module's public header and call HeapMin_free() using the arguments specified in HeapMin.xdc after passing an instance handle as the first argument.

client.c
 
 
 
 
#include <xdc/runtime/HeapMin.h>
    :
HeapMin_Handle heap;
HeapMin_free(heap, buf, size);
Variable arguments support

Variable arguments support.  The RTSC IDL allows you to specify functions which, like printf(), accept a variable number of arguments. The syntax used in the IDL is essentially the same as that specified by ANSI C. For example, the System_printf() function is declared in System.xdc and implemented in System.c as follows:

System.xdc
 
 
 
 
 module System {
     Int printf(String fmt, ...);
         :
}
System.c
 
 
 
 
 
 
#include "package/internal/System.xdc.h"
 
Int System_printf_va(String fmt, VaList va)
{
    :
}

Clients of System_printf simply include the System module's public header and call System_printf() using the arguments specified in System.xdc.

client.c
 
 
 
#include <xdc/runtime/System.h>
    :
System_printf("x = %d, y = %d\n", 1, 2);

Module Binary Contract

The following topics describe the binary data structures and symbols created to support the bindings described above. To maintain compatibility with packages created using different versions of XDCtools, these data structures and their names must not change. It's important to note, however, that while the data structures defined in a module's headers cannot change, the data structures defined in the generated configuration files can (and often do) change from release to release of XDCtools.

Integrating RTSC Modules#Linking Integrating RTSC modules into existing C/C++ environments
Integrating RTSC Modules#Debugging Integrating RTSC modules into existing C/C++ environments

[printable version]  [offline version]offline version generated on 21-Apr-2014 02:04 UTC
Copyright © 2008 The Eclipse Foundation. All Rights Reserved
Personal tools
package reference