// 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/handle.h>
#include <opae/cxx/core/token.h>
#include <opae/types.h>
namespace opae {
namespace fpga {
namespace types {
/** Wraps the OPAE fpga_object primitive.
* sysobject's are created from a call to fpgaTokenGetObject,
* fpgaHandleGetObject, or fpgaObjectGetObject
*/
class sysobject {
public:
typedef std::shared_ptr<sysobject> ptr_t;
sysobject() = delete;
sysobject(const sysobject &o) = delete;
sysobject &operator=(const sysobject &o) = delete;
/**
* @brief Get a sysobject from a token. This will be read-only.
*
* @param[in] t Token object representing a resource.
* @param[in] name An identifier representing an object belonging to a
* resource represented by the token.
* @param[in] flags Control behavior of object identification and creation.
* FPGA_OBJECT_GLOB is used to indicate that the name should be treated as a
* globbing expression. FPGA_OBJECT_RECURSE_ONE indicates that subobjects be
* created for objects one level down from the object identified by name.
* FPGA_OBJECT_RECURSE_ALL indicates that subobjects be created for all
* objects below the current object identified by name.
*
* @return A shared_ptr to a sysobject instance.
*/
static sysobject::ptr_t get(token::ptr_t t, const std::string &name,
int flags = 0);
/**
* @brief Get a sysobject from a handle. This will be read-write.
*
* @param[in] h Handle object representing an open resource.
* @param[in] name An identifier representing an object belonging to a
* resource represented by the handle.
* @param[in] flags Control behavior of object identification and creation.
* FPGA_OBJECT_GLOB is used to indicate that the name should be treated as a
* globbing expression. FPGA_OBJECT_RECURSE_ONE indicates that subobjects be
* created for objects one level down from the object identified by name.
* FPGA_OBJECT_RECURSE_ALL indicates that subobjects be created for all
* objects below the current object identified by name.
*
* @return A shared_ptr to a sysobject instance.
*/
static sysobject::ptr_t get(handle::ptr_t h, const std::string &name,
int flags = 0);
/**
* @brief Get a sysobject from an object. This will be read-write if its
* parent was created from a handle..
*
* @param[in] name An identifier representing an object belonging to this
* object.
* @param[in] flags Control behavior of object identification and creation.
* FPGA_OBJECT_GLOB is used to indicate that the name should be treated as a
* globbing expression. FPGA_OBJECT_RECURSE_ONE indicates that subobjects be
* created for objects one level down from the object identified by name.
* FPGA_OBJECT_RECURSE_ALL indicates that subobjects be created for all
* objects. Flags are defaulted to 0 meaning no flags.
*
* @return A shared_ptr to a sysobject instance.
*/
sysobject::ptr_t get(const std::string &name, int flags = 0);
/**
* @brief Get a sysobject from a container object. This will be read-write if
* its parent was created from a handle..
*
* @param[in] index An index number to get.
*
* @return A shared_ptr to a sysobject instance.
*/
sysobject::ptr_t get(int index);
virtual ~sysobject();
/**
* @brief Get the size (in bytes) of the object.
*
* @return The number of bytes that the object occupies in memory.
*/
uint32_t size() const;
/**
* @brief Read a 64-bit value from an FPGA object.
* The value is assumed to be in string format and will be parsed. See flags
* below for changing that behavior.
*
* @param[in] flags Flags that control how the object is read
* If FPGA_OBJECT_SYNC is used then object will update its buffered copy
* before retrieving the data. If FPGA_OBJECT_RAW is used, then the data
* will be read as raw bytes into the uint64_t pointer variable. Flags
* are defaulted to 0 meaning no flags.
*
* @return A 64-bit value from the object.
*/
uint64_t read64(int flags = 0) const;
/**
* @brief Write 64-bit value to an FPGA object.
* The value will be converted to string before writing. See flags below for
* changing that behavior.
*
* @param[in] value The value to write to the object.
* @param[in] flags Flags that control how the object is written
* If FPGA_OBJECT_RAW is used, then the value will be written as raw bytes.
* Flags are defaulted to 0 meaning no flags.
*
* @note This operation will force a sync operation to update its cached
* buffer
*/
void write64(uint64_t value, int flags = 0) const;
/**
* @brief Get all raw bytes from the object.
*
* @param[in] flags Flags that control how object is read
* If FPGA_OBJECT_SYNC is used then object will update its buffered copy
* before retrieving the data.
*
* @return A vector of all bytes in the object.
*/
std::vector<uint8_t> bytes(int flags = 0) const;
/**
* @brief Get a subset of raw bytes from the object.
*
* @param[in] offset The bytes offset for the start of the returned vector.
* @param[in] size The number of bytes for the returned vector.
* @param[in] flags Flags that control how object is read
* If FPGA_OBJECT_SYNC is used then object will update its buffered copy
* before retrieving the data.
*
* @return A vector of size bytes in the object starting at offset.
*/
std::vector<uint8_t> bytes(uint32_t offset, uint32_t size,
int flags = 0) const;
/** Get the object type (attribute or container)
*/
enum fpga_sysobject_type type() const;
/** Retrieve the underlying fpga_object primitive.
*/
fpga_object c_type() const { return sysobject_; }
/** Retrieve the underlying fpga_object primitive.
*/
operator fpga_object() const { return sysobject_; }
private:
sysobject(fpga_object sysobj, token::ptr_t token, handle::ptr_t hnd);
fpga_object sysobject_;
token::ptr_t token_;
handle::ptr_t handle_;
};
} // end of namespace types
} // end of namespace fpga
} // end of namespace opae