// 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__