// 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 #include #include #include #include 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 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