blob: 09cbcfb9b1dcc15ad1ba43818ca94478837fea55 [file] [log] [blame]
#pragma once
/**
* @file hei_user_interface.hpp
*
* The process for actions like hardware register access will vary per user
* application. Therefore, the user application must define all of the APIs
* declared in this header file.
*/
#include <stdlib.h>
#include <hei_chip.hpp>
namespace libhei
{
/**
* @brief Performs a hardware register read operation.
*
* @param i_chip The target chip for the register access. It is provided to
* the isolator by the user application via the isolator main
* APIs.
*
* @param o_buffer Allocated memory space for the returned contents of the
* register.
*
* @param io_bufSize The input parameter is the maximum size of the allocated
* o_buffer. The return value is the number of bytes actually
* written to the buffer.
*
* @param i_regType The user application may support different types of
* registers. This value is provided to the isolator by the
* user application via the Chip Data Files. The user
* application is responsible for knowing what to do with this
* parameter.
*
* @param i_address The register address. The values is a 1, 2, 4, or 8 byte
* address (right justified), which is provided to the
* isolator by the user application via the Chip Data Files.
*
* @return false => register access was successful
* true => hardware access failure
* Note that in the case of a failure, the user application is
* responsible for reporting why the register access failed.
*/
bool registerRead(const Chip& i_chip, void* o_buffer, size_t& io_bufSize,
uint64_t i_regType, uint64_t i_address);
#ifdef __HEI_ENABLE_HW_WRITE
/**
* @brief Performs a hardware register write operation.
*
* @param i_chip The target chip for the register access. It is provided to
* the isolator by the user application via the isolator main
* APIs.
*
* @param i_buffer Allocated memory space containing the register contents to
* write to hardware.
*
* @param io_bufSize The input parameter is the number of byte from i_buffer to
* write to the hardware register. The return value is the
* actual number of bytes written to the hardware register.
*
* @param i_regType The user application may support different types of
* registers. This value is provided to the isolator by the
* user application via the Chip Data Files. The user
* application is responsible for knowing what to do with this
* parameter.
*
* @param i_address The register address. The values is a 1, 2, 4, or 8 byte
* address (right justified), which is provided to the
* isolator by the user application via the Chip Data Files.
*
* @return false => register access was successful
* true => hardware access failure
* Note that in the case of a failure, the user application is
* responsible for reporting why the register access failed.
*/
bool registerWrite(const Chip& i_chip, void* i_buffer, size_t& io_bufSize,
uint64_t i_regType, uint64_t i_address);
#endif // __HEI_ENABLE_HW_WRITE
/**
* @brief Prints an informational trace/log.
*
* This is similar to printing a single line of text to stdout. Example
* implementation:
* void hei_inf(char* format, ...)
* {
* va_list args;
* va_start(args, format);
* vfprintf(stdout, format, args);
* va_end(args);
* fprintf(stdout, "\n");
* }
*
* @param i_format The string format and variatic arguments.
*/
void hei_inf(char* i_format, ...);
/**
* @brief Prints an error trace/log.
*
* This is similar to printing a single line of text to stderr. Example
* implementation:
* void hei_inf(char* format, ...)
* {
* va_list args;
* va_start(args, format);
* vfprintf(stderr, format, args);
* va_end(args);
* fprintf(stderr, "\n");
* }
*
* @param i_format The string format and variatic arguments.
*/
void hei_err(char* i_format, ...);
} // end namespace libhei