stream_event.h

Reference Documentation

product_line_custom
Napatech SmartNIC
category
Reference Information

Go to the documentation of this file.

1/* 2 * %NT_SOFTWARE_LICENSE% 3 */ 4 5/** 6 * @file 7 * 8 * This header file contains the STREAMTYPE_EVENT interface 9 */ 10#ifndef __STREAM_EVENT_H__ 11#define __STREAM_EVENT_H__ 12 13#if !defined(__NT_H__) 14 #error: My interface file is 'nt.h'. Please include that via #include "nt.h" directly. 15#endif 16 17/** @addtogroup EventStream 18 * @{ 19 * 20 * Event streams are used to get various events from the system. The 21 * event stream is a read only stream. 22 * 23 * To open an event stream call @ref NT_EventOpen. Once the event 24 * stream is open it will receive all system events. An application 25 * that requires certain events will open an event stream and 26 * read the events one by one. The application can then react on the 27 * 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 @ref 37 * 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 supported 47 * Note: MUST be bitmasks 48 */ 49enum NtEventSource_e { 50 NT_EVENT_SOURCE_NONE = 0, 51 NT_EVENT_SOURCE_PORT = (1 << 0), //!< Bit for port event - Data placed in @ref NtEventPort_s 52 NT_EVENT_SOURCE_SENSOR = (1 << 1), //!< Bit for sensor change event - Data placed in @ref NtEventSensor_s 53 NT_EVENT_SOURCE_CONFIG = (1 << 2), //!< Bit for config change made events - Data placed in @ref NtConfig_s 54 NT_EVENT_SOURCE_TIMESYNC = (1 << 3), //!< Bit for time sync events - Data placed in @ref NtEventTimeSync_s 55 NT_EVENT_SOURCE_SDRAM_FILL_LEVEL = (1 << 4), //!< Bit for host buffer fill level warning - Data placed in @ref NtSDRAMFillLevel_s 56 NT_EVENT_SOURCE_PTP_PORT = (1 << 5), //!< Bit for PTP port events - Data placed in @ref NtEventPtpPort_s 57 NT_EVENT_SOURCE_TIMESYNC_STATE_MACHINE = (1 << 6),//!< Bit for time sync state machine - Data placed in @ref NtEventTimeSyncStateMachine_s 58 NT_EVENT_SOURCE_ALL = (NT_EVENT_SOURCE_PORT | 59 NT_EVENT_SOURCE_SENSOR | 60 NT_EVENT_SOURCE_CONFIG | 61 NT_EVENT_SOURCE_TIMESYNC | 62 NT_EVENT_SOURCE_SDRAM_FILL_LEVEL | 63 NT_EVENT_SOURCE_PTP_PORT | 64 NT_EVENT_SOURCE_TIMESYNC_STATE_MACHINE), //!< Bits for all events 65 66 67 NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER0 = (1 << 23), //!< Listen for command event(s). Event raised on write 68 NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER1 = (1 << 24), 69 NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER2 = (1 << 25), 70 NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER3 = (1 << 26), 71 NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER4 = (1 << 27), 72 NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER5 = (1 << 28), 73 NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER6 = (1 << 29), 74 NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER7 = (1 << 30), 75 76 NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ALL = (NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER0 | 77 NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER1 | 78 NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER2 | 79 NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER3 | 80 NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER4 | 81 NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER5 | 82 NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER6 | 83 NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER7), 84//@G-- 85#ifndef DOXYGEN_INTERNAL_ONLY 86 NT_EVENT_SOURCE_PROFILING_QUERY = (1 << 31), //!< Bit for profiling info query 87#endif 88//@G++ 89}; 90 91enum NtEventRaise_e { 92 NT_EVENT_SAMPLE_TIMESTAMP = 1, 93}; 94 95/** 96 * Port events<br> 97 * NT_EVENT_PORT_NIM_INSERTED and NT_EVENT_PORT_NIM_REMOVED will also be issued 98 * 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. 100 101 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 afterwards 103 up again and at the same time sampling is used to detect link changes 104 (in contrast to interrupt). In this case this link down glitch might go 105 undetected by the sampling itself. 106 For most adapters however a sticky bit is set when the link goes down and 107 remains in this state until cleared. If therefore the link is up at the 108 current sampling, and it was also up at last sampling but the sticky bit 109 indicates that the link has been down, then a NT_EVENT_PORT_LINK_DOWN event 110 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 a 113 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 */ 116enum NtEventPort_e { 117 NT_EVENT_PORT_LINK_UP, //!< Port link up event 118 NT_EVENT_PORT_LINK_DOWN, //!< Port link down event 119 NT_EVENT_RXAUI_LINK_ERROR, //!< Port RXAUI link error 120 NT_EVENT_PORT_BYPASS_ACTIVATED, //!< Port bypass activated event 121 NT_EVENT_PORT_BYPASS_DEACTIVATED, //!< Port bypass deactivated event 122 NT_EVENT_PORT_NIM_INSERTED, //!< Port NIM inserted/found event 123 NT_EVENT_PORT_NIM_REMOVED, //!< Port NIM removed/not-found event 124}; 125 126/** 127 * Sensor events 128 */ 129enum NtEventSensor_e { 130 NT_EVENT_SENSOR_ALARM_STATE_ENTRY, //!< Sensor enters alarm state 131 NT_EVENT_SENSOR_ALARM_STATE_EXIT, //!< Sensor exits alarm state 132}; 133 134/** 135 * Event time sync information 136 */ 137enum NtEventTimeSync_e { 138 NT_EVENT_TIMESYNC_PPS_REQUEST_TIME, //!< Request for PPS reference time 139}; 140 141/** 142 * Event time sync state machine information 143 */ 144enum NtEventTimeSyncStateMachine_e { 145 NT_EVENT_TIMESYNC_TIME_REFERENCE_LOST, //!< Time reference is lost 146 NT_EVENT_TIMESYNC_TIME_REFERENCE_SELECT, //!< Select time reference 147 NT_EVENT_TIMESYNC_TIME_REFERENCE_SELECT_FAIL, //!< Fail to select time reference 148 NT_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. 149 NT_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. 150 NT_EVENT_TIMESYNC_PTP_STATE_CHANGE, //!< Change of PTP state 151 NT_EVENT_TIMESYNC_TIME_STAMP_CLOCK_SET, //!< Absolute value assigned to time stamp clock 152 NT_EVENT_TIMESYNC_EXTERNAL_DEVICE_LOST_SYNC_SIGNAL, //!< External device lost synchronization signal 153 NT_EVENT_TIMESYNC_EXTERNAL_DEVICE_OUT_OF_SYNC, //!< External device is out of synchronization 154 NT_EVENT_TIMESYNC_EXTERNAL_DEVICE_LOST_TIME_OF_DAY, //!< External device lost time of day information 155}; 156 157/** 158 * Event link up/down information 159 */ 160struct NtEventPort_s { 161 enum NtEventPort_e action; //!< Port action 162 uint8_t portNo; //!< Port generating the event 163 uint8_t Reserved1[3]; 164}; 165 166/** 167 * PTP port link up/down event information 168 */ 169struct NtEventPtpPort_s { 170 enum NtEventPort_e action; //!< Port action 171 uint8_t adapterNo; //!< Adapter that generates the event 172 uint8_t portNo; //!< Port that generates the event 173 uint8_t Reserved1[2]; 174}; 175 176/** 177 * Event SDRAM fill level information 178 */ 179#define MAX_SDRAM_FILL_LEVEL_STREAMS 256 180struct NtSDRAMFillLevel_s { 181 uint8_t adapterNo; //!< The adapter owning the host buffer 182 uint8_t Reserved1[3]; 183 uint32_t streamsId; //!< Stream ID using the host buffer 184 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 PC 188 //!< 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 buffer 191 /** 192 * This structure tells where the host buffer is currently used. 193 */ 194 struct 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 is 198 //!< ready for the driver and adapter to fill with new data. The result is that the adapter runs 199 //!< 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 size 206 } hb; 207 /** 208 * the array of streams using the host buffer 209 */ 210 struct NtStream_s { 211 int streamIndex; //!< The index for the stream attached to the host buffer 212 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 stream 214 } aStreams[MAX_SDRAM_FILL_LEVEL_STREAMS]; 215}; 216 217/** 218 * Event sensor change information 219 */ 220struct NtEventSensor_s { 221 enum NtSensorSource_e source; //!< The source of the sensor (the port or adapter on which the sensor resides) 222 int sourceIndex; //!< The source index - the adapter number or port number where the sensor resides 223 int sensorIndex; //!< 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_e 225 //!< - NT20E2 port sensor group - @ref NtSensorsPortNT20E2_e 226 //!< - NT20E adapter sensor group - @ref NtSensorsAdapterNT20E_e 227 //!< - NT20E port sensor group - @ref NtSensorsPortNT20E_e 228 //!< - NT4E adapter sensor group - @ref NtSensorsAdapterNT4E_e 229 //!< - NT4E port sensor group - @ref NtSensorsPortNT4E_e 230 enum NtEventSensor_e action; //!< Whether the alarm is entered or exited 231 int value; //!< The value that triggered the event 232 enum NtAdapterType_e adapterType; //!< The adapter type triggering the event 233}; 234 235/** 236 * Time sync information 237 */ 238struct NtEventTimeSync_s { 239 enum NtEventTimeSync_e action; //!< What happened 240 uint8_t adapter; //!< Which adapter generated the event 241 uint8_t Reserved1[3]; 242}; 243 244/** 245 * Time sync state machine event information 246 */ 247struct NtEventTimeSyncStateMachine_s { 248 enum NtEventTimeSyncStateMachine_e action; //!< What happened 249 uint8_t adapter; //!< Which adapter generated the event 250 enum NtTimeSyncReference_e timeReference; //!< Time reference affected by the event 251 union { 252 enum NtPTPPortState_e ptpState[2]; //!< ptpState[0] = old state; ptpState[1] = new state 253 uint64_t timeStampClock; //!< Time in nanoseconds set on adapter 254 }; 255 uint8_t reserved[3]; //!< Reserved for future use 256}; 257 258/** 259 * Event information 260 */ 261typedef struct NtEvent_s { 262 enum NtEventSource_e type; //!< Event type 263 /** 264 * Union holding event information 265 */ 266 union NtEvent_u { 267 struct NtEventPort_s portEvent; //!< Port events - @ref NT_EVENT_SOURCE_PORT 268 struct NtEventSensor_s sensorEvent; //!< Sensor events - @ref NT_EVENT_SOURCE_SENSOR 269 struct NtConfig_s configEvent; //!< Config events - @ref NT_EVENT_SOURCE_CONFIG 270 struct NtEventTimeSync_s timeSyncEvent; //!< Time sync events - @ref NT_EVENT_SOURCE_TIMESYNC 271 struct NtSDRAMFillLevel_s sdramFillLevelEvent; //!< Host buffer usage event - @ref NT_EVENT_SOURCE_SDRAM_FILL_LEVEL 272 struct NtEventPtpPort_s ptpPortEvent; //!< PTP port event - @ref NT_EVENT_SOURCE_PTP_PORT 273 struct NtEventTimeSyncStateMachine_s timeSyncStateMachineEvent; //!< Time sync change state event - @ref NT_EVENT_SOURCE_TIMESYNC_STATE_MACHINE 274 } u; 275} NtEvent_t; 276 277/** 278 * Event stream handle 279 */ 280typedef struct NtEventStream_s* NtEventStream_t; 281 282/** 283 * @brief Opens an event stream and initializes event queues, etc. 284 * 285 * This function must be called before using the events. The necessary 286 * stream, lists, mutexes and semaphores are initialized and 287 * created. 288 * 289 * The source of event is selected by the eventMask. This could be either a 290 * single event source or all event sources. See @ref NtEventSource_e for 291 * the different event sources. 292 * 293 * @param[in,out] hStream Pointer to the stream handle 294 * @param[in] name A friendly name of the stream 295 * @param[in] eventMask @ref NtEventSource_e - A bitmask defining the sources of events to receive 296 * 297 * @retval == NT_SUCCESS: Success 298 * @retval != NT_SUCCESS: Error 299 */ 300int NT_EventOpen(NtEventStream_t *hStream, const char *name, uint32_t eventMask); 301 302/** 303 * @brief Reads an event from an event queue 304 * 305 * This function is called by the user to read an event. 306 * The event is copied from the event queue to the 307 * stream handle for the user to read using the HAL functions. 308 * The event is marked as read for deletion and cannot be 309 * read by the user again. 310 * 311 * 312 * @param[in] hStream Stream to store the current event 313 * @param[out] event Event structure - the event information is returned in this structure 314 * @param[in] timeout Time in milliseconds to wait for an event 315 * 316 * @retval == NT_SUCCESS: Success 317 * @retval != NT_SUCCESS: Error 318 */ 319int NT_EventRead(NtEventStream_t hStream, NtEvent_t *event, uint32_t timeout); 320 321 322 323 324 325int NT_EventWrite(NtEventStream_t hStream, enum NtEventRaise_e eventId); 326 327 328 329 330 331/** 332 * @brief Releases the stream and clears event queues, etc. 333 * 334 * This function must be called after using the events in order 335 * to release the stream and clear the allocated lists, mutexes 336 * and semaphores. 337 * 338 * @param[in] hStream Pointer to the stream handle 339 * 340 * @retval == NT_SUCCESS: Success 341 * @retval != NT_SUCCESS: Error 342 */ 343int NT_EventClose(NtEventStream_t hStream); 344 345/** @} */ 346 347#endif /* __STREAM_EVENT_H__ */