1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
// vim:expandtab:autoindent:tabstop=4:shiftwidth=4:filetype=c:
//
//Do not use "\section", "\subsection", or other page-related commands here as
//this file is inlined in the ISmbios.h file.
//
/** \page smbios_theory Smbios Table Overview
*
* <b>Theory of Operation</b>
*
* <p>The SmbiosTable is meant to model the system SMBIOS table as a standard
* C++ data object. The system SMBIOS table most closely resembles a C++ STL
* vector class that happens to be read-only (const). We have chosen to
* implement the ISmbiosTable class so that it follows closely the STL
* standard containers. If you have used iterators to traverse
* a vector, or the [] operator, then you should be able to use the
* ISmbiosTable easily. The only difference here is that the [] operator
* takes as input the \a type of smbios item you wish to pull from the
* table, rather than an array index.
*
* The SmbiosTable class maintains it's own buffer that mirrors the contents
* of the actual system SMBIOS table. This is for efficiency reasons, as the
* table has a max length of 64k, and each access of the table potentially
* has to do special OS calls to re-read the data. There is a de-cache and
* reset API to tell the class to re-read data from main memory for the case
* of SMBIOS tables that are dynamically updated by firmware.
*
* <b>Object Ownership Rules</b>
*
* There are several types of objects that client code will have to deal
* with. Described below are the ownership semantics for the following
* objects:
* \li smbios::SmbiosFactory
* \li smbios::ISmbiosTable
* \li smbios::ISmbiosItem
*
* smbios::SmbiosFactory objects are singleton objects and may not be deleted.
* The only way to safely reclaim memory from a factory is to run the
* ->reset() method call, which will delete the factory and any
* factory-owned ISmbiosTable instances.
*
* smbios::ISmbiosTable objects are owned by the SmbiosFactory if the table is
* created with the getSingleton() method call. The client should not
* attempt to keep Table references past the point where the factory is
* reset(). If you get the ISmbiosTable object via the
* makeNew() you own the resulting table object and must delete() it.
*
* smbios::ISmbiosItem objects that are given out in response to Queries
* (smbios::ISmbiosTable::operator[]()or the iterator object), are owned by
* the Table. The client should never attempt to A) keep Item references
* past the lifetime of the
* containing table, or B) delete the Item.
*
* <b>Class Heirarchy Description</b>
* <p> The class heirarchy is based upon ISmbiosTable at the top level. This
* class is a pure virtual Abstract Base Class that provides the public
* interfact that outside clients can use. All of the operations that you
* can do on the Table are modeled in the ISmbiosTable class.
*
* The inheritance heirarchy is based around the concept that, no matter
* which OS or platform you are running on, the actual table data and
* parsing is going to be exactly the same. Because of this, all operations
* that operate on table data (parsing header, parsing out items), are
* implemented in the SmbiosTable class, which is a direct subclass of
* ISmbiosTable.
*
* The next level of the heirarchy is where we abstract the different
* methods of actually getting the table. This layer is different among the
* different OSs. This layer is responsible for loading the data items in
* SmbiosTable, and is implemented in SmbiosTableFileIo and
* SmbiosTableMemory. These two classes either load data from a file or from
* memory, respectively. File loading is used in the unit tests.
*
* The last detail of the inheritance heirarchy is that the methods that use
* XML to assist in parsing smbios data are separated into their own class.
* This is done for space and dependency reasons. First, the smbios without
* xml parsing is smaller. Next, xml parsing implies an additional runtime
* dependency on xerces, which is the xml library we use to parse xml. The
* classes which implement this are SmbiosTableXml and
* SmbiosTableXmlOsSpecific
*
* <b>Using the ISmbiosTable interface</b>
*
* \dontinclude testStandalone.cpp
* To use the ISmbiosTable interface, first you must instantiate an object
* with an ISmbiosTable interface. Since ISmbiosTable is a pure abstract
* class, you cannot directly instantiate an object of this type. The way to
* get a pointer to an ISmbiosTable class is by using the SmbiosFactory.
* \skip BEGIN EXAMPLE factory
* \skipline //
* \until getFactory
*
* Once you have a pointer to an ISmbiosTable object, you normally want to
* find items of a given type. This example uses the XML enhanced method,
* looking up the text in the XML file and finding the corresponding item:
* \skipline smbios::ISmbiosTable::iterator
*
* After you have a pointer to an item, you can pull out information from
* that item. Again, the string is converted to an int inside the class by
* looking the text up in XML:
* \skipline getU8
*
* <b>Using the iterator interface</b>
* <p>When there is more than one item of a given type in the table and you
* want to get data from each one, you should use the iterator pattern.
*
* To use the iterator, you instantiate the table the same way using the factory:
* \dontinclude testStandalone.cpp
* \skip BEGIN EXAMPLE iterator
* \skipline //
* \until getSingleton
*
* You can then iterate over the list of items using a for() or while()
* loop. This example prints out each item to a stream:
* \skipline // iterate
* \until }
*
*
* \todo
* The last couple of things that need to be added to ISmbiosTable to
* complete the API are:
* \li Add accessor functions for the different header fields in the
* Smbios Table Entry Point.
* \li Add a function to explicitly check the checksums stored in the
* Entry Point.
*
* \todo
* Need to remove the itemList member variable from ISmbiosTable.
* It needs to be put into SmbiosTable (private implementation class),
* and we need to provide a set of functions that the iterator can use in
* its place.
*/
|
