// Copyright(c) 2018, 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.
#pragma once
#include <memory>
#include <vector>
#include <opae/cxx/core/token.h>
#include <opae/enum.h>
#include <opae/types.h>
namespace opae {
namespace fpga {
namespace types {
/** An allocated accelerator resource
*
* Represents an accelerator resource that has
* been allocated by OPAE. Depending on the type
* of resource, its register space may be
* read/written using a handle object.
*/
class handle {
public:
typedef std::shared_ptr<handle> ptr_t;
handle(const handle &) = delete;
handle &operator=(const handle &) = delete;
virtual ~handle();
/** Retrieve the underlying OPAE handle.
*/
fpga_handle c_type() const { return handle_; }
/** Retrieve the underlying OPAE handle.
*/
operator fpga_handle() const { return handle_; }
/**
* @brief Load a bitstream into an FPGA slot
*
* @param slot The slot number to program
* @param bitstream The bitstream binary data
* @param size The size of the bitstream
* @param 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.
*
* @throws invalid_param if the handle is not an FPGA device handle
* or if the other parameters are not valid.
* @throws exception if an internal error is encountered.
* @throws busy if the accelerator for the given slot is in use.
* @throws reconf_error if errors are reported by the driver
* (CRC or protocol errors).
*/
void reconfigure(uint32_t slot, const uint8_t *bitstream, size_t size,
int flags);
/**
* @brief Read 32 bits from a CSR belonging to a resource associated
* with a handle.
*
* @param[in] offset The register offset
* @param[in] csr_space The CSR space to read from. Default is 0.
*
* @return The 32-bit value read from the CSR
*/
uint32_t read_csr32(uint64_t offset, uint32_t csr_space = 0) const;
/**
* @brief Write 32 bit to a CSR belonging to a resource associated
* with a handle.
*
* @param[in] offset The register offset.
* @param[in] value The 32-bit value to write to the register.
* @param[in] csr_space The CSR space to read from. Default is 0.
*
*/
void write_csr32(uint64_t offset, uint32_t value, uint32_t csr_space = 0);
/**
* @brief Read 64 bits from a CSR belonging to a resource associated
* with a handle.
*
* @param[in] offset The register offset
* @param[in] csr_space The CSR space to read from. Default is 0.
*
* @return The 64-bit value read from the CSR
*/
uint64_t read_csr64(uint64_t offset, uint32_t csr_space = 0) const;
/**
* @brief Write 64 bits to a CSR belonging to a resource associated
* with a handle.
*
* @param[in] offset The register offset.
* @param[in] value The 64-bit value to write to the register.
* @param[in] csr_space The CSR space to read from. Default is 0.
*
*/
void write_csr64(uint64_t offset, uint64_t value, uint32_t csr_space = 0);
/**
* @brief Write 512 bits to a CSR belonging to a resource associated
* with a handle.
*
* @param[in] offset The register offset.
* @param[in] value Pointer to the 512-bit value to write to the register.
* @param[in] csr_space The CSR space to read from. Default is 0.
*
*/
void write_csr512(uint64_t offset, const void *value, uint32_t csr_space = 0);
/** Retrieve a pointer to the MMIO region.
* @param[in] offset The byte offset to add to MMIO base.
* @param[in] csr_space The desired CSR space. Default is 0.
* @return MMIO base + offset
*/
uint8_t *mmio_ptr(uint64_t offset, uint32_t csr_space = 0) const;
/** Open an accelerator resource, given a raw fpga_token
*
* @param[in] token A token describing the accelerator
* resource to be allocated.
*
* @param[in] flags The flags parameter to fpgaOpen().
*
* @return pointer to the mmio base + offset for the given
* csr space
*
*/
static handle::ptr_t open(fpga_token token, int flags);
/** Open an accelerator resource, given a token object
*
* @param[in] token A token object describing the
* accelerator resource to be allocated.
*
* @param[in] flags The flags parameter to fpgaOpen().
*
* @return shared ptr to a handle object
*/
static handle::ptr_t open(token::ptr_t token, int flags);
/** Reset the accelerator identified by this handle
*/
virtual void reset();
/** Close an accelerator resource (if opened)
*
* @return fpga_result indication the result of closing the
* handle or FPGA_EXCEPTION if handle is not opened
*
* @note This is available for explicitly closing a handle.
* The destructor for handle will call close.
*/
fpga_result close();
private:
handle(fpga_handle h);
fpga_handle handle_;
fpga_token token_;
};
} // end of namespace types
} // end of namespace fpga
} // end of namespace opae