// 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 access.h

 * @brief Functions to acquire, release, and reset OPAE FPGA resources

 */

#ifndef __FPGA_ACCESS_H__

#define __FPGA_ACCESS_H__

#include <opae/types.h>

#ifdef __cplusplus

extern "C" {

#endif

/**

 * Open an FPGA object

 *

 * Acquires ownership of the FPGA resource referred to by 'token'.

 *

 * Most often this will be used to open an accelerator object to directly interact

 * with an accelerator function, or to open an FPGA object to perform

 * management functions.

 *

 * @param[in]  token    Pointer to token identifying resource to acquire

 *                      ownership of

 * @param[out] handle   Pointer to preallocated memory to place a handle in.

 *                      This handle will be used in subsequent API calls.

 * @param[in]  flags    One of the following flags:

 *                        * FPGA_OPEN_SHARED allows the resource to be opened

 *                          multiple times (not supported in ASE)

 *                          Shared resources (including buffers) are released

 *                          when all associated handles have been closed

 *                          (either explicitly with fpgaClose() or by process

 *                          termination).

 * @returns             FPGA_OK on success. FPGA_NOT_FOUND if the resource for

 *                      'token' could not be found. FPGA_INVALID_PARAM if

 *                      'token' does not refer to a resource that can be

 *                       opened, or if either argument is NULL or invalid.

 *                      FPGA_EXCEPTION if an internal exception occurred while

 *                      creating the handle. FPGA_NO_DRIVER if the driver is

 *                      not loaded. FPGA_BUSY if trying to open a resource that

 *                      has already been opened in exclusive mode.

 *                      FPGA_NO_ACCESS if the current process' privileges are

 *                      not sufficient to open the resource.

 */

fpga_result fpgaOpen(fpga_token token, fpga_handle *handle,

		     int flags);

/**

 * Close a previously opened FPGA object

 *

 * Relinquishes ownership of a previously fpgaOpen()ed resource. This enables

 * others to acquire ownership if the resource was opened exclusively.

 * Also deallocates / unmaps MMIO and UMsg memory areas.

 *

 * @param[in]  handle   Handle to previously opened FPGA object

 * @returns             FPGA_OK on success. FPGA_INVALID_PARAM if handle does

 *                      not refer to an acquired resource, or if handle is NULL.

 *                      FPGA_EXCEPTION if an internal error occurred while

 *                      accessing the handle.

 */

fpga_result fpgaClose(fpga_handle handle);

/**

 * Reset an FPGA object

 *

 * Performs an accelerator reset.

 *

 * @param[in]  handle   Handle to previously opened FPGA object

 * @returns             FPGA_OK on success. FPGA_INVALID_PARAM if handle does

 *                      not refer to an acquired resource or to a resource that

 *                      cannot be reset. FPGA_EXCEPTION if an internal error

 *                      occurred while trying to access the handle or resetting

 *                      the resource.

 */

fpga_result fpgaReset(fpga_handle handle);

#ifdef __cplusplus

} // extern "C"

#endif // __cplusplus

#endif // __FPGA_ACCESS_H__