blob: 919cd62593c0e872ff71f7f3e3901e1c5d561492 [file] [log] [blame]
Zane Shelley5a266612019-08-15 16:23:53 -05001/**
2 * @file hei_main.hpp
3 *
4 * These are the primary APIs for Hardware Error Isolation (aka the isolator).
5 * The intended flow is to:
6 *
7 * - Call initialize() for each necessary Chip Data File.
8 *
Zane Shelleyb406de42019-09-09 16:10:38 -05009 * - Call isolate() for all chips that need error isolation.
Zane Shelley5a266612019-08-15 16:23:53 -050010 *
11 * - Once isolation is no longer needed, call uninitialize() to free up
12 * resources used for isolation.
13 *
14 * Note that initialize() allocates many objects used for isolation and keeps
15 * them in memory. Its purpose is to avoid initializing the objects each time
16 * isolation is required. The data provided by the Chip Data Files is static.
17 * So reinitializing would be a waste of time, unless for some reason the Chip
18 * Data Files themselves are updated, which would require reinitialization
19 * anyway. Of course, leaving the object in memory chews up resources. So, some
20 * users may need to weigh performance vs. memory usage.
Zane Shelleydd109cc2020-04-30 21:41:41 -050021 *
22 * If data for a specific chip type changes and needs to be reinitialized, the
23 * user application must reinitialize all chip data as follows:
24 *
25 * - Call uninitialize() to flush isolation objects for ALL chip types.
26 *
27 * - Call initialize() for ALL necessary Chip Data Files.
Zane Shelley5a266612019-08-15 16:23:53 -050028 */
29
30#pragma once
31
32#include <hei_includes.hpp>
33#include <hei_isolation_data.hpp>
34#include <isolator/hei_isolator.hpp>
35
36namespace libhei
37{
38
39/**
40 * @brief Initializes all isolation objects based on data from the given Chip
41 * Data File.
42 *
43 * This function only takes one Chip Data File at a time. Therefore, the
44 * user application must call this function for each Chip Data File required
45 * for isolation.
46 *
47 * Storage and management of the Chip Data Files will vary per user application.
48 * Therefore, the user application is responsible for loading the Chip Data
49 * Files into memory as needed, and providing the location and size of the data.
50 *
51 * Once this function returns, the Chip Data File is no longer needed in memory.
52 *
53 * Details of the Chip Data File format can be found in CHIP_DATA.md.
54 *
Zane Shelleydd109cc2020-04-30 21:41:41 -050055 * IMPORTANT:
56 * This function will build and store objects as it is parsing the Chip Data
57 * Files. It will assert:
58 * - Each file is the proper format and contains valid data.
59 * - No two files can share the same chip model/level.
60 * This ensures that the isolator does not use a partial (possibly invalid) or
61 * duplicate set of objects.
62 *
63 * @param i_buffer A pointer to the buffer containing a single Chip Data File.
Zane Shelley5a266612019-08-15 16:23:53 -050064 *
65 * @param i_bufferSize The size (in bytes) of the target Chip Data File.
Zane Shelley5a266612019-08-15 16:23:53 -050066 */
Zane Shelleydd109cc2020-04-30 21:41:41 -050067inline void initialize(void* i_buffer, size_t i_bufferSize)
Zane Shelley5a266612019-08-15 16:23:53 -050068{
Zane Shelleydd109cc2020-04-30 21:41:41 -050069 Isolator::getSingleton().initialize(i_buffer, i_bufferSize);
Zane Shelley5a266612019-08-15 16:23:53 -050070}
71
72/**
73 * @brief Deletes all internal isolation objects that were created by
74 * initialize().
75 */
76inline void uninitialize()
77{
78 Isolator::getSingleton().uninitialize();
79}
80
81/**
Zane Shelleyb406de42019-09-09 16:10:38 -050082 * @brief Isolates all active hardware errors found on the given list of chips.
Zane Shelley5a266612019-08-15 16:23:53 -050083 *
Zane Shelley229c1552020-05-04 22:44:15 -050084 * This functions will assert that initialize() has been called for each Chip
85 * Data File corresponding to the given chip types.
Zane Shelley5a266612019-08-15 16:23:53 -050086 *
Zane Shelleyb406de42019-09-09 16:10:38 -050087 * @param i_chipList The list of all chips that need to be analyzed. Generally,
88 * this would include all processor and memory chips in the
89 * system.
90 *
91 * @param o_isoData Initially, all data in the object will be flushed and then
92 * repopulated with a list of all active hardware errors found
93 * on the given list of chips, the contents of any registers
94 * associated with the active errors, and any other data that
95 * can be useful for debug.
Zane Shelley5a266612019-08-15 16:23:53 -050096 */
Zane Shelley229c1552020-05-04 22:44:15 -050097inline void isolate(const std::vector<Chip>& i_chipList,
98 IsolationData& o_isoData)
Zane Shelley5a266612019-08-15 16:23:53 -050099{
Zane Shelley229c1552020-05-04 22:44:15 -0500100 Isolator::getSingleton().isolate(i_chipList, o_isoData);
Zane Shelley5a266612019-08-15 16:23:53 -0500101}
102
103} // end namespace libhei