src/hei_main.hpp

/**
 * @file hei_main.hpp
 *
 * These are the primary APIs for Hardware Error Isolation (aka the isolator).
 * The intended flow is to:
 *
 *  - Call initialize() for each necessary Chip Data File.
 *
 *  - Call isolate() for each chip that needs error isolation.
 *
 *  - Once isolation is no longer needed, call uninitialize() to free up
 *    resources used for isolation.
 *
 * Note that initialize() allocates many objects used for isolation and keeps
 * them in memory. Its purpose is to avoid initializing the objects each time
 * isolation is required. The data provided by the Chip Data Files is static.
 * So reinitializing would be a waste of time, unless for some reason the Chip
 * Data Files themselves are updated, which would require reinitialization
 * anyway. Of course, leaving the object in memory chews up resources. So, some
 * users may need to weigh performance vs. memory usage.
 */

#pragma once

#include <hei_includes.hpp>
#include <hei_isolation_data.hpp>
#include <isolator/hei_isolator.hpp>

namespace libhei
{

/**
 * @brief Initializes all isolation objects based on data from the given Chip
 *        Data File.
 *
 * This function only takes one Chip Data File at a time. Therefore, the
 * user application must call this function for each Chip Data File required
 * for isolation.
 *
 * Storage and management of the Chip Data Files will vary per user application.
 * Therefore, the user application is responsible for loading the Chip Data
 * Files into memory as needed, and providing the location and size of the data.
 *
 * Once this function returns, the Chip Data File is no longer needed in memory.
 *
 * Details of the Chip Data File format can be found in CHIP_DATA.md.
 *
 * @param i_buffer     A pointer to the buffer containing a single Chip
 *                     Data File.
 *
 * @param i_bufferSize The size (in bytes) of the target Chip Data File.
 *
 * @param i_forceInit  It is possible the user application could call this
 *                     function for a chip type that has already been
 *                     initialized. This is useful if for some reason the Chip
 *                     Data File for a specific chip type has been updated. If
 *                     this function is called and a chip type has already been
 *                     initialized:
 *                      - false (default), the function will return
 *                        RC_CDF_INITIALIZED and exit.
 *                      - true, the function will delete the previous isolation
 *                        objects for this chip type and reinitialize.
 *
 * @return RC_SUCCESS or RC_CDF_INVALID or RC_CDF_INITIALIZED
 */
inline ReturnCode initialize( void * i_buffer, size_t i_bufferSize,
                              bool i_forceInit = false )
{
    return Isolator::getSingleton().initialize( i_buffer, i_bufferSize,
                                                i_forceInit );
}

/**
 * @brief Deletes all internal isolation objects that were created by
 *        initialize().
 */
inline void uninitialize()
{
    Isolator::getSingleton().uninitialize();
}

/**
 * @brief Isolates all active hardware errors found on the given chip.
 *
 * This functions requires initialize() to be called with the Chip Data File
 * corresponding to the given chip type.
 *
 * @param o_isoData  This parameter will contain a reference to the target chip
 *                   and its chip type. The rest of the data in the object will
 *                   be flushed and then repopulated with a list of all active
 *                   hardware errors on this chip, the contents of any
 *                   registers associated with the active errors, and any
 *                   other data that can be useful for debug.
 *
 * @return RC_SUCCESS or RC_CHIP_DATA_MISSING
 */
inline ReturnCode isolate( IsolationData & o_isoData )
{
    return Isolator::getSingleton().isolate( o_isoData );
}

} // end namespace libhei