* First pass at reorganizing the documentation

        For openaadl/ocarina#171

doc/about.rst

-
-
 .. _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.
-

doc/bug.rst

-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

doc/conf.py

@@ -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())

doc/index.rst

@@ -14,11 +14,11 @@ Ocarina User's Guide
    introduction
    installation
    usage
+   scenario
+   polyorb-hi-c
    osate-ocarina
    python
    editors
-   bug
+   ocarina_config
    gfdl
    annexes
-
-

doc/installation.rst

@@ -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.
 

doc/introduction.rst

-
 .. _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.

doc/ocarina_config.rst

+=====================
+Ocarina property sets
+=====================
+
+Deployment
+##########
+
+.. literalinclude:: ../resources/deployment.aadl
+   :language: aadl
+
+.. _ocarina_config:
+
+Ocarina_Config
+##############
+
+.. literalinclude:: ../resources/ocarina_config.aadl
+   :language: aadl

doc/python.rst

@@ -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:

doc/scenario.rst

+.. _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

doc/source/example.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

doc/source/ping/activity.c

+#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;
+      }
+   }
+}
+
+

doc/source/ping/complex_types.aadl

+-- 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

doc/source/ping/data_struct.h

+typedef struct
+{
+   pos_internal_type field1;
+   pos_internal_type field2;
+
+} pos_impl;

doc/source/ping/deployment.h

+#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

doc/source/ping/deployment_c.c

+#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;
+

doc/source/ping/devices.aadl

+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;

doc/source/ping/do_ping_spg.aadl

+subprogram Do_Ping_Spg
+features
+  Data_Source : out parameter Simple_Type;
+properties
+  source_language => C;
+  source_name     => "user_ping";
+end Do_Ping_Spg;
+

doc/source/ping/hardware.aadl

+processor the_processor
+properties
+  ARAO::location           => "127.0.0.1";
+  ARAO::Execution_Platform => Native;
+end the_processor;

doc/source/ping/main.c

+#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);
+}
+
+

doc/source/ping/marshallers.c

+#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;
+      }
+   }
+}