src/hei_user_interface.hpp

#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