// 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 manage.h
* @brief Functions for managing FPGA configurations
*
* FPGA accelerators can be reprogrammed at run time by providing new partial
* bitstreams ("green bitstreams"). This file defines API functions for
* programming green bitstreams as well as for assigning accelerators to host
* interfaces for more complex deployment setups, such as virtualized systems.
*/
#ifndef __FPGA_MANAGE_H__
#define __FPGA_MANAGE_H__
#include <opae/types.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* Assign Port to a host interface.
*
* This function assign Port to a host interface for subsequent use. Only
* Port that have been assigned to a host interface can be opened by
* fpgaOpen().
*
* @param[in] fpga Handle to an FPGA object previously opened that
* both the host interface and the slot belong to
* @param[in] interface_num Host interface number
* @param[in] slot_num Slot number
* @param[in] flags Flags (to be defined)
* @returns FPGA_OK on success
* FPGA_INVALID_PARAM if input parameter combination
* is not valid.
* FPGA_EXCEPTION if an exception occcurred accessing
* the `fpga` handle.
* FPGA_NOT_SUPPORTED if driver does not support
* assignment.
*/
fpga_result fpgaAssignPortToInterface(fpga_handle fpga,
uint32_t interface_num,
uint32_t slot_num,
int flags);
/**
* Assign an accelerator to a host interface
*
* This function assigns an accelerator to a host interface for subsequent use. Only
* accelerators that have been assigned to a host interface can be opened by
* fpgaOpen().
*
* @note This function is currently not supported.
*
* @param[in] fpga Handle to an FPGA object previously opened that
* both the host interface and the accelerator belong to
* @param[in] accelerator accelerator to assign
* @param[in] host_interface Host interface to assign accelerator to
* @param[in] flags Flags (to be defined)
* @returns FPGA_OK on success
*/
fpga_result fpgaAssignToInterface(fpga_handle fpga,
fpga_token accelerator,
uint32_t host_interface,
int flags);
/**
* Unassign a previously assigned accelerator
*
* This function removes the assignment of an accelerator to an host interface (e.g. to
* be later assigned to a different host interface). As a consequence, the accelerator
* referred to by token 'accelerator' will be reset during the course of this function.
*
* @note This function is currently not supported.
*
* @param[in] fpga Handle to an FPGA object previously opened that
* both the host interface and the accelerator belong to
* @param[in] accelerator accelerator to unassign/release
* @returns FPGA_OK on success
*/
fpga_result fpgaReleaseFromInterface(fpga_handle fpga,
fpga_token accelerator);
/**
* Reconfigure a slot
*
* Sends a green bitstream file to an FPGA to reconfigure a specific slot. This
* call, if successful, will overwrite the currently programmed AFU in that
* slot with the AFU in the provided bitstream.
*
* As part of the reconfiguration flow, all accelerators associated with this slot will
* be unassigned and reset.
*
* @param[in] fpga Handle to an FPGA object previously opened
* @param[in] slot Token identifying the slot to reconfigure
* @param[in] bitstream Pointer to memory holding the bitstream
* @param[in] bitstream_len Length of the bitstream in bytes
* @param[in] flags Flags that control behavior of reconfiguration.
* Value of 0 indicates no flags. FPGA_RECONF_FORCE
* indicates that the bitstream is programmed into
* the slot without checking if the resource is
* currently in use.
* @returns FPGA_OK on success. FPGA_INVALID_PARAM if the provided parameters
* are not valid. FPGA_EXCEPTION if an internal error occurred accessing the
* handle or while sending the bitstream data to the driver. FPGA_BUSY if the
* accelerator for the given slot is in use. FPGA_RECONF_ERROR on errors
* reported by the driver (such as CRC or protocol errors).
*
* @note By default, fpgaReconfigureSlot will not allow reconfiguring a slot
* with an accelerator in use. Add the flag FPGA_RECONF_FORCE to force
* reconfiguration without checking for accelerators in use.
*/
fpga_result fpgaReconfigureSlot(fpga_handle fpga,
uint32_t slot,
const uint8_t *bitstream,
size_t bitstream_len, int flags);
#ifdef __cplusplus
} // extern "C"
#endif // __cplusplus
#endif // __FPGA_MANAGE_H__