iop_d3ripURT.h

Go to the documentation of this file.
00001 /** @file iop_d3ripURT.h iodevice for d3ripURT protocol and friends */
00002 
00003 /*
00004   FAU Discrete Event Systems Library (libfaudes)
00005 
00006   Copyright (C) 2011 Ece Schmidt, Klaus Schmidt, Ulas Turan
00007 
00008 */
00009 
00010 
00011 
00012 
00013 #ifndef FAUDES_IOP_D3RIP_URT_H
00014 #define FAUDES_IOP_D3RIP_URT_H
00015 
00016 
00017 
00018 #include "corefaudes.h"
00019 
00020 //only compile with D3RIP-URT protocol operation
00021 #ifdef FAUDES_IODEVICE_D3RIP_URT
00022 
00023 
00024 #include "iop_vdevice.h"
00025 #include <string.h>
00026 #include <sys/stat.h>
00027 #include <fcntl.h> 
00028 #include <mqueue.h>
00029 #include <sys/stat.h>
00030 #include <vector>
00031 #include <map>
00032 
00033 namespace faudes {
00034 
00035 #define D3RIP_RT_MESSAGE_MAX_LENGTH 186
00036 #define D3RIP_URT_MAX_PARAMETERS_COUNT 5
00037 #define D3RIP_URT_MAX_EVENT_COUNT 5
00038 
00039 enum {
00040 D3RIP_URT_EVENT_ID=0,
00041 D3RIP_URT_CHANNEL_TO_TRANSMIT,
00042 D3RIP_URT_PARAMETER_COUNT,
00043 D3RIP_URT_HEADER_SIZE
00044 };
00045 
00046 enum {
00047 D3RIP_URT_DESTIONATION_NODE=0,
00048 D3RIP_URT_DESTIONATION_CHANNEL,
00049 D3RIP_URT_ELIGIBILITY_TIME,
00050 D3RIP_URT_DEADLINE_TIME,
00051 D3RIP_URT_PARAMETER_SIZE
00052 };
00053 
00054 typedef struct {
00055   int destinationNode;
00056   int destinationChannel;
00057   int eligibilityTime;
00058   int deadlineTime;  
00059 }ParameterRecord;
00060 
00061 /**
00062  * Configuration of D3RIP_URT Output Event parameters
00063  * 
00064  * This class assists to extract the content of Ouput Event specification by using TokenReader. 
00065  * Note that D3RIP related parameters should be attached to each Ouput Event.
00066  *
00067  */
00068 
00069 class AttributeD3ripURTOutput : public AttributeVoid {
00070 
00071 FAUDES_TYPE_DECLARATION(Void,AttributeD3ripURTOutput,AttributeVoid)
00072 
00073 public:
00074 
00075   /** Default constructor (no triggers) */
00076   AttributeD3ripURTOutput(void) : AttributeVoid() {};
00077 
00078   /** Copy - constructor */
00079   AttributeD3ripURTOutput(const AttributeD3ripURTOutput& rOtherAttr) : AttributeVoid() 
00080       { DoAssign(rOtherAttr); };
00081 
00082   /** Test for default value (never) */
00083   virtual bool IsDefault(void) const {return false;};
00084 
00085   /** Clear */
00086   virtual void Clear(void) { 
00087     mChannelToTransmit=0;
00088   };
00089 
00090   /** Channel number for transmitting the event */
00091   int mChannelToTransmit;
00092   
00093   /** Consistent event IDs should be given at all controllers */
00094   int mEventId;
00095 
00096   /** Bunch of D3RIP related parameters  */
00097   std::vector<ParameterRecord> mParameterRecords;
00098 
00099  protected:
00100 
00101   /**
00102    * Copy method
00103    *
00104    * @param rSrcAttr
00105    *   Source to copy from
00106    * @return
00107    *   Ref to this attribute
00108    */
00109   virtual void DoAssign(const AttributeD3ripURTOutput& rSrcAttr);
00110 
00111   /**
00112    * Reads the attribute from TokenReader, see AttributeVoid for public wrappers.
00113    *
00114    * If the current token indicates an output mapping, the method reads that
00115    * section. Else it does nothing. Exceptions may only be thrown
00116    * on invalid data within the section. The label argument is ignored, we the hardcoded
00117    * output for output device attributes. The context argument is ignored.
00118    *
00119    * @param rTr
00120    *   TokenReader to read from
00121    * @param rLabel
00122    *   Section to read
00123    * @param pContext
00124    *   Read context to provide contextual information
00125    *
00126    * @exception Exception
00127    *   - IO error (id 1)
00128    */
00129   virtual void DoRead(TokenReader& rTr,const std::string& rLabel="", const Type*  pContext=0);
00130 
00131   /**
00132    * Writes the attribute to TokenWriter, see AttributeVoid for public wrappers.
00133    *
00134    * Writes the output mapping data. The label argument is ignored, we use
00135    * the hardcoded section "Output". The context argument is ignored.
00136    *
00137    * @param rTw
00138    *   TokenWriter to write to
00139    * @param rLabel
00140    *   Section to write
00141    * @param pContext
00142    *   Read context to provide contextual information
00143    *
00144    * @exception Exception
00145    *   - IO error (id 2)
00146    */
00147   virtual void DoWrite(TokenWriter& rTw,const std::string& rLabel="", const Type* pContext=0) const;
00148 
00149 }; // end class AttributeD3ripURTOutput
00150 
00151 
00152 
00153 
00154 
00155 
00156 /**
00157  * Configuration of D3RIP_URT Input Event parameters
00158  * 
00159  * This class assists to extract the content of Input Event specification by using TokenReader.
00160  * It should be noted that only mEventId is required for Input Events. It is not necessary to specify 
00161  * D3RIP related parameters for Input Events
00162  *
00163  */
00164 
00165 class AttributeD3ripURTInput : public AttributeVoid {
00166 
00167 FAUDES_TYPE_DECLARATION(Void,AttributeD3ripURTInput,AttributeVoid)
00168 
00169 public:
00170 
00171   /** Default constructor (no triggers) */
00172   AttributeD3ripURTInput(void) : AttributeVoid() {};
00173 
00174   /** Copy constructor */
00175   AttributeD3ripURTInput (const AttributeD3ripURTInput& rOtherAttr) : AttributeVoid() 
00176       { DoAssign(rOtherAttr); };
00177 
00178   /** Test for default value (never) */
00179   virtual bool IsDefault(void) const {return false;};
00180 
00181   /** Clear */
00182   virtual void Clear(void) { /* set myself to default values */;};
00183   
00184   /** Consistent event IDs should be given at all controllers */
00185   int mEventId;
00186 
00187  protected:
00188 
00189   /**
00190    * Copy method
00191    *
00192    * @param rSrcAttr
00193    *   Source to copy from
00194    * @return
00195    *   Ref to this attribute
00196    */
00197   virtual void DoAssign(const AttributeD3ripURTInput& rSrcAttr);
00198 
00199   /**
00200    * Reads the attribute from TokenReader, see AttributeVoid for public wrappers.
00201    *
00202    * If the current token indicates a input mapping, the method reads that
00203    * section. Else it does nothing. Exceptions may only be thrown
00204    * on invalid data within the section. The label argument is ignored, we use the
00205    * hardcoded section "Input" for input attributes. The context argument is ignored.
00206    *
00207    * @param rTr
00208    *   TokenReader to read from
00209    * @param rLabel
00210    *   Section to read
00211    * @param pContext
00212    *   Read context to provide contextual information
00213    *
00214    * @exception Exception
00215    *   - IO error (id 1)
00216    */
00217   virtual void DoRead(TokenReader& rTr,const std::string& rLabel="", const Type* pContext=0);
00218 
00219 
00220   /**
00221    * Writes the attribute to TokenWriter, see AttributeVoid for public wrappers.
00222    *
00223    * Writes the input mapping data.The label argument is ignored, we use the
00224    * hardcoded section "Input". The context argument is ignored.
00225    *
00226    * @param rTw
00227    *   TokenWriter to write to
00228    * @param rLabel
00229    *   Section to write
00230    * @param pContext
00231    *   Read context to provide contextual information
00232    *
00233    * @exception Exception
00234    *   - IO error (id 2)
00235    */
00236 
00237   virtual void DoWrite(TokenWriter& rTw,const std::string& rLabel="", const Type* pContext=0) const;
00238 
00239 }; // end class AttributeD3ripURTInput
00240 
00241 
00242 
00243 
00244 /**
00245  * Configuration of an d3ripURT event as input or output
00246  *
00247  * This class is derived from the AttributeDeviceEvent to specialise
00248  * for d3ripURT based input and output mapping.
00249  *
00250  */
00251 
00252 class AttributeD3ripURTEvent : public AttributeDeviceEvent {
00253 
00254 FAUDES_TYPE_DECLARATION(Void,AttributeD3ripURTEvent,AttributeDeviceEvent)
00255 
00256  public:
00257 
00258   /** Default constructor (no mapping at all) */
00259   AttributeD3ripURTEvent(void);
00260 
00261   /** Copy constructor */
00262   AttributeD3ripURTEvent(const AttributeD3ripURTEvent& rOtherAttr); 
00263 
00264   /** Test for default value (never) */
00265   virtual bool IsDefault(void) const {return false;};
00266 
00267   /** Clear */
00268   virtual void Clear(void)  { AttributeDeviceEvent::Clear(); };
00269 
00270   /**  Get output mapping */
00271   const AttributeD3ripURTOutput*  Outputp(void) const {
00272     return static_cast<AttributeD3ripURTOutput*>(mpOutputAttribute); };
00273 
00274   /**  Get input mapping */
00275   const AttributeD3ripURTInput*  Inputp(void) const {
00276     return static_cast<AttributeD3ripURTInput*>(mpInputAttribute); };
00277 
00278  protected:
00279 
00280   /** DoAssign */
00281   virtual void DoAssign(const AttributeD3ripURTEvent& rSrc)  
00282   { AttributeDeviceEvent::DoAssign(rSrc);};
00283 
00284   /** Prototype, input (construct on first use static) */
00285   static const AttributeD3ripURTInput* InputPrototypep(void);
00286 
00287   /** Prototype, output (construct on first use static) */
00288   static const AttributeD3ripURTOutput* OutputPrototypep(void);
00289 
00290 }; // class AttributeD3ripURTEvent
00291 
00292 
00293 /**
00294  * Provides the interface between simfaudes and D3RIP protocol running on the same host
00295  *
00296  * @section SecIodeviceD3RipUrtDev1 Networking
00297  * The d3ripURTDevice assists in the exchange of the logical events belonged to the 
00298  * controllers over network utilizing D3RIP. It is similar to the SimpleNet device 
00299  * in some manner, however, d3ripURTDevice provides deterministic time bounds for 
00300  * the transmission of logical events through Ethernet. This device just provides 
00301  * required access to the underlying D3RIP implementation from the libFAUDES simulator. 
00302  * Note that D3RIP implementation and IEEE 1588 Synchronization deamon should be seperately
00303  * provided for the desired operation. 
00304  * 
00305  * @section SecIodeviceD3RipUrtDev1 Protocol Details
00306  * Though d3ripURTDevice does not implement the D3RIP, it should be aware of the corresponding 
00307  * protocol parameters assigned for each output logical event. Token IO is used in section 
00308  * "D3ripURTDevice" while extracting those parameters. Detailed information about protocol related 
00309  * parameters can be obtained by referring to the D3RIP specification. A simple controller may have:
00310  * 
00311  * @code
00312  * <D3ripURTDevice name="ControllerB_Net"> 
00313  * <!-- Time scale in ms/ftiu -->
00314  * <TimeScale value="1000"/> 
00315  *
00316  * <!-- Event configuration -->
00317  * <EventConfiguration> 
00318  * 
00319  * <Event name="?lambda" iotype="output">
00320  * <EventId value="1"/>
00321  * <ChannelToTransmit value="1"/>
00322  * <ParameterRecord name="11">
00323  * <DestinationNode value="1"/>
00324  * <DestinationChannel value="1"/>
00325  * <EligibilityTime value="2" />
00326  * <DeadlineTime value="5"/>
00327  * </ParameterRecord>
00328  * </Event>
00329  * 
00330  * <Event name="!lambda" iotype="input">
00331  * <EventId value="2"/>
00332  * </Event>
00333  * 
00334  * <Event name="lambda" iotype="output">
00335  * <EventId value="3"/>
00336  * <ChannelToTransmit value="1"/>
00337  * <ParameterRecord name="11">
00338  * <DestinationNode value="2"/>
00339  * <DestinationChannel value="1"/>
00340  * <EligibilityTime value="2" />
00341  * <DeadlineTime value="5"/>
00342  * </ParameterRecord>
00343  * </Event>
00344  * 
00345  * </EventConfiguration> 
00346  * 
00347  * </D3ripURTDevice> 
00348  * @endcode
00349  *
00350  * 
00351  * @section SecIodeviceD3RipUrtDev1 Notes
00352  * This device compiles flags under Linux only and should be linked to realtime library (-lrt). 
00353  *
00354  * @ingroup IODevicePlugin
00355  */
00356 
00357 class d3ripURTDevice : public vDevice {
00358 
00359   // provide access to background tasks
00360   friend void* DoListenCLModule(void*);
00361 
00362 FAUDES_TYPE_DECLARATION(D3RipUrtDevice,d3ripURTDevice,vDevice)
00363 
00364 
00365 
00366 public:
00367 
00368   /**
00369   * Array to store Event parameters statically in the form:
00370   * ||| EventID | Channel To Transmit | Parameter Count || DESTIONATION_NODE | DESTIONATION_CHANNEL | ELIGIBILITY_TIME | DEADLINE_TIME | ... |||
00371   */
00372   unsigned char mEventParameters[D3RIP_URT_MAX_EVENT_COUNT][D3RIP_URT_HEADER_SIZE+D3RIP_URT_PARAMETER_SIZE*D3RIP_URT_MAX_PARAMETERS_COUNT]; 
00373   
00374   /** Status for receiving events from D3RIP */
00375   int mContinueListening;
00376   
00377   /** Used for sending events to D3RIP */
00378   mqd_t mMQueueToSend;
00379   
00380   /** Used for receiving events from D3RIP */
00381   mqd_t mMQueueToReceive;
00382   
00383   /** Thread created for listening incoming events */
00384   pthread_t mThreadListenModule;
00385   
00386   /** will be modified by WriteOutput and send by FlushOutput */
00387   unsigned char mCommunicationRequestCount;
00388   
00389   /** Buffer for outgoing  events */
00390   ParameterRecord mCommunicationRequests[D3RIP_URT_MAX_EVENT_COUNT*D3RIP_URT_MAX_PARAMETERS_COUNT];
00391   
00392   /** Stores the total number of events in the system configuration */
00393   unsigned char mEventCount;
00394   
00395   /** Stores the total number of events to be send over D3RIP */
00396   unsigned char mEventsToSendCount;
00397   
00398   /** Stores the Ids for outgoing events */
00399   unsigned char mEventIdsToSend[D3RIP_URT_MAX_EVENT_COUNT];
00400 
00401   /** It is needed to assign a common Ids to the logical events at all controller nodes for the sake of consistency */
00402   std::map<std::string, int> mEventIdMap;
00403 
00404   /**
00405    * Default constructor
00406    */
00407   d3ripURTDevice(void);
00408 
00409   /**
00410    * Copy constructor [not functional, since DoAssign is not implemented]
00411    */
00412   d3ripURTDevice(const d3ripURTDevice& rSrc) : vDevice() 
00413       { DoAssign(rSrc); };
00414 
00415   /**
00416    * Explicit destructor.
00417    */
00418   virtual ~d3ripURTDevice(void);
00419 
00420 
00421   /**
00422    * Clear all configuration.
00423    * This implies Stop().
00424    */
00425   virtual void Clear(void);
00426 
00427   /**
00428    * 
00429    * Build up internal data-structure(e.g. signal-event - mapping and extract D3RIP parameters)
00430    *
00431    */
00432   virtual void Compile(void);
00433 
00434 
00435   /**
00436    * Activate the device. This function enables output execution and input reading.
00437    *
00438    * Configure for real-time operation and create D3RIP listener thread.
00439    *
00440    * @exception Exception
00441    *   - Not yet configured (id 551)
00442    */
00443   virtual void Start(void);
00444 
00445   /**
00446    * Deactivate the device. This function disables output execution and input reading.
00447    */
00448   virtual void Stop(void);
00449 
00450   /** Clear dynamic data and restart device */
00451   virtual void Reset(void);
00452 
00453 
00454   /**
00455    * Prepare the outgoing buffer regarding D3RIP specifications
00456    *
00457    * @exception Exception
00458    *   - unknown output event (id 65)
00459    */
00460   virtual void WriteOutput(Idx output);
00461 
00462   /**
00463   * Forward all ready-to-send events to the D3RIP for tranmission to other controllers
00464   *
00465   * @exception Exception
00466   *   - unknown output event (id 65)
00467   */
00468   void FlushOutput(unsigned char channel);
00469 
00470  protected:
00471 
00472   /** Overall configuration (with actual type) */
00473   TaNameSet<AttributeD3ripURTEvent>* pConfiguration;
00474 
00475 
00476   /**  
00477    * Writes non-event-related configuration to TokenWriter
00478    *
00479    * Device data will be written bottom-to-top along the class-hierarchy,
00480    * see also vDevice::DoWritePreface.
00481    *
00482    * Note: in order to keep the outputfile-layout as simple as possible no label will 
00483    * be used to separate this data-section. 
00484    *
00485    * @param rTw
00486    *   TokenWriter to write
00487    * @param rLabel
00488    *   Section to write
00489    * @param pContext
00490    *   Context to provide contextual information
00491    *
00492    * */
00493   void DoWritePreface(TokenWriter& rTw, const std::string& rLabel,  const Type* pContext=0) const;
00494 
00495   /**  Reads non-event-related configuration from TokenReader
00496    *
00497    * Device date is read bottom-to-top along the class-hierarchy; 
00498    * see also vDevice::DoReadPreface.
00499    *
00500    *
00501    * Note: in order to keep the inputfile-layout as simple as possible no label will 
00502    * be used to separate this data-section. 
00503    *
00504    * @param rTr
00505    *   TokenReader to read from
00506    * @param rLabel
00507    *   Section to read
00508    * @param pContext
00509    *   Read context to provide contextual information
00510    *
00511    * */
00512   virtual void DoReadPreface(TokenReader& rTr,const std::string& rLabel="", const Type* pContext=0);
00513 
00514   // dummies
00515   virtual void DoAssign(const d3ripURTDevice& rSrcAttr){};
00516   virtual bool DoEqual(const d3ripURTDevice& rSrcAttr) const { return false;};
00517 
00518  private:
00519 
00520 }; 
00521 
00522 void* DoListenCLModule(void* pD3ripURTDevice);
00523 }
00524 
00525 #endif // configure
00526 #endif // include
00527 

libFAUDES 2.23h --- 2014.04.03 --- c++ api documentaion by doxygen