-
Notifications
You must be signed in to change notification settings - Fork 84
/
event.h
160 lines (148 loc) · 6.65 KB
/
event.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
// Copyright(c) 2017, Intel Corporation
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:
//
// * Redistributions of source code must retain the above copyright notice,
// this list of conditions and the following disclaimer.
// * Redistributions in binary form must reproduce the above copyright notice,
// this list of conditions and the following disclaimer in the documentation
// and/or other materials provided with the distribution.
// * Neither the name of Intel Corporation nor the names of its contributors
// may be used to endorse or promote products derived from this software
// without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.
/**
* @file event.h
* @brief Functions for registering events and managing the lifecycle for
* `fpga_event_handle`s.
*
* OPAE provides an interface to asynchronous events that can be generated by
* different FPGA resources. The event API provides functions to register for
* these events; associated with every event a process has registered for is an
* fpga_event_handle, which encapsulates the OS-specific data structure for
* event objects. On Linux, an fpga_event_handle can be used as a file
* descriptor and passed to select(), poll(), epoll() and similar functions to
* wait for asynchronous events.
*/
#ifndef __FPGA_EVENT_H__
#define __FPGA_EVENT_H__
#include <opae/types.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* Initialize an event_handle
*
* Platform independent way to initialize an event_handle used for
* notifications from the driver to application. For Linux, this function
* creates an eventfd and returns the eventfd file descriptor in
* `*event_handle`.
*
* @param[out] event_handle Pointer to event handle variable.
*
* @returns FPGA_OK on success. FPGA_INVALID_PARAM if `event_handle` is NULL.
* FPGA_NOT_SUPPORTED if platform does not support events.
*/
fpga_result fpgaCreateEventHandle(fpga_event_handle *event_handle);
/**
* Destroy an event_handle
*
* Destroy handle and free resources. On Linux this corresponds
* to closing the file descriptor pointed to by handle
*
* @note fpgaDestroyEventHandle() requires the address of an
* event_handle as created by fpgaCreateEventHandle(). Passing
* any other value results in undefined behavior.
*
* @param[in] event_handle Pointer to handle to be destroyed
*
* @returns FPGA_OK on success. FPGA_INVALID_PARAM if `event_handle` is NULL.
*/
fpga_result fpgaDestroyEventHandle(fpga_event_handle *event_handle);
/**
* Get OS object from event handle
*
* Check validity of event handle, and get the OS object used to
* subscribe and unsubscribe to events. On Linux, the object corresponds
* to a file descriptor.
*
* @param[in] eh Event handle to get the descriptor value from
* @param[out] fd integer to store the descriptor value
*
* @returns FPGA_OK on success. FPGA_INVALID_PARAM if `event_handle` is invalid.
*/
fpga_result fpgaGetOSObjectFromEventHandle(const fpga_event_handle eh, int *fd);
/**
* Register an FPGA event
*
* This function tells the driver that the caller is interested in notification
* for the event specified by the type and flags pair.
*
* The event_handle points to an OS specific mechanism for event notification.
* An event_handle is associated with only a single event.
*
* In case of user interrupts, the flags parameter will be used to specify
* the vector ID. The value of the flags parameter indicates the vector ID,
* no bit encoding is used.
*
* @todo define if calling fpgaRegisterEvent multiple times with the
* same event_handle is an error condition or if it is silently ignored.
*
* @param[in] handle Handle to previously opened FPGA resource.
* @param[in] event_type Type of event
* @param[in] event_handle Handle to previously opened resource for event
* notification.
* @param[in] flags Optional argument for specifying additional
* information about event. For example irq number
* for interrupt events.
* @returns FPGA_OK on success. FPGA_INVALID_PARAM if handle does not refer to
* a resource supporting the requested event, or if event_handle is not valid.
* FPGA_EXCEPTION if an internal exception occurred while accessing the handle
* or the event_handle. On Linux: FPGA_NO_DAEMON if the driver does not support
* the requested event and there is no FPGA Daemon (fpgad) running to proxy it.
*/
fpga_result fpgaRegisterEvent(fpga_handle handle,
fpga_event_type event_type,
fpga_event_handle event_handle,
uint32_t flags);
/**
* Unregister an FPGA event
*
* This function tells the driver that the caller is no longer interested in
* notification for the event associated with the event_handle
*
* The event_handle points to an OS specific mechanism for event notification.
* An event_handle is associated with only a single event.
*
* @todo define if calling fpgaUnregisterEvent multiple times with the
* same event_handle is an error condition or if it is silently ignored.
*
* @param[in] handle Handle to previously opened FPGA resource.
* @param[in] event_type Type of event to unregister.
* @param[in] event_handle Handle to previously registered resource for event
* notification.
* @returns FPGA_OK on success. FPGA_INVALID_PARAM if handle does
* not refer to a resource supporting the requested event,
* or if event_handle is not valid. FPGA_EXCEPTION if an
* internal error occurred accessing the handle or the
* event_handle.
*/
fpga_result fpgaUnregisterEvent(fpga_handle handle,
fpga_event_type event_type,
fpga_event_handle event_handle);
#ifdef __cplusplus
} // extern "C"
#endif // __cplusplus
#endif // __FPGA_EVENT_H__