blob: 7135f50057387a56693f5fa21c43265b748d1848 [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
Zane Shelley3a02e242020-05-08 16:25:36 -050032#include <hei_chip.hpp>
Zane Shelley5a266612019-08-15 16:23:53 -050033#include <hei_isolation_data.hpp>
Zane Shelley3a02e242020-05-08 16:25:36 -050034
35#include <vector>
Zane Shelley5a266612019-08-15 16:23:53 -050036
37namespace libhei
38{
39
40/**
41 * @brief Initializes all isolation objects based on data from the given Chip
42 * Data File.
43 *
44 * This function only takes one Chip Data File at a time. Therefore, the
45 * user application must call this function for each Chip Data File required
46 * for isolation.
47 *
48 * Storage and management of the Chip Data Files will vary per user application.
49 * Therefore, the user application is responsible for loading the Chip Data
50 * Files into memory as needed, and providing the location and size of the data.
51 *
52 * Once this function returns, the Chip Data File is no longer needed in memory.
53 *
54 * Details of the Chip Data File format can be found in CHIP_DATA.md.
55 *
Zane Shelleydd109cc2020-04-30 21:41:41 -050056 * IMPORTANT:
57 * This function will build and store objects as it is parsing the Chip Data
58 * Files. It will assert:
59 * - Each file is the proper format and contains valid data.
60 * - No two files can share the same chip model/level.
61 * This ensures that the isolator does not use a partial (possibly invalid) or
62 * duplicate set of objects.
63 *
64 * @param i_buffer A pointer to the buffer containing a single Chip Data File.
Zane Shelley5a266612019-08-15 16:23:53 -050065 *
66 * @param i_bufferSize The size (in bytes) of the target Chip Data File.
Zane Shelley5a266612019-08-15 16:23:53 -050067 */
Zane Shelley3a02e242020-05-08 16:25:36 -050068void initialize(void* i_buffer, size_t i_bufferSize);
Zane Shelley5a266612019-08-15 16:23:53 -050069
70/**
71 * @brief Deletes all internal isolation objects that were created by
72 * initialize().
73 */
Zane Shelley3a02e242020-05-08 16:25:36 -050074void uninitialize();
Zane Shelley5a266612019-08-15 16:23:53 -050075
76/**
Zane Shelleyb406de42019-09-09 16:10:38 -050077 * @brief Isolates all active hardware errors found on the given list of chips.
Zane Shelley5a266612019-08-15 16:23:53 -050078 *
Zane Shelley229c1552020-05-04 22:44:15 -050079 * This functions will assert that initialize() has been called for each Chip
80 * Data File corresponding to the given chip types.
Zane Shelley5a266612019-08-15 16:23:53 -050081 *
Zane Shelleyb406de42019-09-09 16:10:38 -050082 * @param i_chipList The list of all chips that need to be analyzed. Generally,
83 * this would include all processor and memory chips in the
84 * system.
85 *
86 * @param o_isoData Initially, all data in the object will be flushed and then
87 * repopulated with a list of all active hardware errors found
88 * on the given list of chips, the contents of any registers
89 * associated with the active errors, and any other data that
90 * can be useful for debug.
Zane Shelley5a266612019-08-15 16:23:53 -050091 */
Zane Shelley3a02e242020-05-08 16:25:36 -050092void isolate(const std::vector<Chip>& i_chipList, IsolationData& o_isoData);
Zane Shelley5a266612019-08-15 16:23:53 -050093
Ben Tyner552992a2021-04-15 10:57:17 -050094/**
95 * @brief Return build information string
96 *
97 * @return Build information string
98 */
99const char* getBuildInfo();
100
Zane Shelley5a266612019-08-15 16:23:53 -0500101} // end namespace libhei