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