event/event_example.c

Reference Documentation

Platform
IntelĀ® PAC
Napatech SmartNIC
Content Type
Reference Information
Napatech Software Suite: event/event_example.c
event/event_example.c

Description

This source file is an example of how to use the Event stream interface in NTAPI.

The following NTAPI functions are used:


Prerequisites

A working system is needed with an Napatech accelerator as adapter 0.

Program flow

The following is required to use the Event stream interface in NTAPI:

  • #include/nt.h - Applications/Tools only need to include nt.h to obtain prototypes, macros etc. from NTAPI.
  • NT_Init(NTAPI_VERSION) - Initialize the NTAPI library. NTAPI_VERSION is a define that describes the version of the API described in the header files included by nt.h. NT_Init() will ask the NTAPI library to convert return data to the NTAPI_VERSION if possible. This will ensure that applications can run on NTAPI libraries of newer versions.
  • NT_EventOpen() - Open an event stream.
  • ForceAnEvent() - Trigger an event.
  • NT_EventRead() - Read the event information.
  • NT_EventClose() - Close the stream when terminating.
  • NT_Done() - Close down the NTAPI library.
  • NT_ExplainError() - Explain an error code returned by NTAPI functions.

/*
*
* Copyright 2020 Napatech A/S. All Rights Reserved.
*
* 1. Copying, modification, and distribution of this file, or executable
* versions of this file, is governed by the terms of the Napatech Software
* license agreement under which this file was made available. If you do not
* agree to the terms of the license do not install, copy, access or
* otherwise use this file.
*
* 2. Under the Napatech Software license agreement you are granted a
* limited, non-exclusive, non-assignable, copyright license to copy, modify
* and distribute this file in conjunction with Napatech SmartNIC's and
* similar hardware manufactured or supplied by Napatech A/S.
*
* 3. The full Napatech Software license agreement is included in this
* distribution, please see "NP-0405 Napatech Software license
* agreement.pdf"
*
* 4. Redistributions of source code must retain this copyright notice,
* list of conditions and the following disclaimer.
*
* THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTIES, EXPRESS OR
* IMPLIED, AND NAPATECH DISCLAIMS ALL IMPLIED WARRANTIES INCLUDING ANY
* IMPLIED WARRANTY OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, OR OF
* FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT NOT PROHIBITED BY
* APPLICABLE LAW, IN NO EVENT SHALL NAPATECH BE LIABLE FOR PERSONAL INJURY,
* OR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES WHATSOEVER,
* INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, CORRUPTION OR
* LOSS OF DATA, FAILURE TO TRANSMIT OR RECEIVE ANY DATA OR INFORMATION,
* BUSINESS INTERRUPTION OR ANY OTHER COMMERCIAL DAMAGES OR LOSSES, ARISING
* OUT OF OR RELATED TO YOUR USE OR INABILITY TO USE NAPATECH SOFTWARE OR
* SERVICES OR ANY THIRD PARTY SOFTWARE OR APPLICATIONS IN CONJUNCTION WITH
* THE NAPATECH SOFTWARE OR SERVICES, HOWEVER CAUSED, REGARDLESS OF THE THEORY
* OF LIABILITY (CONTRACT, TORT OR OTHERWISE) AND EVEN IF NAPATECH HAS BEEN
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME JURISDICTIONS DO NOT ALLOW
* THE EXCLUSION OR LIMITATION OF LIABILITY FOR PERSONAL INJURY, OR OF
* INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS LIMITATION MAY NOT APPLY TO YOU.
*
*
*/
/**
* @example event/event_example.c
* @section event_example_description Description
*
* This source file is an example of how to use the @ref EventStream
* "Event stream" interface in NTAPI.
*
* The following NTAPI functions are used:
* - @ref NT_Init()
* - @ref NT_EventOpen()
* - @ref NT_EventRead()
* - @ref NT_EventClose()
* - @ref NT_Done()
* - @ref NT_ExplainError()
*
* <hr>
* @section event_example_prerequisites Prerequisites
* A working system is needed with an Napatech accelerator as adapter 0.
*
* @section event_example_flow Program flow
* @{
* The following is required to use the @ref EventStream "Event stream"
* interface in NTAPI:
* - \#include/nt.h - Applications/Tools only need to include @ref
* nt.h to obtain prototypes, macros etc. from NTAPI.
* - @ref NT_Init(@ref NTAPI_VERSION) - Initialize the NTAPI
* library. @ref NTAPI_VERSION is a define that describes the version
* of the API described in the header files included by @ref
* nt.h. NT_Init() will ask the NTAPI library to convert return data
* to the @ref NTAPI_VERSION if possible. This will ensure that
* applications can run on NTAPI libraries of newer versions.
* - @ref NT_EventOpen() - Open an event stream.
* - ForceAnEvent() - Trigger an event.
* - @ref NT_EventRead() - Read the event information.
* - @ref NT_EventClose() - Close the stream when terminating.
* - @ref NT_Done() - Close down the NTAPI library.
* - @ref NT_ExplainError() - Explain an error code returned by NTAPI functions.
*
*<hr>
* @}
*/
#include <nt.h>
/*
* This function will set the timestamp of adapter 0 which will trigger
* a configuration change done event.
*/
static int ForceAnEvent(void)
{
NtConfigStream_t hConfigStream; // Config stream handle
NtConfig_t hConfig; // Config handle
char errorBuffer[NT_ERRBUF_SIZE]; // Error buffer
int status; // Status variable
// Open a config stream. This will be used to change the timestamp
// of the adapter causing it to generate an event.
if((status = NT_ConfigOpen(&hConfigStream, "CfgStream")) != NT_SUCCESS) {
// Get the status code as text
NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
fprintf(stderr, "NT_ConfigOpen() failed: %s\n", errorBuffer);
return -1;
}
printf("<<< Force an event. >>>\n");
hConfig.u.timestampWrite.adapter=0; // On adapter 0
hConfig.u.timestampWrite.data.ts = 0; // set time to 0
hConfig.u.timestampWrite.data.bCurrent=0;// and don't use current OS time
// Write timestamp=0 to adapter 0
if((status = NT_ConfigWrite(hConfigStream, &hConfig)) != NT_SUCCESS) {
// Get the status code as text
NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
fprintf(stderr, "NT_ConfigWrite() failed: %s\n", errorBuffer);
return -1;
}
// Close the config stream again
if((status = NT_ConfigClose(hConfigStream)) != NT_SUCCESS) {
// Get the status code as text
NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
fprintf(stderr, "NT_ConfigClose() failed: %s\n", errorBuffer);
return -1;
}
return status;
}
int main(void)
{
NtEventStream_t hEventStream; // Event stream handle
NtEvent_t hEvent; // Event handle
char errorBuffer[NT_ERRBUF_SIZE]; // Error buffer
int status; // Status variable
bool found = false;
// Initialize the NTAPI library and thereby check if NTAPI_VERSION can be used together with this library
if((status = NT_Init(NTAPI_VERSION)) != NT_SUCCESS) {
// Get the status code as text
NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
fprintf(stderr, "NT_Init() failed: %s\n", errorBuffer);
return -1;
}
printf("Generate an event and wait for the event before reading it.\n");
// Open the event stream
if((status = NT_EventOpen(&hEventStream, "ExampleEvent", NT_EVENT_SOURCE_CONFIG | NT_EVENT_SOURCE_TIMESYNC_STATE_MACHINE)) != NT_SUCCESS) {
// Get the status code as text
NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
fprintf(stderr, "NT_EventOpen() failed: %s\n", errorBuffer);
return -1;
}
if(ForceAnEvent() != NT_SUCCESS) {
return -1;
}
while(1) {
// Wait for the events to occur.
if((status = NT_EventRead(hEventStream, &hEvent, 10000)) != NT_SUCCESS) {
if(found) {
printf("No more events received within 10 seconds\n");
break;
}
else {
// Get the status code as text
NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
fprintf(stderr, "NT_EventRead() failed: %s\n", errorBuffer);
return -1;
}
}
// Print event info.
// As we have opened the event stream with the mask NT_EVENT_SOURCE_CONFIG | NT_EVENT_SOURCE_TIMESYNC_STATE_MACHINE
// only these to event will be received.
switch(hEvent.type) {
found = true;
// Some adapters will return this event when changing the adapter time
printf("Event received: Timestamp clock set: New time: %lld\n", (unsigned long long)hEvent.u.timeSyncStateMachineEvent.timeStampClock);
}
break;
found = true;
// Some adapters will return this event when changing the adapter time,
// then the command needs to be checked in order to see which command, that
// caused the event to be sent.
printf("Event received: Timestamp config change: New time: %lld\n", (unsigned long long)hEvent.u.configEvent.u.timestampWrite.data.ts);
}
else {
fprintf(stderr, ">>> Unexpected config change received %d.\n", hEvent.u.configEvent.parm);
}
break;
default:
fprintf(stderr, ">>> Unexpected event received %d.\n", hEvent.type);
break;
}
}
// Close the event stream
if((status = NT_EventClose(hEventStream)) != NT_SUCCESS) {
// Get the status code as text
NT_ExplainError(status, errorBuffer, sizeof(errorBuffer));
fprintf(stderr, "NT_EventClose() failed: %s\n", errorBuffer);
return -1;
}
// Close down the NTAPI library
printf("Done.\n");
return 0;
}