/** * @file EPICSCAInput.h * @brief Header file for class EPICSCAInput * @date 20/04/2017 * @author Andre Neto * * @copyright Copyright 2015 F4E | European Joint Undertaking for ITER and * the Development of Fusion Energy ('Fusion for Energy'). * Licensed under the EUPL, Version 1.1 or - as soon they will be approved * by the European Commission - subsequent versions of the EUPL (the "Licence") * You may not use this work except in compliance with the Licence. * You may obtain a copy of the Licence at: http://ec.europa.eu/idabc/eupl * * @warning Unless required by applicable law or agreed to in writing, * software distributed under the Licence is distributed on an "AS IS" * basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express * or implied. See the Licence permissions and limitations under the Licence. * @details This header file contains the declaration of the class EPICSCAInput * with all of its public, protected and private members. It may also include * definitions for inline methods which need to be visible to the compiler. */ #ifndef JAEPICSCAINPUT_H_ #define JAEPICSCAINPUT_H_ /*---------------------------------------------------------------------------*/ /* Standard header includes */ /*---------------------------------------------------------------------------*/ #include /*---------------------------------------------------------------------------*/ /* Project header includes */ /*---------------------------------------------------------------------------*/ #include "DataSourceI.h" #include "EmbeddedServiceMethodBinderI.h" #include "EventSem.h" #include "SingleThreadService.h" /*---------------------------------------------------------------------------*/ /* Class declaration */ /*---------------------------------------------------------------------------*/ namespace MARTe { /** * Maximum size that a PV name may have */ /*lint -esym(551, MARTe::PV_NAME_MAX_SIZE) the symbol is used to define the size of PVWrapper below*/ const uint32 PV_NAME_MAX_SIZE = 64u; /** * Wraps a PV */ struct PVWrapper { /** * The channel identifier */ chid pvChid; /** * The event identifier */ evid pvEvid; /** * The PV type */ chtype pvType; /** * The memory of the signal associated to this channel */ void *memory; void *previousValue; /** * The number of elements > 0 */ uint32 numberOfElements; /** * The memory size */ uint32 memorySize; /** * The PV name */ char8 pvName[PV_NAME_MAX_SIZE]; }; /** * @brief A DataSource which allows to retrieved data from any number of PVs using the EPICS channel access client protocol. * Data is asynchronously retrieved using ca_create_subscriptions in the context of a different thread (w.r.t. to the real-time thread). * * The configuration syntax is (names are only given as an example): * * 
 * +EPICSCAInput_1 = {
 *     Class = JAEPICSCA::JAEPICSCAInput
 *     StackSize = 1048576 //Optional the EmbeddedThread stack size. Default value is THREADS_DEFAULT_STACKSIZE * 4u
 *     CPUs = 0xff //Optional the affinity of the EmbeddedThread (where the EPICS context is attached).
 *     Signals = {
 *          PV1 = { //At least one shall be defined
 *             PVName = My::PV1 //Compulsory. Name of the PV.
 *             Type = uint32 //Compulsory. Supported types are char8[40], string[40], uint8, int8, uint16, int16, int32, uint32, uint64, int64, float32 and float64
 *             NumberOfElements = 1 //Arrays also supported
 *          }
 *          ...
 *     }
 * }
 *
 *
*/ class JAEPICSCAInput: public DataSourceI, public EmbeddedServiceMethodBinderI { public: CLASS_REGISTER_DECLARATION() /** * @brief Default constructor. NOOP. */ JAEPICSCAInput(); /** * @brief Destructor. * @details TODO. */ virtual ~JAEPICSCAInput(); /** * @brief See DataSourceI::AllocateMemory. NOOP. * @return true. */ virtual bool AllocateMemory(); /** * @brief See DataSourceI::GetNumberOfMemoryBuffers. * @return 1. */ virtual uint32 GetNumberOfMemoryBuffers(); /** * @brief See DataSourceI::GetSignalMemoryBuffer. * @pre * SetConfiguredDatabase */ virtual bool GetSignalMemoryBuffer(const uint32 signalIdx, const uint32 bufferIdx, void *&signalAddress); /** * @brief See DataSourceI::GetNumberOfMemoryBuffers. * @details Only InputSignals are supported. * @return MemoryMapInputBroker. */ virtual const char8 *GetBrokerName(StructuredDataI &data, const SignalDirection direction); /** * @brief See DataSourceI::GetInputBrokers. * @details adds a memory MemoryMapInputBroker instance to the inputBrokers * @return true. */ virtual bool GetInputBrokers(ReferenceContainer &inputBrokers, const char8* const functionName, void * const gamMemPtr); /** * @brief See DataSourceI::GetOutputBrokers. * @return false. */ virtual bool GetOutputBrokers(ReferenceContainer &outputBrokers, const char8* const functionName, void * const gamMemPtr); /** * @brief See DataSourceI::PrepareNextState. NOOP. * @return true. */ virtual bool PrepareNextState(const char8 * const currentStateName, const char8 * const nextStateName); /** * @brief Loads and verifies the configuration parameters detailed in the class description. * @return true if all the mandatory parameters are correctly specified and if the specified optional parameters have valid values. */ virtual bool Initialise(StructuredDataI & data); /** * @brief Final verification of all the parameters. Setup of the memory required to hold all the signals. * @details This method verifies that all the parameters requested by the GAMs interacting with this DataSource * are valid and consistent with the parameters set during the initialisation phase. * In particular the following conditions shall be met: * - All the signals have the PVName defined * - All the signals have one of the following types: uint32, int32, float32 or float64. * @return true if all the parameters are valid and the conditions above are met. */ virtual bool SetConfiguredDatabase(StructuredDataI & data); /** * @brief Gets the affinity of the thread which is going to be used to asynchronously read data from the ca_create_subscription. * @return the the affinity of the thread which is going to be used to asynchronously read data from the ca_create_subscription. */ uint32 GetCPUMask() const; /** * @brief Gets the stack size of the thread which is going to be used to asynchronously read data from the ca_create_subscription. * @return the stack size of the thread which is going to be used to asynchronously read data from the ca_create_subscription. */ uint32 GetStackSize() const; /** * @brief Provides the context to execute all the EPICS relevant calls. * @details Executes in the context of a spawned thread the following EPICS calls: * ca_context_create, ca_create_channel, ca_create_subscription, ca_clear_subscription, * ca_clear_event, ca_clear_channel, ca_detach_context and ca_context_destroy * @return ErrorManagement::NoError if all the EPICS calls return without any error. */ virtual ErrorManagement::ErrorType Execute(ExecutionInfo & info); /** * @brief See DataSourceI::Synchronise. * @return false. */ virtual bool Synchronise(); /** * @brief Registered as the ca_create_subscription callback function. * It calls updates the memory of the corresponding PV variable. */ friend void JAEPICSCAInputEventCallback(struct event_handler_args args); private: /** * List of PVs. */ PVWrapper *pvs; /** * The CPU mask for the executor */ uint32 cpuMask; /** * The stack size */ uint32 stackSize; /** * The EmbeddedThread where the ca_pend_event is executed. */ SingleThreadService executor; /** * Stores the configuration information received at Initialise. */ ConfigurationDatabase originalSignalInformation; }; } /*---------------------------------------------------------------------------*/ /* Inline method definitions */ /*---------------------------------------------------------------------------*/ #endif /* EPICSCADATASOURCE_H_ */