// Copyright(c) 2017-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. /** * @file opae/sysobject.h * @brief Functions to read/write from system objects. * On Linux systems with the OPAE kernel driver, this is used to access sysfs * nodes created by the driver. */ #ifndef __FPGA_SYSOBJECT_H__ #define __FPGA_SYSOBJECT_H__ #include #ifdef __cplusplus extern "C" { #endif /** * @brief Create an `fpga_object` data structures. An `fpga_object` * is a handle to an FPGA resource which can be an attribute, register or * a container. This object is read-only. * * @param[in] token Token identifying a resource (accelerator or device) * @param[in] name A key identifying an object belonging to a resource. * @param[out] object Pointer to memory to store the object in * @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 FPGA_OK on success. FPGA_INVALID_PARAM if any of the supplied * parameters is invalid. FPGA_NOT_FOUND if an object cannot be found with the * given key. FPGA_NOT_SUPPORTED if this function is not supported by the * current implementation of this API. * * @note Names that begin with '.' or '/' or contain '..' are not allowed and * result in FPGA_INVALID_PARAM being returned * */ fpga_result fpgaTokenGetObject(fpga_token token, const char *name, fpga_object *object, int flags); /** * @brief Create an `fpga_object` data structure from a handle. * An `fpga_object` is a handle to an FPGA resource which can be an attribute, * register, or container. This object has read/write access.. * * @param[in] handle Handle identifying a resource (accelerator or device) * @param[in] name A key identifying an object belonging to a resource. * @param[out] object Pointer to memory to store the object in * @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 FPGA_OK on success. FPGA_INVALID_PARAM if any of the supplied * parameters is invalid. FPGA_NOT_FOUND if an object cannot be found with the * given key. FPGA_NOT_SUPPORTED if this function is not supported by the * current implementation of this API. * * @note Names that begin with '.' or '/' or contain '..' are not allowed and * result in FPGA_INVALID_PARAM being returned * */ fpga_result fpgaHandleGetObject(fpga_handle handle, const char *name, fpga_object *object, int flags); /** * @brief Create an `fpga_object` data structure from a parent object. An * `fpga_object` is a handle to an FPGA resource which can be an attribute, * register, or container. If the parent object was created with a handle, * then the new object will inherit the handle allowing it to have read-write * access to the object data. * * @param[in] parent A parent container `fpga_object`. * @param[in] name A key identifying a sub-object of the parent container. * @param[out] object Pointer to memory to store the object in. * @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 FPGA_OK on success. FPGA_INVALID_PARAM if any of the supplied * parameters is invalid - this includes a parent object that is not a * container object. FPGA_NOT_FOUND if an object cannot be found with the given * key. FPGA_NOT_SUPPORTED if this function is not supported by the current * implementation of this API. * * @note Names that begin with '.' or '/' or contain '..' are not allowed and * result in FPGA_INVALID_PARAM being returned * */ fpga_result fpgaObjectGetObject(fpga_object parent, const char *name, fpga_object *object, int flags); /** * @brief Create an `fpga_object` data structure from a parent object using a * given index. An `fpga_object` is a handle to an FPGA resource which can be * an attribute, register, or container. If the parent object was created with * a handle, then the new object will inherit the handle allowing it to have * read-write access to the object data. * * @param[in] parent A parent container 'fpga_object' * @param[in] idx A positive index less than the size reported by the parent. * @param[out] object Pointer to memory to store the object in. * * @return FPGA_OK on success. FPGA_INVALID_PARAM if any of the supplied * parameters is invalid - this includes a parent object that is not a * container object. FPGA_NOT_FOUND if an object cannot be found with the given * key. FPGA_NOT_SUPPORTED if this function is not supported by the current * implementation of this API. */ fpga_result fpgaObjectGetObjectAt(fpga_object parent, size_t idx, fpga_object *object); /** * @brief Get the sysobject type (container or attribute) * * @param[in] obj An fpga_object instance * @param[out] type The type of object (FPGA_OBJECT_CONTAINER or * FPGA_OBJECT_ATTRIBUTE) * * @return FPGA_OK on success, FPGA_INVALID_PARAM if any of the supplied * parameters are null or invalid */ fpga_result fpgaObjectGetType(fpga_object obj, enum fpga_sysobject_type *type); /** * @brief Free memory used for the fpga_object data structure * * @note fpgaDestroyObject() requires the address of an fpga_object * as created by fpgaTokenGetObject(), fpgaHandleGetObject(), * or fpgaObjectGetObject(). Passing any other value results in * undefind behavior. * * @param obj Pointer to the fpga_object instance to destroy * * @return FPGA_OK on success, FPGA_INVALID_PARAM if the object is NULL, * FPGA_EXCEPTION if an internal error is encountered. */ fpga_result fpgaDestroyObject(fpga_object *obj); /** * @brief Retrieve the size of the object. * * @param[in] obj An fpga_object instance. * @param[out] value Pointer to variable to store size in. * @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 size. * * @return FPGA_OK on success. FPGA_INVALID_PARAM if any of supplied parameters * is invalid. FPGA_EXCEPTION if error occurred. */ fpga_result fpgaObjectGetSize(fpga_object obj, uint32_t *value, int flags); /** * @brief Read bytes from an FPGA object * * @param[in] obj An fpga_object instance. * @param[out] buffer Pointer to a buffer to read bytes into. * @param[in] offset Byte offset relative to objects internal buffer where to * begin reading bytes from. * @param[in] len The length, in bytes, to read 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 FPGA_OK on success, FPGA_INVALID_PARAM if any of the supplied * parameters is invalid */ fpga_result fpgaObjectRead(fpga_object obj, uint8_t *buffer, size_t offset, size_t len, int flags); /** * @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] obj An fpga_object instance * @param[out] value Pointer to a 64-bit variable to store the value in * @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. * * @return FPGA_OK on success, FPGA_INVALID_PARAM if any of the supplied * parameters is invalid */ fpga_result fpgaObjectRead64(fpga_object obj, uint64_t *value, int flags); /** * @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] obj An fpga_object instance. * @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. * * @return FPGA_OK on success, FPGA_INVALID_PARAM if any of the supplied * parameters is invalid * * @note The object must have been created using a handle to a resource. */ fpga_result fpgaObjectWrite64(fpga_object obj, uint64_t value, int flags); #ifdef __cplusplus } // extern "C" #endif // __cplusplus #endif /* !__FPGA_SYSOBJECT_H__ */