Commit 23cc28c6 authored by yoogx's avatar yoogx

* First pass at reorganizing the documentation

        For openaadl/ocarina#171
parent d83a0765
.. _about:
================
......@@ -65,4 +63,3 @@ Copyright Information
If you have any questions regarding this document, its
copyright, or publishing this document in non-electronic form,
please contact us.
Submitting a bug
================
To submit a bug report, please follow the following steps, you may then use Ocarina bug tracking system.
See Ocarina main web site for more details.
.. include:: PROBLEM-REPORT-FORM
:literal:
\ No newline at end of file
......@@ -261,7 +261,7 @@ latex_elements = {
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'ocarina.tex', u'Ocarina Documentation',
u'Jerome Hugues', 'manual'),
u'Julien Delange, Jerome Hugues, Bechir Zalila', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
......@@ -320,4 +320,11 @@ texinfo_documents = [
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'http://docs.python.org/': None}
intersphinx_mapping = {'https://docs.python.org/': None}
def setup(sphinx):
sys.path.append(os.path.abspath('.'))
sys.path.append(os.path.abspath('./util/'))
from AADLLexer import AADLLexer
sphinx.add_lexer("aadl", AADLLexer())
......@@ -14,11 +14,11 @@ Ocarina User's Guide
introduction
installation
usage
scenario
polyorb-hi-c
osate-ocarina
python
editors
bug
ocarina_config
gfdl
annexes
......@@ -47,7 +47,7 @@ Optional components:
Semi-automated build instructions
#################################
The `ocarina-build https://github.com/OpenAADL/ocarina-build/`_
The `ocarina-build <https://github.com/OpenAADL/ocarina-build/>`_
repository proposes a script, `build_ocarina.sh`, to get source code,
compile and test Ocarina.
......
.. _introduction:
============
......@@ -169,3 +168,16 @@ a complete model.
:align: center
ASSERT MPC Case study
Ocarina concepts
################
Ocarina uses the following set of definitions :
.. index:: scenario files
* A *scenario file* is a specific AADL system that controls the behavior of Ocarina through various properties, see :ref:`scenariofiles`.
.. index:: root system
* A *root system* is the root of an AADL model; it is a system implementation without feature. As a closed system, it has definitions required for complete processing by Ocarina: processors, threads, processes, etc.
=====================
Ocarina property sets
=====================
Deployment
##########
.. literalinclude:: ../resources/deployment.aadl
:language: aadl
.. _ocarina_config:
Ocarina_Config
##############
.. literalinclude:: ../resources/ocarina_config.aadl
:language: aadl
This diff is collapsed.
......@@ -21,7 +21,8 @@ At run-time, the following environment variables must be set up::
Example
#######
Here is a small examples illustrating Python API capabilities
The following example illustrates the capabilities of the Python API,
it implements a visitor that iterates of the AADL model elements:
.. literalinclude:: ../resources/runtime/python/test/visitor.py
:language: python
......@@ -34,8 +35,5 @@ The following lists all functions defined in the `ocarina` module
.. automodule:: ocarina.ocarina
:members:
.. automodule:: lmp
:members:
.. automodule:: ocarina_common_tools
.. automodule:: ocarina.lmp
:members:
.. _scenariofiles:
==============
Scenario files
==============
AADL scenario files are a very simple way to set build options when
using Ocarina. AADL scenario may consist of more than one AADL file.
Scenario files rely on the system component category to configure all
elements of the system to be processed. The following scenario file
illustrates this feature. It extends an existing scenario file (see
below) with project-specific configuration data:
.. literalinclude:: source/scenario.aadl
:language: aadl
Scenario files rely on specific properties:
* property :code:`AADL_Files` lists all files that are part of the system;
* property :code:`Root_System_Name` is the name of the Root System;
* property :code:`Generator` is the name of the generator (or back-end) to use
.. note:: The definition of scenario-specific properties may be found in section :ref:`ocarina_config`.
:command:`ocarina -x <scenario_file.aadl>` will cause the scenario
file to be processed. In addition, the flag :code:`-b` will
compile generated source files.
:file:`ocarina_library.aadl`
############################
.. literalinclude:: ../resources/AADLv2/ocarina_library.aadl
:language: aadl
package foo_pkg
public
-- sample AADL model
thread foo
features
a : in event data port;
properties
Dispatch_Protocol => Periodic;
Compute_Execution_Time => 5 ms .. 10 ms;
Source_Text => "foobar";
end foo;
end foo_pkg;
\ No newline at end of file
#include <po_hi_types.h>
#include <po_hi_gqueue.h>
#include <request.h>
#include <deployment.h>
#include <types.h>
#include <subprograms.h>
#include <po_hi_task.h>
#include <po_hi_main.h>
#include <marshallers.h>
extern __po_hi_entity_t __po_hi_port_global_to_entity[__PO_HI_NB_PORTS];
extern __po_hi_port_t __po_hi_port_global_to_local[__PO_HI_NB_PORTS];
__po_hi_int8_t __po_hi_data_source_local_destinations[1] = {ping_me_global_data_sink};
__po_hi_uint8_t __po_hi_pinger_woffsets[__po_hi_pinger_nb_ports];
__po_hi_uint8_t __po_hi_pinger_offsets[__po_hi_pinger_nb_ports];
__po_hi_uint8_t __po_hi_pinger_used_size[__po_hi_pinger_nb_ports];
__po_hi_uint8_t __po_hi_pinger_empties[__po_hi_pinger_nb_ports];
__po_hi_uint8_t __po_hi_pinger_first[__po_hi_pinger_nb_ports];
__po_hi_uint8_t __po_hi_pinger_recent[__po_hi_pinger_nb_ports * sizeof(__po_hi_request_t)];
__po_hi_uint8_t __po_hi_pinger_queue[0 * sizeof(__po_hi_request_t)];
__po_hi_uint16_t __po_hi_pinger_total_fifo_size = 0;
__po_hi_port_t __po_hi_pinger_history[0];
__po_hi_uint8_t __po_hi_pinger_n_dest[__po_hi_pinger_nb_ports] = {1};
__po_hi_int8_t __po_hi_pinger_fifo_size[__po_hi_pinger_nb_ports] = {__PO_HI_GQUEUE_FIFO_OUT};
__po_hi_uint8_t* __po_hi_pinger_destinations[__po_hi_pinger_nb_ports] = {__po_hi_data_source_local_destinations};
/* Periodic task : Pinger*/
/****************/
/* pinger_job */
/****************/
void* pinger_job ()
{
simple_type data_source_request_var;
__po_hi_request_t data_source_request;
__po_hi_gqueue_init(node_a_pinger_k,__po_hi_pinger_nb_ports,__po_hi_pinger_queue,__po_hi_pinger_fifo_size,__po_hi_pinger_first,__po_hi_pinger_offsets,__po_hi_pinger_woffsets,__po_hi_pinger_n_dest,__po_hi_pinger_destinations,__po_hi_pinger_used_size,__po_hi_pinger_history,__po_hi_pinger_recent,__po_hi_pinger_empties,__po_hi_pinger_total_fifo_size);
__po_hi_wait_initialization();
while (1)
{
/* Call implementation*/
do_ping_spg(&(data_source_request_var));
/* Set the OUT port values*/
data_source_request.vars.pinger_global_data_source.pinger_global_data_source = data_source_request_var;
data_source_request.port = data_source_request_var;
__po_hi_gqueue_store_out(node_a_pinger_k,pinger_local_data_source,&(data_source_request));
/* Send the OUT ports*/
__po_hi_gqueue_send_output(node_a_pinger_k,pinger_global_data_source);
__po_hi_wait_for_next_period(node_a_pinger_k);
}
}
/**************************/
/* __po_hi_main_deliver */
/**************************/
void __po_hi_main_deliver
(__po_hi_msg_t* message)
{
__po_hi_request_t request;
__po_hi_entity_t entity;
__po_hi_unmarshall_request(&(request),message);
entity = __po_hi_port_global_to_entity[request.port];
switch (entity)
{
default:
{
break;
}
}
}
-- Bounded string type
data String_Data
properties
ARAO::Data_Type => String;
ARAO::Max_Length => <User_Defined_Length>;
end String_Data;
-- Bounded wide string type
data W_String_Data
properties
ARAO::Data_Type => Wide_String;
ARAO::Max_Length => <User_Defined_Length>;
end W_String_Data;
-- Bounded array type: Only the component implementation should be
-- used in the ports or parameters!
data Data_Array
properties
ARAO::Length => <User_Defined_Length>;
end Data_Array;
data implementation Data_Array.i;
subcomponents
-- Only one subcomponent
Element : data String_Data;
end Data_Array.i;
-- Data structure type: Only the component implementation should be
-- used in the ports or parameters!
data Data_Structure
end Data_Structure;
data implementation Data_Structure.i;
subcomponents
Component_1 : data String_Data;
Component_2 : data W_String_Data;
Component_3 : data Data_Array.i;
end Data_Structure.i;
\ No newline at end of file
typedef struct
{
pos_internal_type field1;
pos_internal_type field2;
} pos_impl;
#ifndef __DEPLOYMENT_H_
#define __DEPLOYMENT_H_
#include <po_hi_protected.h>
typedef enum
{
pinger_local_data_source = 0
} __po_hi_pinger_t;
#define __po_hi_pinger_nb_ports 1
typedef enum
{
ping_me_local_data_sink = 0
} __po_hi_ping_me_t;
#define __po_hi_ping_me_nb_ports 1
/* For each node in the distributed application add an enumerator*/
typedef enum
{
node_a_k = 0,
node_b_k = 1
} __po_hi_node_t;
/* For each thread in the distributed application nodes, add an enumerator*/
typedef enum
{
node_a_pinger_k_entity = 0,
node_b_ping_me_k_entity = 1
} __po_hi_entity_t;
typedef enum
{
node_a_pinger_k = 0
} __po_hi_task_id;
#define __PO_HI_NB_TASKS 1
/* For each thread in the distributed application nodes THAT MAY COMMUNICATE*/
/* with the current node, add an enumerator*/
typedef enum
{
invalid_server = -1
} __po_hi_entity_server_t;
#define __PO_HI_NB_SERVERS 0
#define __PO_HI_NB_PROTECTED 0
#define __PO_HI_NB_NODES 2
#define __PO_HI_NB_ENTITIES 2
#define __PO_HI_NB_PORTS 2
typedef enum
{
pinger_global_data_source = 0,
ping_me_global_data_sink = 1
} __po_hi_port_t;
#endif
#include <deployment.h>
__po_hi_entity_server_t server_entity_table[__PO_HI_NB_ENTITIES] = {invalid_server,invalid_server};
__po_hi_node_t entity_table[__PO_HI_NB_ENTITIES] = {node_a_k,node_b_k};
__po_hi_node_t mynode = node_a_k;
package devices
device serial_port_raw
features
serial_line : requires bus access buses::serial.i;
properties
Provided_Virtual_Bus_Class => (classifier (protocols::dummy.i));
end serial_port_raw;
device implementation serial_port_raw.linux
properties
Deployment::Driver_Name => "serial_linux";
Device_Driver => classifier (devices::serial_driver.linux);
Initialize_Entrypoint => classifier (devices::spg_serial_init_linux);
end serial_port_raw.linux;
subprogram spg_serial_poller_linux
properties
Source_Language => C;
Source_Name => "__po_hi_c_driver_serial_linux_poller";
end spg_serial_poller_linux;
subprogram spg_serial_sender_linux
properties
Source_Language => C;
Source_Name => "__po_hi_c_driver_serial_linux_sender";
end spg_serial_sender_linux;
subprogram spg_serial_init_linux
features
data_source : out parameter types::int.i;
properties
Source_Language => C;
Source_Name => "__po_hi_c_driver_serial_linux_init";
end spg_serial_init_linux;
thread serial_poller
end serial_poller;
thread implementation serial_poller.linux
calls
mycall : {
pspg : subprogram spg_serial_poller_linux;
};
properties
Period => 1000ms;
Dispatch_Protocol => Periodic;
end serial_poller.linux;
thread implementation serial_poller.rasta
calls
mycall : {
pspg : subprogram spg_serial_poller_rasta;
};
properties
Period => 1000ms;
Dispatch_Protocol => Periodic;
end serial_poller.rasta;
abstract serial_driver
end serial_driver;
abstract implementation serial_driver.linux
subcomponents
receiver : thread serial_poller.linux;
sender : subprogram spg_serial_sender_linux;
end serial_driver.linux;
abstract implementation serial_driver.rasta
subcomponents
receiver : thread serial_poller.rasta;
sender : subprogram spg_serial_sender_rasta;
end serial_driver.rasta;
end devices;
subprogram Do_Ping_Spg
features
Data_Source : out parameter Simple_Type;
properties
source_language => C;
source_name => "user_ping";
end Do_Ping_Spg;
processor the_processor
properties
ARAO::location => "127.0.0.1";
ARAO::Execution_Platform => Native;
end the_processor;
#include <activity.h>
#include <po_hi_common.h>
#include <po_hi_main.h>
#include <po_hi_time.h>
#include <po_hi_task.h>
/***********************/
/* __PO_HI_MAIN_NAME */
/***********************/
__PO_HI_MAIN_TYPE __PO_HI_MAIN_NAME ()
{
__po_hi_initialize();
__po_hi_create_periodic_task(node_a_pinger_k,__po_hi_milliseconds(5000),2,pinger_job);
__po_hi_wait_initialization();
__po_hi_wait_for_tasks();
return (__PO_HI_MAIN_RETURN);
}
#include <types.h>
#include <po_hi_types.h>
#include <po_hi_marshallers.h>
/***************************************/
/* __po_hi_marshall_type_simple_type */
/***************************************/
void __po_hi_marshall_type_simple_type
(simple_type value,
__po_hi_msg_t* message,
__po_hi_uint16_t* offset)
{
__po_hi_marshall_int(value,message,offset);
}
/*****************************************/
/* __po_hi_unmarshall_type_simple_type */
/*****************************************/
void __po_hi_unmarshall_type_simple_type
(simple_type* value,
__po_hi_msg_t* message,
__po_hi_uint16_t* offset)
{
__po_hi_unmarshall_int(value,message,offset);
}
/************************************************/
/* __po_hi_marshall_request_ping_me_data_sink */
/************************************************/
void __po_hi_marshall_request_ping_me_data_sink
(__po_hi_request_t* request,
__po_hi_msg_t* message,
__po_hi_uint16_t* offset)
{
__po_hi_marshall_type_simple_type(request->vars.ping_me_global_data_sink.ping_me_global_data_sink,message,offset);
}
/**************************************************/
/* __po_hi_unmarshall_request_ping_me_data_sink */
/**************************************************/
void __po_hi_unmarshall_request_ping_me_data_sink
(__po_hi_request_t* request,
__po_hi_msg_t* message,
__po_hi_uint16_t* offset)
{
__po_hi_unmarshall_type_simple_type(&(request->vars.ping_me_global_data_sink.ping_me_global_data_sink),message,offset);
}
/*************************************************/
/* __po_hi_marshall_request_pinger_data_source */
/*************************************************/
void __po_hi_marshall_request_pinger_data_source
(__po_hi_request_t* request,
__po_hi_msg_t* message,
__po_hi_uint16_t* offset)
{
__po_hi_marshall_type_simple_type(request->vars.pinger_global_data_source.pinger_global_data_source,message,offset);
}
/***************************************************/
/* __po_hi_unmarshall_request_pinger_data_source */
/***************************************************/
void __po_hi_unmarshall_request_pinger_data_source
(__po_hi_request_t* request,
__po_hi_msg_t* message,
__po_hi_uint16_t* offset)
{
__po_hi_unmarshall_type_simple_type(&(request->vars.pinger_global_data_source.pinger_global_data_source),message,offset);
}
/******************************/
/* __po_hi_marshall_request */
/******************************/
void __po_hi_marshall_request
(__po_hi_request_t* request,
__po_hi_msg_t* message)
{
__po_hi_uint16_t offset;
offset = 0;
__po_hi_marshall_port(request->port,message);
switch (request->port)
{
case ping_me_global_data_sink:
{
__po_hi_marshall_request_ping_me_data_sink(request,message,&(offset));
break;
}
case pinger_global_data_source:
{
__po_hi_marshall_request_pinger_data_source(request,message,&(offset));
break;
}
default:
{
break;
}
}
}
/********************************/
/* __po_hi_unmarshall_request */
/********************************/
void __po_hi_unmarshall_request
(__po_hi_request_t* request,
__po_hi_msg_t* message)
{
__po_hi_uint16_t offset;
offset = 0;
__po_hi_unmarshall_port(&(request->port),message);
switch (request->port)
{
case ping_me_global_data_sink:
{
__po_hi_unmarshall_request_ping_me_data_sink(request,message,&(offset));
break;
}
case pinger_global_data_source:
{
__po_hi_unmarshall_request_pinger_data_source(request,message,&(offset));
break;
}
default:
{
break;
}
}
}
#include <po_hi_protocols.h>
#include <deployment.h>
/* Naming Table*/
__po_hi_inetport_t node_port[__PO_HI_NB_NODES] = {__PO_HI_NOPORT,12002};
__po_hi_inetaddr_t node_addr[__PO_HI_NB_NODES] = {__PO_HI_NOADDR,"127.0.0.1"};
process A
features
Out_Port : out event data port Simple_Type;
end A;
process implementation A.Impl
subcomponents
Pinger : thread P.Impl;
connections
C1 : event data port Pinger.Data_Source -> Out_Port;
end A.Impl;
#include <po_hi_gqueue.h>
#include <po_hi_types.h>
#include <request.h>
#include <deployment.h>
#include <po_hi_task.h>
#include <subprograms.h>
#include <po_hi_main.h>
#include <marshallers.h>
extern __po_hi_entity_t __po_hi_port_global_to_entity[__PO_HI_NB_PORTS];
extern __po_hi_port_t __po_hi_port_global_to_local[__PO_HI_NB_PORTS];
__po_hi_uint8_t __po_hi_ping_me_woffsets[__po_hi_ping_me_nb_ports];
__po_hi_uint8_t __po_hi_ping_me_offsets[__po_hi_ping_me_nb_ports];
__po_hi_uint8_t __po_hi_ping_me_used_size[__po_hi_ping_me_nb_ports];
__po_hi_uint8_t __po_hi_ping_me_empties[__po_hi_ping_me_nb_ports];
__po_hi_uint8_t __po_hi_ping_me_first[__po_hi_ping_me_nb_ports];
__po_hi_uint8_t __po_hi_ping_me_recent[__po_hi_ping_me_nb_ports * sizeof(__po_hi_request_t)];
__po_hi_uint8_t __po_hi_ping_me_queue[16 * sizeof(__po_hi_request_t)];
__po_hi_uint16_t __po_hi_ping_me_total_fifo_size = 16;
__po_hi_port_t __po_hi_ping_me_history[16];
__po_hi_uint8_t __po_hi_ping_me_n_dest[__po_hi_ping_me_nb_ports] = {0};
__po_hi_int8_t __po_hi_ping_me_fifo_size[__po_hi_ping_me_nb_ports] = {16};
__po_hi_uint8_t* __po_hi_ping_me_destinations[__po_hi_ping_me_nb_ports] = {NULL};
/*********************/
/* ping_me_deliver */
/*********************/
void ping_me_deliver
(__po_hi_request_t* request)
{
switch (request->port)
{
case ping_me_global_data_sink:
{
__po_hi_gqueue_store_in(node_b_ping_me_k,ping_me_local_data_sink,request);
break;
}
default:
{
break;
}
}
}
/* Sporadic task : Ping_Me*/
/* Get the IN ports values*/
/*****************/
/* ping_me_job */
/*****************/
void* ping_me_job ()
{
__po_hi_port_t port;
__po_hi_request_t data_sink_request;
__po_hi_gqueue_init(node_b_ping_me_k,__po_hi_ping_me_nb_ports,__po_hi_ping_me_queue,__po_hi_ping_me_fifo_size,__po_hi_ping_me_first,__po_hi_ping_me_offsets,__po_hi_ping_me_woffsets,__po_hi_ping_me_n_dest,__po_hi_ping_me_destinations,__po_hi_ping_me_used_size,__po_hi_ping_me_history,__po_hi_ping_me_recent,__po_hi_ping_me_empties,__po_hi_ping_me_total_fifo_size);
__po_hi_wait_initialization();
while (1)
{
__po_hi_gqueue_wait_for_incoming_event(node_b_ping_me_k,&(port));
__po_hi_compute_next_period(node_b_ping_me_k);
if (__po_hi_gqueue_get_count(node_b_ping_me_k,ping_me_local_data_sink))
{
__po_hi_gqueue_get_value(node_b_ping_me_k,ping_me_local_data_sink,&(data_sink_request));
__po_hi_gqueue_next_value(node_b_ping_me_k,ping_me_local_data_sink);
}
/* Call implementation*/