stream_event.h

1/*2 * %NT_SOFTWARE_LICENSE%3 */45/**6 * @file7 *8 * This header file contains the STREAMTYPE_EVENT interface9 */10#ifndef __STREAM_EVENT_H__11#define __STREAM_EVENT_H__1213#if !defined(__NT_H__)14 #error: My interface file is 'nt.h'. Please include that via #include "nt.h" directly.15#endif1617/** @addtogroup EventStream18 * @{19 *20 * Event streams are used to get various events from the system. The21 * event stream is a read only stream.22 *23 * To open an event stream call @ref NT_EventOpen. Once the event24 * stream is open it will receive all system events. An application25 * that requires certain events will open an event stream and26 * read the events one by one. The application can then react on the27 * events that it wants to react on and ignore the rest. Once done,28 * call @ref NT_EventClose to close the stream.29 *30 * The events types currently supported are:31 * @li <tt>Port events</tt> These events are link up and link down events.32 * @li <tt>Sensor events</tt> These events are sensor alarm state changes.33 * @li <tt>Config events</tt> These events are sent when a configuration change has been made.34 * @li <tt>Time sync events</tt> These events are time synchronization state changes.35 *36 * For an example on how to use the event stream see @ref37 * event/event_example.c "event/event_example.c".38 *39 * @note The event stream is not thread-safe. If the same stream handle is to be used by multiple threads,40 * it must be mutex protected in the application.41 * 42 */43#include "ntapi/commontypes.h"44#include "ntapi/stream_config.h"45/**46 * The event types supported47 * Note: MUST be bitmasks48 */49enumNtEventSource_e {50NT_EVENT_SOURCE_NONE = 0,51NT_EVENT_SOURCE_PORT = (1 << 0), //!< Bit for port event - Data placed in @ref NtEventPort_s52NT_EVENT_SOURCE_SENSOR = (1 << 1), //!< Bit for sensor change event - Data placed in @ref NtEventSensor_s53NT_EVENT_SOURCE_CONFIG = (1 << 2), //!< Bit for config change made events - Data placed in @ref NtConfig_s54NT_EVENT_SOURCE_TIMESYNC = (1 << 3), //!< Bit for time sync events - Data placed in @ref NtEventTimeSync_s55NT_EVENT_SOURCE_SDRAM_FILL_LEVEL = (1 << 4), //!< Bit for host buffer fill level warning - Data placed in @ref NtSDRAMFillLevel_s56NT_EVENT_SOURCE_PTP_PORT = (1 << 5), //!< Bit for PTP port events - Data placed in @ref NtEventPtpPort_s57NT_EVENT_SOURCE_TIMESYNC_STATE_MACHINE = (1 << 6),//!< Bit for time sync state machine - Data placed in @ref NtEventTimeSyncStateMachine_s58NT_EVENT_SOURCE_ALL = (NT_EVENT_SOURCE_PORT |59NT_EVENT_SOURCE_SENSOR |60NT_EVENT_SOURCE_CONFIG |61NT_EVENT_SOURCE_TIMESYNC |62NT_EVENT_SOURCE_SDRAM_FILL_LEVEL |63NT_EVENT_SOURCE_PTP_PORT |64NT_EVENT_SOURCE_TIMESYNC_STATE_MACHINE), //!< Bits for all events656667NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER0 = (1 << 23), //!< Listen for command event(s). Event raised on write68NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER1 = (1 << 24),69NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER2 = (1 << 25),70NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER3 = (1 << 26),71NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER4 = (1 << 27),72NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER5 = (1 << 28),73NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER6 = (1 << 29),74NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER7 = (1 << 30),7576NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ALL = (NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER0 |77NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER1 |78NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER2 |79NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER3 |80NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER4 |81NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER5 |82NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER6 |83NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER7),84//@G--85#ifndef DOXYGEN_INTERNAL_ONLY86 NT_EVENT_SOURCE_PROFILING_QUERY = (1 << 31), //!< Bit for profiling info query87#endif88//@G++89};9091enumNtEventRaise_e {92NT_EVENT_SAMPLE_TIMESTAMP = 1,93};9495/**96 * Port events<br>97 * NT_EVENT_PORT_NIM_INSERTED and NT_EVENT_PORT_NIM_REMOVED will also be issued98 * during the load of ntservice if a NIM is present/not present at this time.99 * These events are not issued for fixed ports like RJ45.100101 If the link goes up or down then NT_EVENT_PORT_LINK_UP and NT_EVENT_PORT_LINK_DOWN are issued.102 A special case is relevant if the link goes down and then shortly afterwards103 up again and at the same time sampling is used to detect link changes104 (in contrast to interrupt). In this case this link down glitch might go105 undetected by the sampling itself.106 For most adapters however a sticky bit is set when the link goes down and107 remains in this state until cleared. If therefore the link is up at the108 current sampling, and it was also up at last sampling but the sticky bit109 indicates that the link has been down, then a NT_EVENT_PORT_LINK_DOWN event110 followed immidiately by a NT_EVENT_PORT_LINK_UP event is issued.111 In this case the log will also indicate that a link down glitch has occurred.112 It should be noted that the link might go up and down several times during a113 sampling period but this will only count as ONE link down glitch.114 Whether sampling or interrupt is used to detect link changes is adapter dependend.115 */116enumNtEventPort_e {117NT_EVENT_PORT_LINK_UP, //!< Port link up event118NT_EVENT_PORT_LINK_DOWN, //!< Port link down event119NT_EVENT_RXAUI_LINK_ERROR, //!< Port RXAUI link error120NT_EVENT_PORT_BYPASS_ACTIVATED, //!< Port bypass activated event121NT_EVENT_PORT_BYPASS_DEACTIVATED, //!< Port bypass deactivated event122NT_EVENT_PORT_NIM_INSERTED, //!< Port NIM inserted/found event123NT_EVENT_PORT_NIM_REMOVED, //!< Port NIM removed/not-found event124};125126/**127 * Sensor events128 */129enumNtEventSensor_e {130NT_EVENT_SENSOR_ALARM_STATE_ENTRY, //!< Sensor enters alarm state131NT_EVENT_SENSOR_ALARM_STATE_EXIT, //!< Sensor exits alarm state132};133134/**135 * Event time sync information136 */137enumNtEventTimeSync_e {138NT_EVENT_TIMESYNC_PPS_REQUEST_TIME, //!< Request for PPS reference time139};140141/**142 * Event time sync state machine information143 */144enumNtEventTimeSyncStateMachine_e {145NT_EVENT_TIMESYNC_TIME_REFERENCE_LOST, //!< Time reference is lost146NT_EVENT_TIMESYNC_TIME_REFERENCE_SELECT, //!< Select time reference147NT_EVENT_TIMESYNC_TIME_REFERENCE_SELECT_FAIL, //!< Fail to select time reference148NT_EVENT_TIMESYNC_TIME_IN_SYNC, //!< TS clock changed from out-of-sync to in-sync with master clock based on configured threshold value. Note: no timestamp value supplied.149NT_EVENT_TIMESYNC_TIME_OUT_OF_SYNC, //!< TS clock changed from in-sync to out-of-sync with master clock based on configured threshold value. note: no timestamp value supplied.150NT_EVENT_TIMESYNC_PTP_STATE_CHANGE, //!< Change of PTP state151NT_EVENT_TIMESYNC_TIME_STAMP_CLOCK_SET, //!< Absolute value assigned to time stamp clock152NT_EVENT_TIMESYNC_EXTERNAL_DEVICE_LOST_SYNC_SIGNAL, //!< External device lost synchronization signal153NT_EVENT_TIMESYNC_EXTERNAL_DEVICE_OUT_OF_SYNC, //!< External device is out of synchronization154NT_EVENT_TIMESYNC_EXTERNAL_DEVICE_LOST_TIME_OF_DAY, //!< External device lost time of day information155};156157/**158 * Event link up/down information159 */160struct NtEventPort_s {161enumNtEventPort_eaction; //!< Port action162 uint8_t portNo; //!< Port generating the event163 uint8_t Reserved1[3];164};165166/**167 * PTP port link up/down event information168 */169struct NtEventPtpPort_s {170enumNtEventPort_eaction; //!< Port action171 uint8_t adapterNo; //!< Adapter that generates the event172 uint8_t portNo; //!< Port that generates the event173 uint8_t Reserved1[2];174};175176/**177 * Event SDRAM fill level information178 */179#define MAX_SDRAM_FILL_LEVEL_STREAMS 256180struct NtSDRAMFillLevel_s {181 uint8_t adapterNo; //!< The adapter owning the host buffer182 uint8_t Reserved1[3];183 uint32_t streamsId; //!< Stream ID using the host buffer184 uint32_t numStreams; //!< Number of streams using the host buffers. Also indicating the use depth of @ref aStreams.185 uint64_t used; //!< SDRAM used. This shows the amount of adapter memory used. One must pay attention to this value.186 //!< When the value is close to used, it means that the adapter has used all the buffer memory.187 //!< This happens if the adapter is not able to transfer the received data to the host buffers on the PC188 //!< and is mainly caused by a slow application not being able to release the data fast enough.189 //!< Packet loss will probably occur.190 uint64_t size; //!< The amount of SDRAM reserved for this host buffer191 /**192 * This structure tells where the host buffer is currently used.193 */194struct NtHostBuffer_s {195 uint64_t deQueued; //!< Bytes available or in use by the streams.196 //!< If all data is placed here it means that the application is too slow to handle the data.197 //!< The application is not able to release the packets (host buffer) fast enough so the data is198 //!< ready for the driver and adapter to fill with new data. The result is that the adapter runs199 //!< out of data space and a packet loss occurs.200 uint64_t enQueued; //!< Bytes available to the host buffer handler.201 //!< If all data is placed here it means that the driver is too slow to handle the data.202 //!< This is a driver error and should never happen.203 uint64_t enQueuedAdapter; //!< Bytes currently in the adapter.204 //!< Most of the time the data should be placed here.205 uint64_t size; //!< Host buffer size206 } hb;207 /**208 * the array of streams using the host buffer209 */210struct NtStream_s {211intstreamIndex; //!< The index for the stream attached to the host buffer212 uint64_t enQueued; //!< The data currently enqueued to the stream. The stream with the largest enqueued amount is the slowest stream and probably the one that causes the packet loss.213 uint64_t processID; //!< The process owning the stream214 } aStreams[MAX_SDRAM_FILL_LEVEL_STREAMS];215};216217/**218 * Event sensor change information219 */220struct NtEventSensor_s {221enumNtSensorSource_e source; //!< The source of the sensor (the port or adapter on which the sensor resides)222intsourceIndex; //!< The source index - the adapter number or port number where the sensor resides223intsensorIndex; //!< The sensor index - the index of the sensor within the group of sensors. Each adapter or port has a different number and sensor type.224 //!< - NT20E2 adapter sensor group - @ref NtSensorsAdapterNT20E2_e225 //!< - NT20E2 port sensor group - @ref NtSensorsPortNT20E2_e226 //!< - NT20E adapter sensor group - @ref NtSensorsAdapterNT20E_e227 //!< - NT20E port sensor group - @ref NtSensorsPortNT20E_e228 //!< - NT4E adapter sensor group - @ref NtSensorsAdapterNT4E_e229 //!< - NT4E port sensor group - @ref NtSensorsPortNT4E_e230enumNtEventSensor_eaction; //!< Whether the alarm is entered or exited231intvalue; //!< The value that triggered the event232enumNtAdapterType_e adapterType; //!< The adapter type triggering the event233};234235/**236 * Time sync information237 */238struct NtEventTimeSync_s {239enumNtEventTimeSync_eaction; //!< What happened240 uint8_t adapter; //!< Which adapter generated the event241 uint8_t Reserved1[3];242};243244/**245 * Time sync state machine event information246 */247struct NtEventTimeSyncStateMachine_s {248enumNtEventTimeSyncStateMachine_eaction; //!< What happened249 uint8_t adapter; //!< Which adapter generated the event250enumNtTimeSyncReference_e timeReference; //!< Time reference affected by the event251union {252enumNtPTPPortState_e ptpState[2]; //!< ptpState[0] = old state; ptpState[1] = new state253 uint64_t timeStampClock; //!< Time in nanoseconds set on adapter254 };255 uint8_t reserved[3]; //!< Reserved for future use256};257258/**259 * Event information260 */261typedefstruct NtEvent_s {262enumNtEventSource_e type; //!< Event type263 /**264 * Union holding event information265 */266union NtEvent_u {267struct NtEventPort_s portEvent; //!< Port events - @ref NT_EVENT_SOURCE_PORT268struct NtEventSensor_s sensorEvent; //!< Sensor events - @ref NT_EVENT_SOURCE_SENSOR269struct NtConfig_s configEvent; //!< Config events - @ref NT_EVENT_SOURCE_CONFIG270struct NtEventTimeSync_s timeSyncEvent; //!< Time sync events - @ref NT_EVENT_SOURCE_TIMESYNC271struct NtSDRAMFillLevel_s sdramFillLevelEvent; //!< Host buffer usage event - @ref NT_EVENT_SOURCE_SDRAM_FILL_LEVEL272struct NtEventPtpPort_s ptpPortEvent; //!< PTP port event - @ref NT_EVENT_SOURCE_PTP_PORT273struct NtEventTimeSyncStateMachine_s timeSyncStateMachineEvent; //!< Time sync change state event - @ref NT_EVENT_SOURCE_TIMESYNC_STATE_MACHINE274 } u;275} NtEvent_t;276277/**278 * Event stream handle279 */280typedefstruct NtEventStream_s* NtEventStream_t;281282/**283 * @brief Opens an event stream and initializes event queues, etc.284 *285 * This function must be called before using the events. The necessary286 * stream, lists, mutexes and semaphores are initialized and287 * created.288 *289 * The source of event is selected by the eventMask. This could be either a290 * single event source or all event sources. See @ref NtEventSource_e for291 * the different event sources.292 *293 * @param[in,out] hStream Pointer to the stream handle294 * @param[in] name A friendly name of the stream295 * @param[in] eventMask @ref NtEventSource_e - A bitmask defining the sources of events to receive296 *297 * @retval == NT_SUCCESS: Success298 * @retval != NT_SUCCESS: Error299 */300intNT_EventOpen(NtEventStream_t *hStream, constchar *name, uint32_t eventMask);301302/**303 * @brief Reads an event from an event queue304 *305 * This function is called by the user to read an event.306 * The event is copied from the event queue to the307 * stream handle for the user to read using the HAL functions.308 * The event is marked as read for deletion and cannot be309 * read by the user again.310 *311 *312 * @param[in] hStream Stream to store the current event313 * @param[out] event Event structure - the event information is returned in this structure314 * @param[in] timeout Time in milliseconds to wait for an event315 *316 * @retval == NT_SUCCESS: Success317 * @retval != NT_SUCCESS: Error318 */319intNT_EventRead(NtEventStream_t hStream, NtEvent_t *event, uint32_t timeout);320321322323324325intNT_EventWrite(NtEventStream_t hStream, enumNtEventRaise_e eventId);326327328329330331/**332 * @brief Releases the stream and clears event queues, etc.333 *334 * This function must be called after using the events in order335 * to release the stream and clear the allocated lists, mutexes336 * and semaphores.337 *338 * @param[in] hStream Pointer to the stream handle339 *340 * @retval == NT_SUCCESS: Success341 * @retval != NT_SUCCESS: Error342 */343intNT_EventClose(NtEventStream_t hStream);344345/** @} */346347#endif /* __STREAM_EVENT_H__ */