sysobject.h

// 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 <opae/types.h>

#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__ */