Add documentation and example of a custom POHIC driver

step by step explanations to add a user-written POHIC communication
driver.

doc/drivers/add-driver-to-pohic/add_driver_doc_mp.txt

+1) edit ocarina_components.aadl and look for this pattern:
+
+
+  --------------------------------------------------
+  -- USB BRICK (STAR DUNDEE) DEVICE FOR SPACEWIRE --
+  --------------------------------------------------
+
+
+2) below this section, add the following to declare the 2 new drivers for two SPW ports:
+
+  ---------------------------------------------------
+  -- CUSTOM DRIVER TO SIMULATE SPW PORT A OF GR740 --
+  ---------------------------------------------------
+
+  device gr740_spw_a
+  features
+    link : requires bus access ocarina_buses::spacewire.generic;
+  end gr740_spw_a;
+
+  device implementation gr740_spw_a.pohic
+  properties
+    Deployment::Driver_Name       => "gr740_spw_a";
+    Device_Driver                 => classifier (ocarina_drivers_gr740_spw_a::driver.gr740_spw_a);
+    Initialize_Entrypoint         => classifier (ocarina_drivers_gr740_spw_a::spw_a_init);
+    Provided_Virtual_Bus_Class    => (classifier (ocarina_buses::pohi.c));
+  end gr740_spw_a.pohic;
+
+  ---------------------------------------------------
+  -- CUSTOM DRIVER TO SIMULATE SPW PORT B OF GR740 --
+  ---------------------------------------------------
+
+  device gr740_spw_b
+  features
+    link : requires bus access ocarina_buses::spacewire.generic;
+  end gr740_spw_b;
+
+  device implementation gr740_spw_b.pohic
+  properties
+    Deployment::Driver_Name       => "gr740_spw_b";
+    Device_Driver                 => classifier (ocarina_drivers_gr740_spw_b::driver.gr740_spw_b);
+    Initialize_Entrypoint         => classifier (ocarina_drivers_gr740_spw_b::spw_b_init);
+    Provided_Virtual_Bus_Class    => (classifier (ocarina_buses::pohi.c));
+  end gr740_spw_b.pohic;
+
+
+!!pay attention to the Driver_Name!!
+
+we have to define the devices in packages named "ocarina_drivers_gr740_spw_a / b"
+
+3) look for that pattern in the file:
+
+
+  with ocarina_drivers_star_dundee_spacewire_brick;
+
+4) just below, add:
+
+  with ocarina_drivers_gr740_spw_a;
+  with ocarina_drivers_gr740_spw_b;
+
+5) look for that pattern:
+
+package ocarina_drivers_star_dundee_spacewire_brick
+
+6) below that patten section, add:
+
+package ocarina_drivers_gr740_spw_a
+public
+
+with ocarina_buses;
+with Deployment;
+
+subprogram spw_a_poller
+properties
+	Source_Language => (C);
+	Source_Name => "__po_hi_c_driver_gr740_spw_a_poller";
+end spw_a_poller;
+
+subprogram spw_a_sender
+properties
+	Source_Language => (C);
+	Source_Name => "__po_hi_c_driver_gr740_spw_a_sender";
+end spw_a_sender;
+
+subprogram spw_a_init
+properties
+	Source_Language => (C);
+	Source_Name => "__po_hi_c_driver_gr740_spw_a_init";
+end spw_a_init;
+
+
+thread thr_poller
+end thr_poller;
+
+thread implementation thr_poller.i
+calls
+	mycall : {
+	  pspg : subprogram spw_a_poller;
+	};
+properties
+   Period => 1000ms;
+   Dispatch_Protocol => Periodic;
+end thr_poller.i;
+
+abstract driver
+properties
+   Deployment::Version  => "0.1beta";
+   Deployment::Help     => "Write your ASN.1 configuration here";
+   Deployment::Configuration_Type => classifier (ocarina_drivers::configuration_type_spacewire);
+end driver;
+
+abstract implementation driver.gr740_spw_a
+subcomponents
+   receiver_rasta_spacewire : thread thr_poller.i;
+   sender                   : subprogram spw_a_sender;
+end driver.gr740_spw_a;
+
+end ocarina_drivers_gr740_spw_a;
+
+
+package ocarina_drivers_gr740_spw_b
+public
+
+with ocarina_buses;
+with Deployment;
+
+subprogram spw_b_poller
+properties
+	Source_Language => (C);
+	Source_Name => "__po_hi_c_driver_gr740_spw_b_poller";
+end spw_b_poller;
+
+subprogram spw_b_sender
+properties
+	Source_Language => (C);
+	Source_Name => "__po_hi_c_driver_gr740_spw_b_sender";
+end spw_b_sender;
+
+subprogram spw_b_init
+properties
+	Source_Language => (C);
+	Source_Name => "__po_hi_c_driver_gr740_spw_b_init";
+end spw_b_init;
+
+
+thread thr_poller
+end thr_poller;
+
+thread implementation thr_poller.i
+calls
+	mycall : {
+	  pspg : subprogram spw_b_poller;
+	};
+properties
+   Period => 1000ms;
+   Dispatch_Protocol => Periodic;
+end thr_poller.i;
+
+abstract driver
+properties
+   Deployment::Version  => "0.1beta";
+   Deployment::Help     => "Write your ASN.1 configuration here";
+   Deployment::Configuration_Type => classifier (ocarina_drivers::configuration_type_spacewire);
+end driver;
+
+abstract implementation driver.gr740_spw_b
+subcomponents
+   receiver_rasta_spacewire : thread thr_poller.i;
+   sender                   : subprogram spw_b_sender;
+end driver.gr740_spw_b;
+
+end ocarina_drivers_gr740_spw_b;
+
+
+6) for the moment note this line:
+
+   Deployment::Configuration_Type => classifier (ocarina_drivers::configuration_type_spacewire);
+
+It is defined in the file like this:
+
+   data configuration_type_spacewire
+   properties
+      Type_Source_Name              => "Spacewire-Conf-T";
+      Deployment::ASN1_Module_Name  => "POHICDRIVER-SPACEWIRE";
+      Source_Language               => (ASN1);
+      Source_Text                   => ("/home/taste/tool-inst/include/ocarina/runtime/polyorb-hi-c/src/drivers/configuration/spacewire.asn", "drivers/configuration/spacewire.h");
+   end configuration_type_spacewire;
+
+This can be modified to add a custom type for the configuration of our device ...
+
+
+7) go to ~/tool-src/polyorb-hi-c/src/drivers
+
+
+Create (or copy from another driver) the C code of the driver
+name of the file: po_hi_driver_gr740_spw_a.c
+
+// The following pattern is __PO_HI_NEED_DRIVER_<Driver_Name> 
+// the Driver_Name is in the AADL file (Deployment::Driver_Name)
+// Then the definition will be done in deployment.h automatically
+#ifdef __PO_HI_NEED_DRIVER_GR740_SPW_A
+
+
+8) go to ~/tool-src/polyorb-hi-c/include/drivers
+
+Create (or copy from another driver) the include file of the driver
+name of the file: po_hi_driver_gr740_spw_a.h
+
+9) The drivers must be copied to:
+/home/taste/tool-inst/include/ocarina/runtime/polyorb-hi-c/include/drivers/ (.h files)
+and 
+/home/taste/tool-inst/include/ocarina/runtime/polyorb-hi-c/src/drivers (.c files)
+
+This is normally done by the Makefile in pohic/src/drivers
+
+the following two files must be completed with the new driver names (.c and .o):
+
+Makefile.common.in in tool-src/polyorb-hi-c/share/make  (add the .o)
+Makefile.am  in tool-srtc/polyorb-hi-c/src/drivers   (add the .c)

