Comete User Manual

Revision 1.0
Comete
User Manual
Authors: Germain Haugou (STMicroelectronics)
Revision 1.0
Copyright STMicroelectronics 2008
2
Comete User Manual
Information furnished in this document is believed to be accurate and reliable. However, STMicroelectronics assumes no responsibility for the consequences of use of such information nor for any
infringement of patents or other rights of third parties, which may result from its use. No license is
granted by implication or otherwise under any patent or any rights of STMicroelectronics. Specifications
mentioned in this document are subject to change without notice. This document supersedes and
replaces all information previously supplied. STMicroelectronics products are not authorized for use as
critical components in life support devices or systems without express written approval of STMicroelectronics.
is a registered trademark of the STMicroelectronics Group.
c
2008
STMicroelectronics - All Rights Reserved.
STMicroelectronics GROUP OF COMPANIES
Australia - Brazil - Canada - China - France - Germany - Italy - Japan - Korea - Malaysia - Malta Morocco - The Netherlands - Singapore - Spain - Sweden - Switzerland - Taiwan - Thailand - United
Kingdom - U.S.A.
http://www.st.com
Copyright STMicroelectronics 2008
3
Comete User Manual
Contents
1
2
3
Overview
7
1.1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
1.2
Functionalities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
1.3
The big picture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
Installation
2.1
Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2
Install Comete toolset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3
Install Comete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3.1
Install from pre-compiled binaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3.2
Install from sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Programming model
3.1
3.2
3.3
3.4
4
10
12
Cecilia ADL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.1.1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.1.2
Grammar Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Cecilia IDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.2.1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.2.2
Basic Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.2.3
Cecilia IDL Grammar Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
ThinkMC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.3.1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.3.2
Grammar Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Execution model
CONTENTS
21
Copyright STMicroelectronics 2008
4
5
Comete User Manual
Usage
5.1
5.2
5.3
6
22
Using the deployer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.1.1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.1.2
Deployment information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.1.3
Writing the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.1.4
Compiling the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Using the Component Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.2.1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.2.2
Writing the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.2.3
Compiling the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Executing Comete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
References
32
6.1
Compiler usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
6.2
APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.3
6.4
6.2.1
Deployer API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.2.2
Component manager API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Available bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
6.3.1
CBST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
6.3.2
Remote Procedure Call (RPC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Available platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.4.1
Multi-threaded platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.4.2
Multi-process platform on TCP/IP network . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.4.3
Traviata board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
6.4.4
xSTream architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
CONTENTS
Copyright STMicroelectronics 2008
5
Comete User Manual
History of changes
Author(s)
Germain Haugou
CONTENTS
Date
2008-11-03
Version
1.0
Description
Initial document
Copyright STMicroelectronics 2008
6
Comete User Manual
References
[1] The latest version of this document is available at http://mpcom.codex.cro.st.com/
minus-site/1.2-alpha-1/comete/Comete_userManual.pdf.
[2] CBST programming model: Available at http://mpcom.codex.cro.st.com/minus-site/1.
2-alpha-1/comete/CBSTxST-0_7.pdf.
REFERENCES
Copyright STMicroelectronics 2008
7
Comete User Manual
Chapter 1
Overview
1.1
Introduction
Comete is a middleware targetting the deployment of component-based applications over distributed resources.
The current supported component model is the Cecilia one. Cecilia is a development environment for programming
Fractal components on top of the C programming language. You can get more details on the Cecilia site at http:
//fractal.objectweb.org/cecilia-site/current.
The particularity of Comete is to target a wide range of platform, from TCP/IP networks to System On Chip
platforms.
1.2
Functionalities
Here are some of the things you can do with Comete:
• Deploy a component-based application on distributed processing elements.
• Undeploy applications.
• Dynamically decide when an application must be deploy or undeployed.
• Manage the deployment of several applications.
• Connect deployed applications together in order to build complex application schemes.
• Reconfigure deployed applications during their execution by modifying their connections.
1.3
The big picture
The figure 1.1 gives an overview of what Comete does:
1. First, you write your application using the Cecilia component model. This includes writing:
Overview
Copyright STMicroelectronics 2008
8
Comete User Manual
- Architecture Definition Language (ADL) files: they describe the architecture of you application, i.e. all
the components constituting the application and their connections.
- Interface Definition Language (IDL) files: for each connection between two components, you need to
specify the type of this connection, i.e. the different methods that can be called through this connection
and the prototype of each method.
- Implementation (C) files: these files are the code that implements the components of your application.
A component code can be a classical C code if the component has no interaction with the other components, otherwise, you can see on figure 1.1 two particular constructions that allows to interact with
other components:
- A METHOD macro that can be used to implement the method of a server interface of the component. This code will be executed when this method will be called by a client component connected
to this server interface.
- A CALL macro that can be used to call the method of a client interface of the component. This
will have the effect of calling the method of the server interface connected to this client interface.
2. Then, you deploy your application during the execution. Comete will take care of deploying each subcomponent of your application on the processing elements you specified and will also take care of binding
them together, i.e make all the initializations required for the remote connection.
1.3 The big picture
Copyright STMicroelectronics 2008
9
Comete User Manual
Figure 1.1: Comete overview
1.3 The big picture
Copyright STMicroelectronics 2008
10
Comete User Manual
Chapter 2
Installation
2.1
Requirements
- You need a Java Development Kit (tested with version 1.6.0_06).
- You need Python version 2.5 or above (tested with version 2.5.2).
2.2
Install Comete toolset
1. Get the toolset at http://mpcom.codex.cro.st.com/minus-site/1.2-alpha-1/comete/
downloads/toolset-1.1-alpha-6.tar.gz
2. Unpack it:
t a r x v f z t o o l s e t −1.1− a l p h a −6. t a r . gz
3. Set the environment variable COMETE_HOME to the directory where the toolset has been unpacked (this
directory must contain a directory named ’comete’).
4. Append ${COMETE_HOME}/comete/bin to your PATH environment variable.
5. Get Comete tools at http://mpcom.codex.cro.st.com/maven2/org/objectweb/think/
minus/tools/tools/1.3/tools-1.3-bin.tar.gz
6. Unpack it in the directory containing the toolset:
cd $ {COMETE_HOME}
t a r x v f z t o o l s −1.3− b i n . t a r . gz
Installation
Copyright STMicroelectronics 2008
11
Comete User Manual
2.3
2.3.1
Install Comete
Install from pre-compiled binaries
This is the easiest way of getting Comete.
Comete binaries are provided through several packages. One package contains all the required binaries for one
version of Comete. There is one version for each supported combination of platforms, optional functionalities,
environment, etc...
The binaries contained into one of these packages were compiled with a given environment and may not suit yours.
In this case, you have to compile Comete from its sources, see the next section for that.
To install Comete binaries:
1. Get the requested packages at http://mpcom.codex.cro.st.com/minus-site/1.
2-alpha-1/comete/index.html.
For example, you can try with the package http://mpcom.codex.cro.st.com/minus-site/
1.2-alpha-1/comete/downloads/pthread.debug-1.1-alpha-6.car which provides
Comete binaries for a pthread platform.
2. Unpack them to the ${COMETE_HOME}/comete directory with the jar archiver. For the pthread.debug
platform:
cd $ {COMETE_HOME} / c o m e t e
j a r x v f p t h r e a d . debug −1.1− a l p h a −6. c a r
2.3.2
Install from sources
1. Get Comete sources at http://mpcom.codex.cro.st.com/minus-site/1.2-alpha-1/
comete/downloads/comete-1.1-alpha-6-src.tar.gz.
2. Unpack them to a new directory:
m k d i r comete−s o u r c e s
cd comete−s o u r c e s
t a r x v f z comete −1.1− a l p h a −6− s r c . t a r . gz
3. Compile Comete. The target that you must specify to the make program is the version of Comete you want
to compile plus “.compile”. For example, for the pthread.debug version, you need to type:
cd comete −1.1− a l p h a −6
make p t h r e a d . debug . c o m p i l e
4. Install the binaries:
cp −r t a r g e t / p t h r e a d . debug / c o m e t e $COMETE_HOME
2.3 Install Comete
Copyright STMicroelectronics 2008
12
Comete User Manual
Chapter 3
Programming model
The only supported programming model is the Cecilia one. All the following documentations and more details can
be found at http://fractal.objectweb.org/cecilia-site/current/programming.html.
3.1
3.1.1
Cecilia ADL
Overview
The Cecilia ADL Language is an extension of the Fractal ADL language. Basically, the latter is an extensible XML
based language which allows the programmer to describe software configurations in terms of interfaces, attributes,
component compositions and bindings.
3.1.2
Grammar Specification
The ADL has a very simple XML structure and a straightforward grammar.
In the following description, optional XML attributes will be indicated in italic.
definition
: a component architecture definition
attributes:
• name: the name of the component definition
• arguments: the comma separated argument names which can customize the definition
• extends: specifies the comma separated names of the extended definitions
sub-elements: comment*, interface*, component*, binding*, content?, attributes?, controller?, output?
component
a component instance definition
attributes:
Programming model
Copyright STMicroelectronics 2008
13
Comete User Manual
• name: the name of the component instance
• definition: specifies the comma separated names of the component definitions
sub-elements: comment*, interface*, component*, binding*, content?, attributes?, controller?, templatecontroller?, logger?, virtual-node?, coordinates*, output?
interface a component interface definition
attributes:
•
•
•
•
•
name: the name of the interface
role: the role of the interface, which can be client or server
signature: the signature name of the interface
contingency: indicates if the interface is mandatory or optional. Default is mandatory
cardinality: indicates if the interface accepts multiple connections (collection) or not (singleton). Default is
singleton.
sub-elements: comment*
binding
a binding definition
attributes:
• client: the component interface acting as client for this binding
• server: the component interface acting as server for this binding
sub-elements: comment*
attributes component attribute set definition
attributes:
• signature: the signature name of the attribute structure
sub-elements: comment*, attribute*
attribute attribute assignment definition
attributes:
• name: the name of the attribute field
• value: the value of the attribute field
sub-elements: comment*, [Parsed Character DATA]
Parsed Character DATA and a ’value’ attribute of the attribute XML element cannot be simultaneously present.
3.1 Cecilia ADL
Copyright STMicroelectronics 2008
14
Comete User Manual
controller controller generator specification. If this tag is not used, a default controller generator will be used.
attributes:
• desc: the descriptor of the controller generator
• lang: the language in which the controller interfaces must be implemented by the generator. By default, the
language value is the same as the content implementation language.
sub-elements: comment*
content primitive component implementation specification
attributes:
• class: the implementation file name without its language indicator extension
• language: specifies the language of the implementation file
sub-elements: comment*, include*, cflag*, ldflag*
include a file making part of the implementation module of the component. The file that is referenced with this
tag will be considered as an implementation file. In difference with the content class file, an included file cannot
declare its own instance data but can use the instance data that is defined in the content class.
attributes:
• file: the implementation file name without its language indicator extension
sub-elements: cflag
one or more compilation flags to be passed to the C compiler
attributes:
• value: c-flag to be passed to the C compiler
sub-elements: ldflag one or more linker flags to be passed to the binary object linker
attributes:
• value: ld-flag to be passed to the object linker
sub-elements: -
3.1 Cecilia ADL
Copyright STMicroelectronics 2008
15
Comete User Manual
comment a tag to include commentaries in ADL descriptions
attributes:
• text: the comment text
• language: specifies the language of the comment
sub-elements: -
3.2
3.2.1
Cecilia IDL
Overview
The Cecilia IDL Language is a way to define interfaces in Cecilia, because the C programming language does not
support natively the interface construct.
This IDL is strongly typed. In fact interface descriptions are used by the compilation tool-chain to make type
based analysis to verify the compatibility of interconnected component interfaces, and to generate communication
adaptors for component pairs that can not be naturally bound (JNI, RPC, etc.).
3.2.2
Basic Example
Cecilia IDL supports four types of constructs:
• Interface defines the signature of a component interface. An interface contains a set of methods. Each method
must have a distinct name. Optionally, an interface can extends another interface (multiple inheritance is not
allowed). Finally, an interface may define constants;
• Record defines a structured type. It contains a set of fields. Each field has a type and a name. Records are
used to define component attributes and can also be used as method parameter or return types.
• Enum (since Cecilia 1.2) defines an enumerated type. It contains a set of members. Each field has a name
and optionally a value. Enums can be used as interfaces method parameter types and also as method return
types.
• Union (since Cecilia 2.0) defines a union type. It contains a set of fields. Each field has a type and a name.
Unions can be used as method parameter or return types.
Each construct definition must be done in a separate file. The extension used for these files is .idl. The file name
must correspond to the construct name which is defined in the file, and each IDL definition belongs to a package.
The package name must correspond to the path in the file system.
An IDL definition can reference a type which is defined in another IDL definition. To this end, two kinds of
identifiers may be used, a simple identifier or a qualified identifier. A qualified identifier corresponds to <package>.<interface> giving the absolute description of the IDL definition. An identifier corresponds only to <interface>, and may be considered as a relative path. An single identifier can be used to reference an IDL type which is
defined in the same package. Otherwise, one may import the qualified identifier to use then an identifier in the IDL
definition. Note that the imported identifiers overload the identifiers found in the same package.
The following IDL definition specifies an interface, called Printer, in the package video.api, which provides two
distinct methods, one providing a print operation for a character, and the other for a string.
3.2 Cecilia IDL
Copyright STMicroelectronics 2008
16
Comete User Manual
/ / f i l e = video / api / P r i n t e r . i d l
package video . api ;
public interface Printer {
void printChar ( char c ) ;
void p r i n t S t r i n g ( s t r i n g s ) ;
}
The following IDL definition defines a record called ServiceAttributes in the package attributes which has two
integer fields respectively called cols and rows.
// file = service / ServiceAttributes . idl
package a t t r i b u t e s ;
record ServiceAttributes {
int cols ;
i n t rows ;
}
The following IDL defintion defines a DayOfTheWeek enumerated type in the package days, which has 7 members,
named after the days of the week.
/ / f i l e = d a y s / DayOfTheWeek . i d l
package days ;
enum DayOfTheWeek {
MONDAY,
TUESDAY,
WEDNESDAY,
THURSDAY,
FRIDAY ,
SATURDAY,
SUNDAY
}
The following IDL defintion defines a Handle union type in the package system, which has an integer field and a
pointer field.
/ / f i l e = system / Handle . i d l
package system ;
enum H a n d l e {
uint32_t handle ;
any p t r ;
}
3.2 Cecilia IDL
Copyright STMicroelectronics 2008
17
3.2.3
Comete User Manual
Cecilia IDL Grammar Specification
Common grammar elements The very first element of the IDL language consists in the identifiers. As explained
above, two kinds of identifiers are supported : qualified identifier and the simple identifier. The simple identifier
corresponds to a string corresponding to a classical C identifier (starting with an alphabetical character and not
containing arithmetical or boolean operator characters). A qualified identifier is a list of identifiers, connected with
points.
QualifiedIdentifier ::=
( I d e n t i f i e r ( " . " I d e n t i f i e r )∗ )
An IDL declaration starts with a package clause, followed by a list of import clauses, and contain one interface
definition or one record definition or one enumeration definition.
D e c l a r a t i o n : : = Package ( Import )∗ ( I n t e r f a c e D e c l a r a t i o n | R e c o r d D e c l a r a t i o n | EnumDeclar
Package
: : = " package " Q u a l i f i e d I d e n t i f i e r ;
Import
::= " import " Q u a l i f i e d I d e n t i f i e r ;
Another common element is the supported types. We distinguish between primitive types corresponding to keywords defined in the IDL language, and the complex types that are defined in other IDL definitions.
Type
: : = P r i m i t i v e T y p e | ComplexType
ComplexType
: : = Q u a l i f i e d I d e n t i f i e r | " any "
PrimitiveType
::= (
" boolean "
|
" char "
|
" byte "
|
" short "
|
" int "
|
" long "
|
" unsigned byte "
|
" unsigned short "
|
" unsigned i n t "
|
" unsigned long "
|
" float "
|
" double "
|
"( u ?) i n t ( 8 | 1 6 | 3 2 | 6 4 ) _t "
|
"( u ?) i n t _ l e a s t ( 8 | 1 6 | 3 2 | 6 4 ) _t " |
"( u ?) i n t _ f a s t ( 8 | 1 6 | 3 2 | 6 4 ) _t " |
"( u ?) i n t p t r _ t "
|
"( u ?) intmax_t "
|
" string " )
Primitive and complex types are mapped to the C types as described in the Cecilia IDL to C page. Interface
definition grammar
An interface type declaration identified by Identifier contains two sorts of declarations: methods and constant fields.
The keyword "public" isn’t relevant and is only here for compatibility purpose.
InterfaceDeclaration
::=
(
MethodDeclaration
|
3.2 Cecilia IDL
" p u b l i c "? " i n t e r f a c e " I d e n t i f i e r "{"
Copyright STMicroelectronics 2008
18
Comete User Manual
FieldDeclaration
";"
)∗
|
"}"
The grammar of a method declaration is given below. The keyword "..." is used for passing arbitrary parameters
number. The optional "in", "out", "in_out" (default to "in") specify parameter passing modes, and allow the IDL
compiler to map the operations to the target programming language, accordingly to the language capabilities. See
the IDL to C Mapping page for a practical description of the mapping procedure from Cecilia IDL to C.
MethodDeclaration
: : = ResultType I d e n t i f i e r FormalParameters " ; "
ResultType
: : = Type | " v o i d "
FormalParameters
::=
"("
FormalParameter
( " ," FormalParameter )∗
( " ," " . . . " )?
")"
FormalParameter
::=
( " i n " | " o u t " | " i n _ o u t " ) ? Type I d e n t i f i e r
A constant field declaration grammar looks like this. The expression must be a valid constant expression and only
a primitive type can be assigned as a constant. No semantic check on the expression is done by the IDL compiler.
FieldDeclaration
::=
PrimitiveType I d e n t i f i e r = Expression ";"
Record definition grammar
The grammar of the record definition is given below. A record can contain any type.
RecordDeclaration
: : = " r e c o r d " I d e n t i f i e r "{
( B a s i c F i e l d D e c l a r a t i o n )∗
"}"
BasicFieldDeclaration
: : = Type I d e n t i f i e r " ; "
Enum definition grammar
The grammar of the enum definition is given below. A enum must contain one or more members, each of them can
optionally specify a value. Note that for enum definitions import statements have no meaning.
EnumDeclaration
: : = " enum " I d e n t i f i e r " {
( EnumMemberDeclaration )
( " , " EnumMemberDeclaration ) ∗
"}"
EnumMemberDeclaration : : =
I d e n t i f i e r ( " : " Expression )?
Union definition grammar
The grammar of the union definition is given below. An union can contain any type.
UnionDeclaration
: : = " union " I d e n t i f i e r "{
( B a s i c F i e l d D e c l a r a t i o n )∗
"}"
BasicFieldDeclaration
: : = Type I d e n t i f i e r " ; "
3.2 Cecilia IDL
Copyright STMicroelectronics 2008
19
Comete User Manual
3.3
ThinkMC
3.3.1
Overview
The purpose of thinkMC is to abstract the C programmer from the conventions and the definition of data structures
while implementing primitive components for Cecilia. Although allowing the programmer to manipulate concepts
alien to standard C language, thinkMC is not however a new language, and promotes the use of standard C and
related standard C compilation chains as available with target processors.
3.3.2
Grammar Specifications
Following subsections provide the specification of the thinkMC language constructs.
Implementation file The implementation file must be called with the name that has been used in the specification
of the component in ADL. The extension of the file must be ".c". The content of the file must follow the below
structure.
IMPLEMENTATION : : = DECLARE_DATA "# i n c l u d e < c e c i l i a . h >" (METHOD) ∗
Instance data declaration The declaration of instance data of components is made using the DECLARE_DATA
construct whose structure is given below. This declaration must be done even if the component does not have any
instance data. Instance data of a component is formed by a set of fields (The content of the DECLARE_DATA
construct is equivalent to the definition of a C structure).
DECLARE_DATA : : = "DECLARE_DATA { "
( F i e l d D e c l a r a t i o n )∗
"}";
Method implementation A primitive component implementation file must contain the implementations of each
method of each interface that is provided by the component. There are two issues to consider for method implementations:
* declaring the signature of the method with a specific construct called METHOD, * must accept as first parameter
of the method a void pointer which is called _this. The structure of the method implementation is given below.
METHOD : : = r e t u r n T y p e "METHOD( " i n t e r f a c e N a m e " , " methodName " ) ( v o i d ∗ _ t h i s , "
( " , " argument )∗ " ) "
"{"
ImplementationCode
"}"
Method invocation Components can invoke methods that are provided by other components through their client
interfaces. To this end, a CALL construct has been defined whose structure is given below.
"CALL ( " i n t e r f a c e P o i n t e r " , " methodName ( " , " p a r a m e t e r ) ∗ " ) ; "
3.3 ThinkMC
Copyright STMicroelectronics 2008
20
Comete User Manual
The first argument of the CALL construct is an interface reference (i.e. a pointer to an interface). See next section
to know how to get references to client interfaces.
WARNING: The CALL construct is NOT RECURSIVE. It means that the parameter list cannot contains inner
usage of CALL.
Access to client interfaces Components can access their client interfaces using the REQUIRED construct. The
structure of this construct is given below.
"REQUIRED . " i n t e r f a c e N a m e
To invoke a method of on a client interface the construct is
CALL(REQUIRED.interfaceName, methodName, parameters...)
Access to instance data Components can access the instance data that has been declared in the DECLARE_DATA
construct, using the DATA construct. The structure of this construct is given below.
"DATA . " f i e l d N a m e
Access to attributes Components can access their attributes using the ATTRIBUTES construct. The structure of
this construct is given below.
"ATTRIBUTES . " f i e l d N a m e
Invocation of self method Components can invoke their own server interface using the CALLMINE construct.
The structure of this construct is given below.
"CALLMINE ( " s e r v e r I n t e r f a c e N a m e " , " methodName ( " , " p a r a m e t e r ) ∗ " ) ; "
This construct only works on server interfaces that are actually implemented by the implementation code (i.e.
functional code). To invoke methods on a controller interface use the GET_MY_INTERFACE and the CALL
constructs.
Access to server interfaces Components can retrieve a reference to their server interfaces using the
GET_MY_INTERFACE construct. The structure of this construct is given below.
"GET_MY_INTERFACE ( " i n t e r f a c e N a m e " ) "
For instance to invoke the bindFc method of the binding-controller interface of the component itself, use the following code:
CALL( GET_MY_INTERFACE ( b i n d i n g _ c o n t r o l l e r ) , b i n d F c ,
3.3 ThinkMC
...
);
Copyright STMicroelectronics 2008
21
3.4
Comete User Manual
Example
You can find a helloworld example at http://fractal.objectweb.org/cecilia-examples-site/
current/helloworld/index.html.
3.4 Example
Copyright STMicroelectronics 2008
22
Comete User Manual
Chapter 4
Execution model
The execution model is the one defined by the CBST programming model described in [2]
Execution model
Copyright STMicroelectronics 2008
23
Comete User Manual
Chapter 5
Usage
There are two ways of using Comete.
- A high-level one which makes use of a component called the deployer.
- A low-level high which makes use of a component called the component manager.
5.1
5.1.1
Using the deployer
Overview
The Deployer is not part of Comete. It is an extension to Comete provided in order to ease the deployment of
distributed applications.
The figure 5.1 gives an overal picture of the runtime when the deployer is used.
In this figure, we can basically share the functionalities between 3 main components.
Application loader This component is the one that takes the deployment decisions. The application integrator
has to write this component as he is the one who knowns when each application must be deployed or undeployed.
This component can be for example commanded by a shell, which enables the user to ask for application start or
stoping.
Deployer This component is the one that knowns how to deploy the different applications. This means that for
each application, it knowns which are the sub-component that must be deployed on the different processing elements
and how they must be bounded when the application is asked to be deployed. The only information that is required
when it is asked to deploy an application is the platform mapping, i.e. on which processing elements the different
sub-components must be deployed.
Component manager This component is the one that knowns what must be done when a component must be
deployed or bounded. Contrary to the deployer that knowns how to deploy an entire application made of several
binaries, the component manager only knows how to deploy a single binary.
Usage
Copyright STMicroelectronics 2008
24
Comete User Manual
Figure 5.1: Comete scheme using the deployer
The figure 5.2 describes the process for using the deployer.
Figure 5.2: Comete compilation using the deployer
Top ADL file A top ADL file must written. This file describes all the applications that can be deployed during
the execution. It details of which components each application is made, how they must be deployed and bounded
together on the whole platform. It also contains the application loader. In this component, you need to specify when
each application will be deployed or undeployed. A default loader can be generated automaticaly if you only need
to deploy applications that will lives during the whole execution.
5.1 Using the deployer
Copyright STMicroelectronics 2008
25
Comete User Manual
Top ADL compilation This top ADL file must be compiled using the Comete toolset (based on Cecilia). The
compilation will produce all the binaries that are required for the deployment of the described applications. In
particular, it will generate and compile the deployer. All the produced binaries are hold in a repository which is
accessed during the execution when an application is deployed.
5.1.2
Deployment information
The figure 5.3 shows the architecture of a classical Cecilia application.
Figure 5.3: Classical Cecilia application
A top component contains several layers of sub-components and bindings which forms a component-based application.
The figure 5.4 shows the architecture of a deployable application, i.e. a classical Cecilia application enriched with
deployment information.
Figure 5.4: Deployable application
To become a deployable application, a Cecilia application must be enriched with three information.
5.1 Using the deployer
Copyright STMicroelectronics 2008
26
Comete User Manual
The processing element (PE) mapping This describes how the application must be distributed on the processing
elements. This is done by splitting the application into several pieces and by assigning a processing element to
each piece. This processing element is a virtual one and will be translated to the real one when the application is
deployed. This allows to deploy several times the same application with differents mappings. Each piece is a binary
that will be dynamically loaded when it the corresponding component is deployed.
The protocol for remote bindings A remote binding is a connection between two components of different processing elements. As such bindings need more handling than local bindings, they need to be assigned a protocol
that will described how the binding must be handled.
The start order This specifies the order in which the components must be started. Components will be started
from the lower value to the higher. This information is facultative. Components with no start order will be started
in last.
5.1.3
Writing the application
Cecilia version
an application:
First you need to write your application using the Cecilia framework. Here is an example of such
<? xml v e r s i o n = " 1 . 0 " e n c o d i n g = " ISO−8859−1" ? >
< !DOCTYPE d e f i n i t i o n PUBLIC " −// o b j e c t w e b . o r g / / DTD F r a c t a l ADL 2 . 0 / / EN"
" c l a s s p a t h : / / o r g / o b j e c t w e b / f r a c t a l / c e c i l i a / a d l / p a r s e r / xml / c e c i l i a . d t d " >
< d e f i n i t i o n name= " A p p l i c a t i o n " >
< component name= " v i e w e r " d e f i n i t i o n = " a p p l i . Viewer " / >
< component name= " d e c o d e r " d e f i n i t i o n = " a p p l i . D e c o d e r " / >
< binding c l i e n t =" decoder . o u t p u t " s e r v e r =" viewer . i n p u t " / >
</ definition>
Deployable version Then you need to add the information described in section 5.1.2. For that, you need to respect
the following constraints:
- Any fractal file that contains a deployment information must use the following DTD:
<? xml v e r s i o n = " 1 . 0 " ? >
< !DOCTYPE d e f i n i t i o n PUBLIC " −// o b j e c t w e b . o r g / / DTD F r a c t a l ADL 2 . 0 / / EN"
" c l a s s p a t h : / / o r g / o b j e c t w e b / f r a c t a l / c o m e t e / a d l / xml / d e p l o y m e n t . d t d " >
- Each component which is assigned a processing element must be completly defined by a definition name, i.e.
not using inheritance or redefinition.
A processing element is assigned by adding an attribute pe to a component node. This attribute must be assigned
the processing element number.
A protocol is assigned by adding an attribute protocol to a binding node. This attribute must be assigned the protocol
name.
A startOrder is assigned by adding an attribute startOrder to a component node. This attribute must be assigned an
integer.
Here is an example of the previous application enriched with depployment information:
5.1 Using the deployer
Copyright STMicroelectronics 2008
27
Comete User Manual
<? xml v e r s i o n = " 1 . 0 " ? >
< !DOCTYPE d e f i n i t i o n PUBLIC " −// o b j e c t w e b . o r g / / DTD F r a c t a l ADL 2 . 0 / / EN"
" c l a s s p a t h : / / o r g / o b j e c t w e b / f r a c t a l / c o m e t e / a d l / xml / d e p l o y m e n t . d t d " >
< d e f i n i t i o n name= " D e p l o y a b l e A p p l i c a t i o n " e x t e n d s = " A p p l i c a t i o n " >
< component name= " v i e w e r " pe = " 0 " s t a r t O r d e r = " 1 " / >
< component name= " d e c o d e r " pe = " 1 " s t a r t O r d e r = " 0 " / >
< binding c l i e n t =" decoder . o u t p u t " s e r v e r =" viewer . i n p u t " p r o t o c o l =" c b s t " / >
</ definition>
Application loader Finally, you need to write the application loader, i.e. the component that will take the deployment decisions for your applications.
If you only need to deploy your applications at system startup and let them live, you don’t need to write the
application loader, it will be automatically generated.
Otherwise, you need to:
1. Add the system component. This component is just an abstract component modeling Comete. It will enable
to connect application components to Comete services such as the component manager or the allocator. Just
add the following code in your top component:
< component name= " s y s t e m " t e m p l a t e = " s y s t e m " d e f i n i t i o n = " c o m e t e . System " / >
2. Write your application loader. The following constraints must be respected:
- It must have the attribute template=’’loader’’. This just means that this component will be the first one
instantiated by Comete.
- It must have a server entry interface. This is the interface which is called when the component is entered.
- It must have a client deployer interface.
Here is an example of loader for the previous application:
< d e f i n i t i o n name= " L o a d e r " >
< i n t e r f a c e name= " a l l o c a t o r " r o l e = " c l i e n t " s i g n a t u r e = " memory . a p i . A l l o c a t o r " / >
< i n t e r f a c e name= " e n t r y " r o l e = " s e r v e r " s i g n a t u r e = " b o o t . a p i . Main " / >
< i n t e r f a c e name= " componentManager " r o l e = " c l i e n t " s i g n a t u r e = " c o m e t e . g e n e r i c . a p i . ComponentManager "
contingency =" o p t i o n a l " / >
< i n t e r f a c e name= " end " r o l e = " s e r v e r " s i g n a t u r e = " End " / >
< component name= " l o a d e r " >
< i n t e r f a c e name= " e n t r y " r o l e = " s e r v e r " s i g n a t u r e = " b o o t . a p i . Main " / >
< i n t e r f a c e name= " d e p l o y e r " r o l e = " c l i e n t " s i g n a t u r e = " c o m e t e . D e p l o y e r " / >
< i n t e r f a c e name= " end " r o l e = " s e r v e r " s i g n a t u r e = " End " / >
< c o n t e n t c l a s s = " l o a d e r " l a n g u a g e = " thinkMC " / >
< / component >
< component name= " d e p l o y e r " t e m p l a t e = " d e p l o y e r " d e f i n i t i o n = " c o m e t e . D e p l o y e r " / >
<binding
<binding
<binding
<binding
<binding
c l i e n t =" deployer . a l l o c a t o r " s e r v e r =" t h i s . a l l o c a t o r " / >
c l i e n t =" t h i s . e n t r y " s e r v e r =" l o a d e r . e n t r y " / >
c l i e n t = " d e p l o y e r . componentManager " s e r v e r = " t h i s . componentManager " / >
c l i e n t =" l o a d e r . deployer " s e r v e r =" deployer . deployer " / >
c l i e n t = " t h i s . end " s e r v e r = " l o a d e r . end " / >
</ definition>
It is made of two sub-components:
(a) The loader itself.
5.1 Using the deployer
Copyright STMicroelectronics 2008
28
Comete User Manual
(b) The deployer. This component is the deployer described previously. It will be automatically generated
and will contain the description of your applications, allowing it to deploy them according to the orders
coming from the application loader. You can see that the deployer is connected to the component
manager as it needs to deploy and bind the sub-components of the applications it is asked to deploy.
You have to add the loader in the top ADL file:
<? xml v e r s i o n = " 1 . 0 " e n c o d i n g = " ISO−8859−1" ? >
< !DOCTYPE d e f i n i t i o n PUBLIC " −// o b j e c t w e b . o r g / / DTD F r a c t a l ADL 2 . 0 / / EN"
" c l a s s p a t h : / / o r g / o b j e c t w e b / f r a c t a l / c e c i l i a / a d l / p a r s e r / xml / c e c i l i a . d t d " >
< d e f i n i t i o n name= " D e p l o y a b l e A p p l i c a t i o n " >
< component name= " s y s t e m " t e m p l a t e = " s y s t e m " d e f i n i t i o n = " c o m e t e . System " / >
< component name= " l o a d e r " t e m p l a t e = " l o a d e r " d e f i n i t i o n = " L o a d e r " / >
< component name= " a p p l i c a t i o n " d e f i n i t i o n = " D e p l o y a b l e A p p l i c a t i o n " / >
< binding c l i e n t =" l o a d e r . a l l o c a t o r " s e r v e r =" system . a l l o c a t o r " / >
< b i n d i n g c l i e n t = " l o a d e r . componentManager " s e r v e r = " l o a d e r . componentManager " / >
</ definition>
3. Write the application loader implementation. The way to write it is the Cecilia one. You need to implemente
the entry interface using the deployer API. Here is an example for the previous application:
DECLARE_DATA {
};
# i n c l u d e < c e c i l i a . h>
v o i d METHOD ( entry , main ) ( v o i d ∗_this , jint argc , c h a r ∗∗argv ) {
i n t cpuMapping1 [ 2 ] = { 0 , 1 } ;
i n t cpuMapping2 [ 2 ] = { 1 , 2 } ;
i n t cpuMapping3 [ 2 ] = { 2 , 3 } ;
v o i d ∗instance1 , ∗instance2 , ∗instance3 ;
CALL ( REQUIRED . deployer , deploy , " a p p l i c a t i o n " , &cpuMapping1 , &instance1 ) ;
CALL ( REQUIRED . deployer , deploy , " a p p l i c a t i o n " , &cpuMapping2 , &instance2 ) ;
CALL ( REQUIRED . deployer , deploy , " a p p l i c a t i o n " , &cpuMapping3 , &instance3 ) ;
CALL ( REQUIRED . deployer , start , instance1 ) ;
CALL ( REQUIRED . deployer , start , instance2 ) ;
CALL ( REQUIRED . deployer , start , instance3 ) ;
}
This code will deploy 3 instances of the same application, each one with a different platform mapping.
We’ve just seen the instantiation of a single application, but it is possible to declare several applications in the ADL
file and bind them together. Look at the deployer API for more details.
5.1.4
Compiling the application
Compiling a distributed application using the deployer is quite easy as you just need to compile the fractal file that
describes the deployment scheme (one call to the compiler will produce all the binaries). See section 6.1 for details
on compiler usage.
5.1 Using the deployer
Copyright STMicroelectronics 2008
29
Comete User Manual
5.2
5.2.1
Using the Component Manager
Overview
The figure 5.5 gives an overal picture of the runtime when the component manager is used.
Figure 5.5: Comete scheme using the component manager
This figure shows that using the component manager is similar to using the deployer except that:
- There is no deployer. The application is directly connected to the component manager. This means the
application loader must ask the deployment of each binary constituting the application to be deployed.
- We must take care of the stub and skeletons. The stubs and the skeletons are the components that are needed
when two components of different processing elements are bounded together. The only thing to take care
about them is to compile them and make sure that they are accessible at runtime when they are needed.
The figure 5.6 describes the process for using the component manager.
On this figure, we can see 3 kinds of objects that need to be compiled:
- The application sub-components. Each sub-component which will be deployed through a component manager call must be compiled separatly.
- The application loader.
- The IDLs. Each IDL used in a remote binding must be compiled. This will produce a stub and a skeleton that
will be used at runtime when the associated binding is asked.
5.2 Using the Component Manager
Copyright STMicroelectronics 2008
30
Comete User Manual
Figure 5.6: Comete compilation flow using the component manager
5.2.2
Writing the application
Application sub-components A component definition must be written for each sub-component of the application
that the component manager will be asked to deploy.
The figure 5.7 shows the example introduced in the previous section when the component manager is used:
Figure 5.7: Distributed application
A top ADL gathering all the sub-components is not needed in this case, as only the sub-components will be given
to the compiler.
Application loader The application loader must respect the following constraints:
- It must have a server entry interface. This is the interface which is called when the component is entered.
5.2 Using the Component Manager
Copyright STMicroelectronics 2008
31
Comete User Manual
- It must have a client componentManager interface. This interface will be automatically bounded to the
component manager when the application loader is instantiated.
- Its binary name must be loader, as it will be automatically instantiated after Comete startup.
In our example, the application loader is:
< d e f i n i t i o n name= " l o a d e r " >
< i n t e r f a c e name= " e n t r y " r o l e = " s e r v e r " s i g n a t u r e = " minus . common . g e n e r i c . a c t i v i t y . a p i . Main " / >
< i n t e r f a c e name= " componentManager " r o l e = " c l i e n t " s i g n a t u r e = " c o m e t e . g e n e r i c . a p i . ComponentManager " / >
< c o n t e n t c l a s s = " l o a d e r " l a n g u a g e = " thinkMC " / >
< / component >
The implementation of the application loader must respect the Cecilia syntax. It must implement the entry interface
and make use of the component manager API for deploying and binding the sub-components of the application.
Here is an example of application loader:
DECLARE_DATA {
};
# i n c l u d e < c e c i l i a . h>
v o i d METHOD ( entry , main ) ( v o i d ∗_this , jint argc , c h a r ∗∗argv ) {
i n t instance1 , instance2 , instance3 ;
CALL ( REQUIRED . componentManager , instantiate , " comp1 " ,
0 , &instance1 ) ;
CALL ( REQUIRED . componentManager , instantiate , " comp2 " ,
1 , &instance2 ) ;
CALL ( REQUIRED . componentManager , instantiate , " comp3 " ,
2 , &instance3 ) ;
CALL ( REQUIRED . componentManager , bind , instance1 , " i t f 1 " ,
instance2 , " i t f 1 " , comete_generic_api_ComponentManager_BIND_CBST ) ;
CALL ( REQUIRED . componentManager , bind , instance2 , " i t f 2 " ,
instance3 , " i t f 1 " , comete_generic_api_ComponentManager_BIND_CBST ) ;
CALL ( REQUIRED . componentManager , start , instance3 ) ;
CALL ( REQUIRED . componentManager , start , instance2 ) ;
CALL ( REQUIRED . componentManager , start , instance1 ) ;
}
This piece of code instantiates, binds and starts an application made of 3 sub-components, each one deployed on a
different processing element and bounded together.
5.2.3
Compiling the application
Compiling a distributed application without using the deployer is much more complex than when it is used as each
single binary needs to be compiled separatly through a compiler call.
Compiling the ADLs You need to compile each ADL that will be deployed through a component manager call.
Compiling them is similar to compiling the application as it was done in the previous section except that you have
to call several times the compiler. See section 6.1 for details on compiler usage.
Compiling the IDLs You need to compile each IDL which is used in a remote connection. For that you need to
compile for each of these IDLs a stub and a skeleton.
You must respect the following constraints:
5.2 Using the Component Manager
Copyright STMicroelectronics 2008
32
Comete User Manual
• The ADL to be compiled must be minus.bare.generic.exportbind.<bindingType>.lib.<stubSkel>(<idlName>)
where:
– <bindingType> is either cbst or rpc
– <stubSkel> is either stub or skeleton
– <idlName> is the name of the IDL without the .idl extension with all . replaced by _.
• The binary name must be <bindingType>_<stubSkel>_<idlName> where:
– <bindingType> is either CBST or RPC
– <stubSkel> is either STUB or SKEL
– <idlName> is the name of the IDL without the .idl extension with all . replaced by _.
5.3
Executing Comete
A tool for running Comete applications named runtarget is provided within the Comete package. If you followed
the instructions in section 2, this tool should be in your path.
It is used with the following command-line arguments:
r u n t a r g e t −− t a r g e t = c o m e t e . < c o m e t e V e r s i o n > −−w o r k P a t h =< workPath >
where cometeVersion is the platform on which you want to launch Comete and your applications and workPath is
the directory path where all the application binaries were put.
cometeVersion can be any of:
•
•
•
•
•
•
pthread: the pthread platform
pthread.debug: the pthread platform with debug features
procnet: the network of processes
procnet.debug: the network of processes with debug features
stm8010: the Traviate board
xstream.unix: the xSTream architecture
5.3 Executing Comete
Copyright STMicroelectronics 2008
33
Comete User Manual
Chapter 6
References
6.1
Compiler usage
The compiler that must be used to compile distributed Cecilia application is an extension of the classical Cecilia
compiler. The reason is that the classical compiler is not able to compile components that need to be dynamically
loaded.
The extended compiler is called ceciliadync. If you followed the instructions in section 2, this compiler should be
in your path. Its usage is quite the same that the Cecilia compiler.
The ceciliadync compiler compiles a given architecture definition file. It is used with the following command-line
arguments:
c e c i l i a d y n c [ OPTIONS ] ( < d e f i n i t i o n > [ : < b i n p a t h > ] ) +
where definition is the name of the distributed component to be compiled, and binpath is the directory path where
the resulting binaries will be put.
Available options are :
• -h, –help
Print help message and exit.
• -S=path list, –src-path=path list
Specify the search path of ADL,IDL and implementation files in a classpath-like format (see bellow for
detail). This option may be specified several times.
• -o=output path, –out-path=output path
Specify the path where generated files will be put (default is current working directory). The given directory
must exist prior the execution of ceciliac.
• -t=name, –target-descriptor=name
Specify the target descriptor. See target-descriptor page for details on how to define new target descriptors.
• -compiler-command=path
Specify the command of the C compiler (default is gcc).
References
Copyright STMicroelectronics 2008
34
Comete User Manual
• -c=flags, –c-flags=flags
Specify the c-flags compiler directives. This option may be specified several times.
• -I=path list, –inc-path=path list
Specify the list of path to be added in compiler include paths in a classpath-like format. This option may be
specified several times.
• -linker-command=path
Specify the command of the linker (default is gcc).
• -l=flags, –ld-flags=flags
Specify the ld-flags compiler directives. This option may be specified several time.
• -L=path list, –ld-path=path list
Specify the list of path to be added linker library search path in a classpath-like format. This option may be
specified several time.
• -a=path, –archiver-command=path
Specify the command of the archiver tool (default is ar).
• -T=path, –linker-script=path
Specify the linker script to use. The script is searched in the compiler source-path.
• -executable-name=name
Specify the name of the target executable file (can be used only if one and only one ADL is specified).
• -j=number, –jobs=number
Specify the number of concurrent compilation jobs (default is 1).
• -e
When an error occurs, print stack traces.
• -s, –static
Specify that the component must be compiled statically (i.e. using the classical way).
6.2
APIs
6.2.1
Deployer API
The deployer is accessed through its single server interface whose signature is “comete.Deployer” defined by the
following IDL file.
6.2 APIs
Copyright STMicroelectronics 2008
35
Comete User Manual
6.2.1.1
int deploy (string name, int ∗ cpuMapping, out any instance)
Deploy an application according to the given platform mapping. All sub-components of the application are deployed
are all internale bindings are done. Only the interfaces exported by the application are not bounded.
Parameters:
name The name of the application that mus be deployed. This name is the instance name of the application in
the ADL file describing the deployment (the one that is given as input file to the compiler).
cpuMapping A pointer to an array describing the platform mapping. This array will be indexed by the processing elements that are specified in the ADL file describing the deployment in order to get the real
processing elements where each component must be deployed.
instance The pointer to the structure describing the deployed application will be returned in this parameter.
This pointer can be used for further operations on this deployed application such as destruction, starting
or binding.
Returns:
0 If the operation succeeded, 1 if it failed.
6.2.1.2
int undeploy (any instance)
Undeploy an application that was previously deployed. All sub-components and internals bindings are destroyed.
The bindings with exported interfaces of the application need to be destroyed before the application is destroyed
Parameters:
instance The structure pointer that was returned by the deploy method when the application was deployed
Returns:
0 If the operation succeeded, 1 if it failed.
6.2.1.3
int start (any instance)
Start an application that was previously deployed. Each entry interface of each sub-component of the application
will posted to the event engine.
Parameters:
instance The structure pointer that was returned by the deploy method when the application was deployed
Returns:
0 If the operation succeeded, 1 if it failed.
6.2 APIs
Copyright STMicroelectronics 2008
36
Comete User Manual
6.2.1.4
int bind (any fromInstance, string fromItfName, any toInstance, string toItfName, int type)
Bind two application interfaces together.
Parameters:
fromInstance The application owning the client interface (structure pointer returned by the deploy method).
fromItfName The name of the client interface.
toInstance The application owning the server interface (structure pointer returned by the deploy method).
toItfName The name of the server interface.
type The type of the binding.
Returns:
0 If the operation succeeded, 1 if it failed.
6.2.1.5
int unbind (any fromInstance, string fromItfName)
Unbind two application interfaces that was previously bounded
Parameters:
fromInstance The application owning the client interface (structure pointer returned by the deploy method).
fromItfName The name of the client interface.
Returns:
0 If the operation succeeded, 1 if it failed.
6.2.1.6
Member Data Documentation
6.2.1.7
int RPC = 0
RPC: classical Remote Procedure Call.
6.2.1.8
int CBST = 5
CBST: event-based bindings suitable for streaming applications.
6.2.1.9
int CBST_SYS = 9
CBST_SYS: high-priority event-based bindings suitable for streaming applications control.
6.2 APIs
Copyright STMicroelectronics 2008
37
Comete User Manual
6.2.2
Component manager API
The component manager is accessed through its single server
“comete.generic.api.ComponentManager” defined by the following IDL file.
6.2.2.1
interface
whose
signature
is
int instantiate (const string name, int target, int ∗ instance)
Instantiate a component.
Parameters:
name The binary name of the component.
target The processing element where it must be instantiated.
instance The instance ID is returned here.
Returns:
0 If the operation succeeded, 1 if it failed.
6.2.2.2
int destroy (int instance)
Destroy a component. The component must have been stopped and completly unbounded.
Parameters:
name The binary name of the component.
Returns:
0 If the operation succeeded, 1 if it failed.
6.2.2.3
int bind (int clientInstance, const string clientItfName, int serverInstance, const string
serverItfName, int bindType)
Bind two interfaces.
Parameters:
clientInstance The instance ID of the client.
clientItfName The name of the client interface.
serverInstance The instance ID of the server.
serverItfName The name of the server interface.
bindType The type of the binding which can be any of the above constants.
Returns:
0 If the operation succeeded, 1 if it failed.
6.2 APIs
Copyright STMicroelectronics 2008
38
Comete User Manual
6.2.2.4
int unbind (int clientInstance, const string clientItfName)
Unbound two interfaces.
Parameters:
clientInstance The instance ID of the client. The name of the client interface.
6.2.2.5
int start (int instance)
Start a component.
Parameters:
instance The instance ID of the component.
Returns:
0 If the operation succeeded, 1 if it failed.
6.2.2.6
int stop (int instance)
Stop a component.
Parameters:
instance The instance ID of the component.
Returns:
0 If the operation succeeded, 1 if it failed.
6.2.2.7
Member Data Documentation
6.2.2.8
int BIND_RPC = 0
RPC: classical Remote Procedure Call.
6.2.2.9
int BIND_CBST = 5
CBST: event-based bindings suitable for streaming applications.
6.2 APIs
Copyright STMicroelectronics 2008
39
Comete User Manual
6.2.2.10
int BIND_CBST_SYS = 9
CBST_SYS: high-priority event-based bindings suitable for streaming applications control.
6.2.2.11
int BIND_PP = 6
PP: Push Pop bindings.
6.3
6.3.1
Available bindings
CBST
CBST bindings are event-based bindings suitable for streaming application. They are described in [2].
6.3.2
Remote Procedure Call (RPC)
RPC are classical function calls between remote processing elements.
6.4
6.4.1
Available platforms
Multi-threaded platform
This platform is a set of threads, all runnings in the same process. This platform is only available on Linux.
As shown on figure 6.1, each processing element is a pthread.
The communication between all the processing elements is made through shared memory. On this platform, no
memory copy occurs as the pointers are directly exchanged during the calls.
6.4.2
Multi-process platform on TCP/IP network
This platform is a set of processes running on different Linux machines connected by a TCP/IP network.
As shown on figure 6.2, each processing element is a process running on a given machine. Several processing
elements can run on the same machine.
The communication is made through the TCP/IP network. Each call is serialized into packets that are sent through
the network to the receiver. Packets are then deserialized into a call.
6.3 Available bindings
Copyright STMicroelectronics 2008
40
Comete User Manual
Figure 6.1: Multi-threaded platform
Figure 6.2: Multi-process platform on TCP/IP network
6.4.3
Traviata board
This platform is made of 3 CPUs, each one with its own cache and sharing a central memory, and of hardware
mailboxes for communication.
As shown on figure 6.3, each processing element is a CPU.
The communication is made using hardware mailboxes and shared memory. Each call is serialized to the mailbox,
sent to the receiver, and deserialized.
6.4 Available platforms
Copyright STMicroelectronics 2008
41
Comete User Manual
Figure 6.3: Traviata board
6.4.4
xSTream architecture
The xSTream architecture is a set of small processing elements communicating together through hardware FIFOs
plus a general-purpose processing element.
As shown on figure 6.4, each processing element is mapped to a processing element of the machine.
The communicatin is made through the hardware FIFOs. A call is serialized to the hardware output buffer, sent
through the Network On Chip (NoC) and finally deserialized from the input buffer.
Figure 6.4: xSTream architecture
6.4 Available platforms
Copyright STMicroelectronics 2008