Zane Shelley | 465e0b3 | 2019-04-17 10:15:39 -0500 | [diff] [blame] | 1 | #pragma once |
| 2 | |
Zane Shelley | a61f4c5 | 2019-08-01 13:58:49 -0500 | [diff] [blame] | 3 | #include "hei_includes.hpp" |
| 4 | #include "hei_isolation_data.hpp" |
| 5 | #include "chip_data/hei_chip_data.hpp" |
Zane Shelley | 465e0b3 | 2019-04-17 10:15:39 -0500 | [diff] [blame] | 6 | |
Zane Shelley | 814b1e3 | 2019-06-17 20:55:04 -0500 | [diff] [blame] | 7 | namespace libhei |
Zane Shelley | 465e0b3 | 2019-04-17 10:15:39 -0500 | [diff] [blame] | 8 | { |
| 9 | |
Zane Shelley | a61f4c5 | 2019-08-01 13:58:49 -0500 | [diff] [blame] | 10 | /** |
| 11 | * @brief This is the main API for Hardware Error Isolation (aka the isolator). |
| 12 | * |
| 13 | * The intended flow is to: |
| 14 | * - Create a singleton instance of an Isolator object. |
| 15 | * - Use initialize() to input each necessary Chip Data File (provided by the |
| 16 | * user application). |
| 17 | * - Call isolate() each time you want to find all active errors being |
| 18 | * reported by a chip. |
| 19 | * - Once isolation is no longer needed, the Isolator singleton can be deleted |
| 20 | * to free up internal resources. |
| 21 | * |
| 22 | * The purpose of the singleton instance is to avoid initializing the object |
| 23 | * each time isolation is required. The data provided by the Chip Data Files is |
| 24 | * static. So reinitializing would be a waste of time, unless for some reason |
| 25 | * the Chip Data Files themselves are updated, which would require |
| 26 | * reinitialization anyway. Of course, leaving the object in memory chews up |
| 27 | * resources. So, some users may need to weigh performance vs. memory usage. |
| 28 | */ |
Zane Shelley | 465e0b3 | 2019-04-17 10:15:39 -0500 | [diff] [blame] | 29 | class Isolator |
| 30 | { |
| 31 | public: |
| 32 | |
Zane Shelley | a61f4c5 | 2019-08-01 13:58:49 -0500 | [diff] [blame] | 33 | /** @brief Default constructor. */ |
| 34 | Isolator() = default; |
Zane Shelley | 465e0b3 | 2019-04-17 10:15:39 -0500 | [diff] [blame] | 35 | |
Zane Shelley | a61f4c5 | 2019-08-01 13:58:49 -0500 | [diff] [blame] | 36 | /** @brief Destructor. */ |
| 37 | ~Isolator() = default; |
Zane Shelley | 465e0b3 | 2019-04-17 10:15:39 -0500 | [diff] [blame] | 38 | |
Zane Shelley | a61f4c5 | 2019-08-01 13:58:49 -0500 | [diff] [blame] | 39 | /** @brief Copy constructor. */ |
| 40 | Isolator( const Isolator & ) = delete; |
Zane Shelley | 465e0b3 | 2019-04-17 10:15:39 -0500 | [diff] [blame] | 41 | |
Zane Shelley | a61f4c5 | 2019-08-01 13:58:49 -0500 | [diff] [blame] | 42 | /** @brief Assignment operator. */ |
| 43 | Isolator & operator=( const Isolator & ) = delete; |
| 44 | |
| 45 | /** |
| 46 | * @brief Initializes internal isolation objects based on data from the |
| 47 | * given Chip Data File. |
| 48 | * |
| 49 | * This function only takes one Chip Data File at a time. Therefore, the |
| 50 | * user application must call this function for each Chip Data File required |
| 51 | * for isolation. |
| 52 | * |
| 53 | * Storage and management of the Chip Data Files will vary per user |
| 54 | * application. Therefore, the user application is responsible for loading |
| 55 | * the Chip Data Files into memory, as needed, and providing the location |
| 56 | * and size of the data. |
| 57 | * |
| 58 | * Once initialization has successfully completed with a Chip Data File, the |
| 59 | * file is no longer needed in memory. |
| 60 | * |
| 61 | * Details of the Chip Data File format can be found in CHIP_DATA.md. |
| 62 | * |
| 63 | * @param i_buffer A pointer to the buffer containing a single Chip |
| 64 | * Data File. |
| 65 | * |
| 66 | * @param i_bufferSize The size (in bytes) of the target Chip Data File. |
| 67 | * |
| 68 | * @param i_forceInit It is possible the user application could call this |
| 69 | * function for a chip type that has already been |
| 70 | * initialized. This is useful if for some reason the |
| 71 | * Chip Data File is for a chip type has been updated. |
| 72 | * If this function is called and a chip type has |
| 73 | * already been initialized: |
| 74 | * - false (default), the function will return |
| 75 | * RC_CDF_INITIALIZED and exit. |
| 76 | * - true, the function will delete previous isolation |
| 77 | * objects for this chip type and reinitialize. |
| 78 | * |
| 79 | * @return RC_SUCCESS or RC_CDF_INVALID or RC_CDF_INITIALIZED |
| 80 | */ |
| 81 | ReturnCode initialize( void * i_buffer, size_t i_bufferSize, |
| 82 | bool i_forceInit = false ); |
| 83 | |
| 84 | /** |
| 85 | * @brief Isolates all active hardware errors found on the given chip. |
| 86 | * |
| 87 | * This functions requires initialize() to be called with the Chip Data File |
| 88 | * corresponding to the given chip type. |
| 89 | * |
| 90 | * @param i_chip This is simply a pointer to a user application object |
| 91 | * that represents the target chip. The isolator does not |
| 92 | * know anything about this object or how to use it. This |
| 93 | * parameter's only purpose is to eventually get passed |
| 94 | * back to the user application in a deviceRead() |
| 95 | * operation. |
| 96 | * |
| 97 | * @param i_chipType Each Chip Data File contains a unique chip type |
| 98 | * identifier. The user application will need to input |
| 99 | * this value so the isolator will know which set of the |
| 100 | * isolation objects to reference. |
| 101 | * |
| 102 | * @param o_isoData This return object will contain a list of all active |
| 103 | * hardware errors on this chip, the contents of any |
| 104 | * registers associated with the active errors, and any |
| 105 | * other data that can be useful for debug. |
| 106 | * |
| 107 | * @return RC_SUCCESS or RC_CHIP_DATA_MISSING |
| 108 | */ |
| 109 | ReturnCode isolate( void * i_chip, ChipType_t i_chipType, |
| 110 | IsolationData & o_isoData ); |
Zane Shelley | 465e0b3 | 2019-04-17 10:15:39 -0500 | [diff] [blame] | 111 | |
| 112 | private: |
| 113 | |
| 114 | }; // end class Isolator |
| 115 | |
Zane Shelley | 814b1e3 | 2019-06-17 20:55:04 -0500 | [diff] [blame] | 116 | } // end namespace libhei |