doc/drivers/add-driver-to-pohic/po_hi_driver_gr740_spw_a.c

+/*
+ * This is a part of PolyORB-HI-C distribution, a minimal
+ * middleware written for generated code from AADL models.
+ * You should use it with the Ocarina toolsuite.
+ *
+ * For more informations, please visit http://taste.tuxfamily.org/wiki
+ *
+ * Copyright (C) 2017 ESA
+ */
+
+#include <deployment.h>
+/* Generated code header */
+
+// The following pattern is __PO_HI_NEED_DRIVER_<Driver_Name> 
+// the Driver_Name is in the AADL file (Deployment::Driver_Name)
+// Then the definition will be done in deployment.h automatically
+#ifdef __PO_HI_NEED_DRIVER_GR740_SPW_A
+
+#include <activity.h>
+#include <marshallers.h>
+#include <deployment.h>
+
+#include <po_hi_debug.h>
+#include <po_hi_transport.h>
+#include <po_hi_gqueue.h>
+#include <po_hi_messages.h>
+#include <po_hi_returns.h>
+
+#include <drivers/po_hi_driver_gr740_spw_a.h>
+
+#include <stdlib.h>
+#include <string.h>
+#include <sys/ioctl.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+#include <fcntl.h>
+
+#include <stdio.h>
+/* POSIX-style files */
+
+//__po_hi_request_t __po_hi_c_driver_gr740_spw_a_request;
+//__po_hi_msg_t     __po_hi_c_driver_gr740_spw_a_poller_msg;
+
+void __po_hi_c_driver_gr740_spw_a_poller (const __po_hi_device_id dev_id)
+{
+    printf("[SPW_A_Port] Polling (in fact doing nothing)\n");
+
+//  __po_hi_c_driver_gr740_spw_a_poller_msg.length = n;
+//  __po_hi_unmarshall_request (&__po_hi_c_driver_gr740_spw_a_request, &__po_hi_c_driver_gr740_spw_a_poller_msg);
+//  __po_hi_main_deliver (&__po_hi_c_driver_gr740_spw_a_request);
+
+
+}
+
+void __po_hi_c_driver_gr740_spw_a_init (__po_hi_device_id id)
+{
+   int i;
+   __po_hi_c_spacewire_conf_t* drv_conf;  // instance of ASN.1 type with the configuration
+   printf("[SPW_A_Port] Initializing\n");
+
+   drv_conf = (__po_hi_c_spacewire_conf_t*) __po_hi_get_device_configuration (id);
+
+   __po_hi_transport_set_sending_func (id, __po_hi_c_driver_gr740_spw_a_sender);
+
+   printf("[SPW_A_Port] Device Name = %s\n", drv_conf->devname);
+}
+
+// I hope there can't be simultaneous callers....
+__po_hi_msg_t           __po_hi_c_driver_gr740_spw_a_sender_msg;
+
+int __po_hi_c_driver_gr740_spw_a_sender (const __po_hi_task_id task_id, const __po_hi_port_t port)
+{
+   int                     n;
+   int                     ts;
+
+   uint8_t buf[__PO_HI_MESSAGES_MAX_SIZE+1];
+
+   unsigned long* swap_pointer;
+   unsigned long swap_value;
+   __po_hi_local_port_t    local_port;
+   __po_hi_request_t*      request;
+   __po_hi_port_t          destination_port;
+   __po_hi_device_id       dev_id;
+   __po_hi_device_id       remote_device;
+   __po_hi_c_spacewire_conf_t* remote_drv_conf;  // instance of ASN.1 type with the configuration
+
+   dev_id = __po_hi_get_device_from_port (port);
+
+   if (dev_id == invalid_device_id)
+   {
+      __PO_HI_DEBUG_DEBUG ("[GR740_SPW_A] Invalid device id for sending\n");
+      return __PO_HI_UNAVAILABLE;
+   }
+
+   local_port = __po_hi_get_local_port_from_global_port (port);
+
+   request = __po_hi_gqueue_get_most_recent_value (task_id, local_port);
+
+   if (request->port == -1)
+   {
+      __PO_HI_DEBUG_DEBUG ("[GR740_SPW_A] Send output task %d, port %d (local_port=%d): no value to send\n", task_id, port, local_port);
+      return __PO_HI_SUCCESS;
+   }
+
+   destination_port     = __po_hi_gqueue_get_destination (task_id, local_port, 0);
+   // Identify remote device, to get its configuration
+   remote_device        = __po_hi_get_device_from_port (destination_port);
+
+   remote_drv_conf = (__po_hi_c_spacewire_conf_t*) __po_hi_get_device_configuration (remote_device);
+   printf("[GR740_SPW_A_Sender] Sending to device name %s\n", remote_drv_conf->devname);
+
+   __po_hi_msg_reallocate (&__po_hi_c_driver_gr740_spw_a_sender_msg);
+
+   request->port = destination_port;
+   printf ("[USB-SPW] Destination port= %d, send through device %d \n", destination_port, dev_id);
+
+   __po_hi_marshall_request (request, &__po_hi_c_driver_gr740_spw_a_sender_msg);
+   swap_pointer  = (unsigned long*) &__po_hi_c_driver_gr740_spw_a_sender_msg.content[0];
+   swap_value    = *swap_pointer;
+   *swap_pointer = __po_hi_swap_byte (swap_value);
+
+   memcpy (&buf[1], __po_hi_c_driver_gr740_spw_a_sender_msg.content, __PO_HI_MESSAGES_MAX_SIZE);
+   for (ts = 0 ; ts < __PO_HI_MESSAGES_MAX_SIZE ; ts++)
+   {
+      __PO_HI_DEBUG_DEBUG ("%x", __po_hi_c_driver_gr740_spw_a_sender_msg.content[ts]);
+   }
+   __PO_HI_DEBUG_DEBUG ("|\n");
+
+   request->port = __PO_HI_GQUEUE_INVALID_PORT;
+
+   return 1;
+}
+
+#endif

doc/drivers/add-driver-to-pohic/po_hi_driver_gr740_spw_a.h

+/*
+ * This is a part of PolyORB-HI-C distribution, a minimal
+ * middleware written for generated code from AADL models.
+ * You should use it with the Ocarina toolsuite.
+ *
+ * For more informations, please visit http://taste.tuxfamily.org/wiki
+ *
+ * Copyright (C) 2011-2014 ESA & ISAE.
+ */
+
+#include <deployment.h>
+
+#include <drivers/configuration/spacewire.h>
+
+#ifndef __PO_HI_DRIVER_GR740_SPW_A_H__
+#define __PO_HI_DRIVER_GR740_SPW_A_H__
+
+#ifdef __PO_HI_NEED_DRIVER_GR740_SPW_A
+
+void __po_hi_c_driver_gr740_spw_a_poller (const __po_hi_device_id dev_id);
+void __po_hi_c_driver_gr740_spw_a_init (__po_hi_device_id id);
+int __po_hi_c_driver_gr740_spw_a_sender (const __po_hi_task_id task_id, const __po_hi_port_t port);
+
+
+#endif
+
+#endif
+
+