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
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
/* IBM_PROLOG_BEGIN_TAG
* This is an automatically generated prolog.
*
* $Source: src/include/usr/hwpf/fapi/fapiAttributeService.H $
*
* IBM CONFIDENTIAL
*
* COPYRIGHT International Business Machines Corp. 2011-2012
*
* p1
*
* Object Code Only (OCO) source materials
* Licensed Internal Code Source Materials
* IBM HostBoot Licensed Internal Code
*
* The source code for this program is not published or other-
* wise divested of its trade secrets, irrespective of what has
* been deposited with the U.S. Copyright Office.
*
* Origin: 30
*
* IBM_PROLOG_END_TAG
*/
/**
* @file fapiAttributeService.H
*
* @brief Defines the FAPI_ATTR_GET and FAPI_ATTR_SET macros that a user calls
* to get/set attributes and a check function that the macros use to
* verify correct usage
*/
/*
* Change Log ******************************************************************
* Flag Defect/Feature User Date Description
* ------ -------------- ---------- ----------- ----------------------------
* mjjones 06/06/2011 Created.
* mjjones 06/22/2011 Major updates
* mjjones 09/06/2011 Remove support for strings
* mjjones 09/22/2011 Fixed example
* mjjones 10/13/2011 Added fapiGetInitFileAttr
* camvanng 10/20/2011 Changed i_pTarget to "const"
* ptr
* mjjones 04/10/2012 Support for privileged atts
* mjjones 06/07/2012 Add attr override support
*/
#ifndef FAPIATTRIBUTESERVICE_H_
#define FAPIATTRIBUTESERVICE_H_
#include <stdint.h>
#include <fapiAttributeIds.H>
#include <fapiPlatAttributeService.H>
/**
* @brief Macros called by user to get/set attributes
*
* Code must have a pointer to a Target and an attribute ID (from XML file):
* fapi::ReturnCode l_rc;
* fapi::Target * l_pTarget = ????;
*
* To get a copy of an integer attribute and set the attribute
* uint64_t l_val = 0;
* l_rc = FAPI_ATTR_GET(<ID>, l_pTarget, l_val);
* l_rc = FAPI_ATTR_SET(<ID>, l_pTarget, l_val);
*
* To get a copy of an integer array attribute and set the attribute
* uint32_t l_pVal[4] = {0};
* l_rc = FAPI_ATTR_GET(<ID>, l_pTarget, l_pVal);
* l_rc = FAPI_ATTR_SET(<ID>, l_pTarget, l_pVal);
*
* A priveleged attribute is one that a HWP should not generally access,
* examples include ATTR_NAME and ATTR_EC, where usage can lead to a non
* data-driven design. A privileged attribute can be accessed with
* FAPI_ATTR_GET_PRIVILEGED and FAPI_ATTR_SET_PRIVILEGED
*
* The non-PRIVILEGED macros first call a template function (compiler will
* optimize out) that will cause a compile failure if the attribute is
* privileged, they then call a PRIVILEGED macro to get/set the attribute
*
* The PRIVILEGED macros call a template function (compiler will optimize out)
* that will cause a compile failure if the ID is not valid or VAL is not the
* correct type.
* The GET macro calls the FAPI_PLAT_GET_ATTR_OVERRIDE PLAT macro to find if
* there is an attribute override value to return (platforms can set this to
* false if they do not support attribute override or if they handle it in
* the standard <ID>_GETMACRO path), if this returns false then the
* <ID>_GETMACRO PLAT macro is called to get the attribute, platforms must
* define a _GETMACRO for each attribute.
*
* The SET macro calls the <ID>_SETMACRO PLAT macro to set the attribute,
* platforms must define a _SETMACRO for each attribute. It then calls the
* FAPI_PLAT_CLEAR_NON_CONST_ATTR_OVERRIDE to clear any non-const attribute
* overrides (platforms can set this to NULL if they do not support
* attribute override or if they handle it in the standard <ID>_SETMACRO
* path).
*
* Note that a const attribute override is one that is always returned on a
* FAPI_ATTR_GET even if a subsequent FAPI_ATTR_SET is done. A non-const
* attribute override is one that is cleared when a FAPI_ATTR_SET is done
*/
#define FAPI_ATTR_GET(ID, PTARGET, VAL) \
(fapi::fapiFailIfPrivileged<fapi::ID##_Privileged>(), \
fapi::fapiCheckIdType<fapi::ID##_Type>(fapi::ID, VAL), \
FAPI_PLAT_GET_ATTR_OVERRIDE(fapi::ID, PTARGET, VAL) ? \
fapi::FAPI_RC_SUCCESS \
: ID##_GETMACRO(ID, PTARGET, VAL))
#define FAPI_ATTR_SET(ID, PTARGET, VAL) \
(fapi::fapiFailIfPrivileged<fapi::ID##_Privileged>(), \
fapi::fapiCheckIdType<fapi::ID##_Type>(fapi::ID, VAL), \
FAPI_PLAT_CLEAR_NON_CONST_ATTR_OVERRIDE(fapi::ID, PTARGET), \
ID##_SETMACRO(ID, PTARGET, VAL))
#define FAPI_ATTR_GET_PRIVILEGED(ID, PTARGET, VAL) \
(fapi::fapiCheckIdType<fapi::ID##_Type>(fapi::ID, VAL), \
FAPI_PLAT_GET_ATTR_OVERRIDE(fapi::ID, PTARGET, VAL) ? \
fapi::FAPI_RC_SUCCESS \
: ID##_GETMACRO(ID, PTARGET, VAL))
#define FAPI_ATTR_SET_PRIVILEGED(ID, PTARGET, VAL) \
(fapi::fapiCheckIdType<fapi::ID##_Type>(fapi::ID, VAL), \
FAPI_PLAT_CLEAR_NON_CONST_ATTR_OVERRIDE(fapi::ID, PTARGET), \
ID##_SETMACRO(ID, PTARGET, VAL))
namespace fapi
{
/**
* @brief Get an InitFile attribute
*
* This function gets a copy of an attribute. In the case of an array attribute,
* The value in the specified index is retrieved. This should be used by the
* InitFile HWP only, that HWP processes a binary InitFile and therefore needs
* to read a variable ID of a variable data type. Standard HWPs should use the
* FAPI_ATTR_GET macro which automatically checks the type for correct usage.
*
* If there are ever attributes with more than 4 dimensions then this function
* will need to be updated.
*
* @param[in] i_id AttributeID
* @param[in] i_pTarget Pointer to fapi::Target (can be NULL for system)
* @param[out] o_val Reference to uint64_t where attribute value is set
* @param[in] i_arrayIndex1 If array attribute then index1
* @param[in] i_arrayIndex2 If at least 2D array attribute then index2
* @param[in] i_arrayIndex3 If at least 3D array attribute then index3
* @param[in] i_arrayIndex4 If at least 4D array attribute then index4
*
* @return ReturnCode. Zero if success
*/
ReturnCode fapiGetInitFileAttr(const AttributeId i_id,
const Target * i_pTarget,
uint64_t & o_val,
const uint32_t i_arrayIndex1 = 0,
const uint32_t i_arrayIndex2 = 0,
const uint32_t i_arrayIndex3 = 0,
const uint32_t i_arrayIndex4 = 0);
/**
* @brief Check the ID and TYPE
*
* This is called by FAPI code to check at compile time that a FAPI attribute
* access is using the correct data type and a valid AttributeId
*/
template<typename T> void fapiCheckIdType(AttributeId, T &) {}
/**
* @brief Fail if attribute privileged
*
* This is called by FAPI code to check at compile time that a standard FAPI
* attribute access (FAPI_ATTR_GET) is not accessing a privileged attribute
*/
class ErrorAccessingPrivilegedAttribute;
template<const bool PRIVILEGED> void fapiFailIfPrivileged()
{
ErrorAccessingPrivilegedAttribute();
}
template <> inline void fapiFailIfPrivileged<false>() {}
}
#endif // FAPIATTRIBUTESERVICE_H_
|
