stream_event.h Source File

Reference Documentation

Platform
Intel® PAC
Napatech SmartNIC
Content Type
Reference Information
Capture Software Version
Link™ Capture Software 12.10
Napatech Software Suite: include/ntapi/stream_event.h Source File
stream_event.h
Go to the documentation of this file.
1 /*
2  *
3  * Copyright (C) 2023 Napatech A/S.
4  * All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions are met:
8  * * Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * * Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  * * Neither the name of the Napatech A/S nor the
14  * names of its contributors may be used to endorse or promote products
15  * derived from this software without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
18  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
19  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
20  * DISCLAIMED. IN NO EVENT SHALL NAPATECH A/S BE LIABLE FOR ANY
21  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
22  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
24  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
26  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27  *
28  *
29 
30  */
31 
32 /**
33  * @file
34  *
35  * This header file contains the STREAMTYPE_EVENT interface
36  */
37 #ifndef __STREAM_EVENT_H__
38 #define __STREAM_EVENT_H__
39 
40 #if !defined(__NT_H__)
41  #error: My interface file is 'nt.h'. Please include that via #include "nt.h" directly.
42 #endif
43 
44 /** @addtogroup EventStream
45  * @{
46  *
47  * Event streams are used to get various events from the system. The
48  * event stream is a read only stream.
49  *
50  * To open an event stream call @ref NT_EventOpen. Once the event
51  * stream is open it will receive all system events. An application
52  * that requires certain events will open an event stream and
53  * read the events one by one. The application can then react on the
54  * events that it wants to react on and ignore the rest. Once done,
55  * call @ref NT_EventClose to close the stream.
56  *
57  * The events types currently supported are:
58  * @li <tt>Port events</tt> These events are link up and link down events.
59  * @li <tt>Sensor events</tt> These events are sensor alarm state changes.
60  * @li <tt>Config events</tt> These events are sent when a configuration change has been made.
61  * @li <tt>Time sync events</tt> These events are time synchronization state changes.
62  *
63  * For an example on how to use the event stream see @ref
64  * event/event_example.c "event/event_example.c".
65  *
66  * @note The event stream is not thread-safe. If the same stream handle is to be used by multiple threads,
67  * it must be mutex protected in the application.
68  *
69  */
70 #include "ntapi/commontypes.h"
71 #include "ntapi/stream_config.h"
72 /**
73  * The event types supported
74  * Note: MUST be bitmasks
75  */
78  NT_EVENT_SOURCE_PORT = (1 << 0), //!< Bit for port event - Data placed in @ref NtEventPort_s
79  NT_EVENT_SOURCE_SENSOR = (1 << 1), //!< Bit for sensor change event - Data placed in @ref NtEventSensor_s
80  NT_EVENT_SOURCE_CONFIG = (1 << 2), //!< Bit for config change made events - Data placed in @ref NtConfig_s
81  NT_EVENT_SOURCE_TIMESYNC = (1 << 3), //!< Bit for time sync events - Data placed in @ref NtEventTimeSync_s
82  NT_EVENT_SOURCE_SDRAM_FILL_LEVEL = (1 << 4), //!< Bit for host buffer fill level warning - Data placed in @ref NtSDRAMFillLevel_s
83  NT_EVENT_SOURCE_PTP_PORT = (1 << 5), //!< Bit for PTP port events - Data placed in @ref NtEventPtpPort_s
84  NT_EVENT_SOURCE_TIMESYNC_STATE_MACHINE = (1 << 6),//!< Bit for time sync state machine - Data placed in @ref NtEventTimeSyncStateMachine_s
91  NT_EVENT_SOURCE_TIMESYNC_STATE_MACHINE), //!< Bits for all events
92 
93 
94  NT_EVENT_LISTEN_TIMESTAMP_SAMPLE_ADAPTER0 = (1 << 23), //!< Listen for command event(s). Event raised on write
102 
111 //
112 
113 };
114 
117 };
118 
119 /**
120  * Port events<br>
121  * NT_EVENT_PORT_NIM_INSERTED and NT_EVENT_PORT_NIM_REMOVED will also be issued
122  * during the load of ntservice if a NIM is present/not present at this time.
123  * These events are not issued for fixed ports like RJ45.
124 
125  If the link goes up or down, then NT_EVENT_PORT_LINK_UP and
126  NT_EVENT_PORT_LINK_DOWN are issued.
127  A special case is relevant if the link goes down and then shortly afterwards
128  comes up again, and at the same time sampling is used to detect link changes
129  (in contrast to interrupt). In this case this link-down glitch might go
130  undetected by the sampling itself.
131  For most adapters, however, a sticky bit is set when the link goes down and
132  remains in this state until cleared. If, therefore, the link is up at the
133  current sampling, and it was also up at the last sampling, but the sticky bit
134  indicates that the link has been down, then an NT_EVENT_PORT_LINK_DOWN event
135  followed immediately by an NT_EVENT_PORT_LINK_UP event are issued.
136  In this case the log will also indicate that a link down glitch has occurred.
137  It should be noted that the link might go up and down several times during a
138  sampling period but this only counts as ONE link down glitch.
139  Whether sampling or interrupt is used to detect link changes is adapter
140  dependent.
141 
142  The following figure illustrates a link-down glitch:
143 
144  @image html pictures/LinkDownGlitch1.png "Link-down Glitch"
145 
146  <br>
147  */
149  NT_EVENT_PORT_LINK_UP, //!< Port link up event
150  NT_EVENT_PORT_LINK_DOWN, //!< Port link down event
151  NT_EVENT_RXAUI_LINK_ERROR, //!< Port RXAUI link error
152  NT_EVENT_PORT_BYPASS_ACTIVATED, //!< Port bypass activated event
153  NT_EVENT_PORT_BYPASS_DEACTIVATED, //!< Port bypass deactivated event
154  NT_EVENT_PORT_NIM_INSERTED, //!< Port NIM inserted/found event
155  NT_EVENT_PORT_NIM_REMOVED, //!< Port NIM removed/not-found event
156 };
157 
158 /**
159  * Sensor events
160  */
162  NT_EVENT_SENSOR_ALARM_STATE_ENTRY, //!< Sensor enters alarm state
163  NT_EVENT_SENSOR_ALARM_STATE_EXIT, //!< Sensor exits alarm state
164 };
165 
166 /**
167  * Event time sync information
168  */
170  NT_EVENT_TIMESYNC_PPS_REQUEST_TIME, //!< Request for PPS reference time
171 };
172 
173 /**
174  * Event time sync state machine information
175  */
177  NT_EVENT_TIMESYNC_TIME_REFERENCE_LOST, //!< Time reference is lost
178  NT_EVENT_TIMESYNC_TIME_REFERENCE_SELECT, //!< Select time reference
179  NT_EVENT_TIMESYNC_TIME_REFERENCE_SELECT_FAIL, //!< Fail to select time reference
180  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.
181  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.
182  NT_EVENT_TIMESYNC_PTP_STATE_CHANGE, //!< Change of PTP state
183  NT_EVENT_TIMESYNC_TIME_STAMP_CLOCK_SET, //!< Absolute value assigned to time stamp clock
184  NT_EVENT_TIMESYNC_EXTERNAL_DEVICE_LOST_SYNC_SIGNAL, //!< External device lost synchronization signal
185  NT_EVENT_TIMESYNC_EXTERNAL_DEVICE_OUT_OF_SYNC, //!< External device is out of synchronization
186  NT_EVENT_TIMESYNC_EXTERNAL_DEVICE_LOST_TIME_OF_DAY, //!< External device lost time of day information
187 };
188 
189 /**
190  * Event link up/down information
191  */
193  enum NtEventPort_e action; //!< Port action
194  uint8_t portNo; //!< Port generating the event
195  uint8_t Reserved1[3];
196 };
197 
198 /**
199  * PTP port link up/down event information
200  */
202  enum NtEventPort_e action; //!< Port action
203  uint8_t adapterNo; //!< Adapter that generates the event
204  uint8_t portNo; //!< Port that generates the event
205  uint8_t Reserved1[2];
206 };
207 
208 /**
209  * Event SDRAM fill level information
210  */
211 #define MAX_SDRAM_FILL_LEVEL_STREAMS 256
213  uint8_t adapterNo; //!< The adapter owning the host buffer
214  uint8_t Reserved1[3];
215  uint32_t streamsId; //!< Stream ID using the host buffer
216  uint32_t numStreams; //!< Number of streams using the host buffers. Also indicating the use depth of @ref aStreams.
217  uint64_t used; //!< SDRAM used. This shows the amount of adapter memory used. One must pay attention to this value.
218  //!< When the value is close to used, it means that the adapter has used all the buffer memory.
219  //!< This happens if the adapter is not able to transfer the received data to the host buffers on the PC
220  //!< and is mainly caused by a slow application not being able to release the data fast enough.
221  //!< Packet loss will probably occur.
222  uint64_t size; //!< The amount of SDRAM reserved for this host buffer
223  /**
224  * This structure tells where the host buffer is currently used.
225  */
226  struct NtHostBuffer_s {
227  uint64_t deQueued; //!< Bytes available or in use by the streams.
228  //!< If all data is placed here it means that the application is too slow to handle the data.
229  //!< The application is not able to release the packets (host buffer) fast enough so the data is
230  //!< ready for the driver and adapter to fill with new data. The result is that the adapter runs
231  //!< out of data space and a packet loss occurs.
232  uint64_t enQueued; //!< Bytes available to the host buffer handler.
233  //!< If all data is placed here it means that the driver is too slow to handle the data.
234  //!< This is a driver error and should never happen.
235  uint64_t enQueuedAdapter; //!< Bytes currently in the adapter.
236  //!< Most of the time the data should be placed here.
237  uint64_t size; //!< Host buffer size
238  } hb;
239  /**
240  * the array of streams using the host buffer
241  */
242  struct NtStream_s {
243  int streamIndex; //!< The index for the stream attached to the host buffer
244  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.
245  uint64_t processID; //!< The process owning the stream
246  } aStreams[MAX_SDRAM_FILL_LEVEL_STREAMS];
247 };
248 
249 /**
250  * Event sensor change information
251  */
253  enum NtSensorSource_e source; //!< The source of the sensor (the port or adapter on which the sensor resides)
254  uint32_t sourceIndex; //!< The source index - the adapter number or port number where the sensor resides
255  uint32_t 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.
256  //!< - NT20E2 adapter sensor group - @ref NtSensorsAdapterNT20E2_e
257  //!< - NT20E2 port sensor group - @ref NtSensorsPortNT20E2_e
258  //!< - NT20E adapter sensor group - @ref NtSensorsAdapterNT20E_e
259  //!< - NT20E port sensor group - @ref NtSensorsPortNT20E_e
260  //!< - NT4E adapter sensor group - @ref NtSensorsAdapterNT4E_e
261  //!< - NT4E port sensor group - @ref NtSensorsPortNT4E_e
262  enum NtEventSensor_e action; //!< Whether the alarm is entered or exited
263  int value; //!< The value that triggered the event
264  enum NtAdapterType_e adapterType; //!< The adapter type triggering the event
265 };
266 
267 /**
268  * Time sync information
269  */
271  enum NtEventTimeSync_e action; //!< What happened
272  uint8_t adapter; //!< Which adapter generated the event
273  uint8_t Reserved1[3];
274 };
275 
276 /**
277  * Time sync state machine event information
278  */
280  enum NtEventTimeSyncStateMachine_e action; //!< What happened
281  uint8_t adapter; //!< Which adapter generated the event
282  enum NtTimeSyncReference_e timeReference; //!< Time reference affected by the event
283  union {
284  enum NtPTPPortState_e ptpState[2]; //!< ptpState[0] = old state; ptpState[1] = new state
285  uint64_t timeStampClock; //!< Time in nanoseconds set on adapter
286  };
287  uint8_t reserved[3]; //!< Reserved for future use
288 };
289 
290 /**
291  * Event information
292  */
293 typedef struct NtEvent_s {
294  enum NtEventSource_e type; //!< Event type
295  /**
296  * Union holding event information
297  */
298  union NtEvent_u {
299  struct NtEventPort_s portEvent; //!< Port events - @ref NT_EVENT_SOURCE_PORT
300  struct NtEventSensor_s sensorEvent; //!< Sensor events - @ref NT_EVENT_SOURCE_SENSOR
301  struct NtConfig_s configEvent; //!< Config events - @ref NT_EVENT_SOURCE_CONFIG
302  struct NtEventTimeSync_s timeSyncEvent; //!< Time sync events - @ref NT_EVENT_SOURCE_TIMESYNC
303  struct NtSDRAMFillLevel_s sdramFillLevelEvent; //!< Host buffer usage event - @ref NT_EVENT_SOURCE_SDRAM_FILL_LEVEL
304  struct NtEventPtpPort_s ptpPortEvent; //!< PTP port event - @ref NT_EVENT_SOURCE_PTP_PORT
305  struct NtEventTimeSyncStateMachine_s timeSyncStateMachineEvent; //!< Time sync change state event - @ref NT_EVENT_SOURCE_TIMESYNC_STATE_MACHINE
306  } u;
307 } NtEvent_t;
308 
309 /**
310  * Event stream handle
311  */
312 typedef struct NtEventStream_s* NtEventStream_t;
313 
314 /**
315  * @brief Opens an event stream and initializes event queues, etc.
316  *
317  * This function must be called before using the events. The necessary
318  * stream, lists, mutexes and semaphores are initialized and
319  * created.
320  *
321  * The source of event is selected by the eventMask. This could be either a
322  * single event source or all event sources. See @ref NtEventSource_e for
323  * the different event sources.
324  *
325  * @param[in,out] hStream Pointer to the stream handle
326  * @param[in] name A friendly name of the stream
327  * @param[in] eventMask @ref NtEventSource_e - A bitmask defining the sources of events to receive
328  *
329  * @retval == NT_SUCCESS: Success
330  * @retval != NT_SUCCESS: Error
331  */
332 int NT_EventOpen(NtEventStream_t *hStream, const char *name, uint32_t eventMask);
333 
334 /**
335  * @brief Reads an event from an event queue
336  *
337  * This function is called by the user to read an event.
338  * The event is copied from the event queue to the
339  * stream handle for the user to read using the HAL functions.
340  * The event is marked as read for deletion and cannot be
341  * read by the user again.
342  *
343  *
344  * @param[in] hStream Stream to store the current event
345  * @param[out] event Event structure - the event information is returned in this structure
346  * @param[in] timeout Time in milliseconds to wait for an event
347  *
348  * @retval == NT_SUCCESS: Success
349  * @retval != NT_SUCCESS: Error
350  */
351 int NT_EventRead(NtEventStream_t hStream, NtEvent_t *event, uint32_t timeout);
352 
353 
354 
355 
356 
357 int NT_EventWrite(NtEventStream_t hStream, enum NtEventRaise_e eventId);
358 
359 
360 
361 
362 
363 /**
364  * @brief Releases the stream and clears event queues, etc.
365  *
366  * This function must be called after using the events in order
367  * to release the stream and clear the allocated lists, mutexes
368  * and semaphores.
369  *
370  * @param[in] hStream Pointer to the stream handle
371  *
372  * @retval == NT_SUCCESS: Success
373  * @retval != NT_SUCCESS: Error
374  */
375 int NT_EventClose(NtEventStream_t hStream);
376 
377 /** @} */
378 
379 #endif /* __STREAM_EVENT_H__ */