]>
Commit | Line | Data |
---|---|---|
c2c90b42 RN |
1 | /** @file\r |
2 | EFI NVDIMM Label Protocol Definition\r | |
3 | \r | |
4 | The EFI NVDIMM Label Protocol is used to Provides services that allow management\r | |
5 | of labels contained in a Label Storage Area that are associated with a specific\r | |
6 | NVDIMM Device Path.\r | |
7 | \r | |
8 | Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>\r | |
9344f092 | 9 | SPDX-License-Identifier: BSD-2-Clause-Patent\r |
c2c90b42 RN |
10 | \r |
11 | @par Revision Reference:\r | |
12 | This Protocol was introduced in UEFI Specification 2.7.\r | |
13 | \r | |
14 | **/\r | |
15 | \r | |
16 | #ifndef __EFI_NVDIMM_LABEL_PROTOCOL_H__\r | |
17 | #define __EFI_NVDIMM_LABEL_PROTOCOL_H__\r | |
18 | \r | |
19 | #define EFI_NVDIMM_LABEL_PROTOCOL_GUID \\r | |
20 | { \\r | |
21 | 0xd40b6b80, 0x97d5, 0x4282, {0xbb, 0x1d, 0x22, 0x3a, 0x16, 0x91, 0x80, 0x58 } \\r | |
22 | }\r | |
23 | \r | |
24 | typedef struct _EFI_NVDIMM_LABEL_PROTOCOL EFI_NVDIMM_LABEL_PROTOCOL;\r | |
25 | \r | |
26 | #define EFI_NVDIMM_LABEL_INDEX_SIG_LEN 16\r | |
27 | #define EFI_NVDIMM_LABEL_INDEX_ALIGN 256\r | |
28 | typedef struct {\r | |
29 | ///\r | |
30 | /// Signature of the Index Block data structure. Must be "NAMESPACE_INDEX\0".\r | |
31 | ///\r | |
32 | CHAR8 Sig[EFI_NVDIMM_LABEL_INDEX_SIG_LEN];\r | |
33 | \r | |
34 | ///\r | |
35 | /// Attributes of this Label Storage Area.\r | |
36 | ///\r | |
37 | UINT8 Flags[3];\r | |
38 | \r | |
39 | ///\r | |
40 | /// Size of each label in bytes, 128 bytes << LabelSize.\r | |
41 | /// 1 means 256 bytes, 2 means 512 bytes, etc. Shall be 1 or greater.\r | |
42 | ///\r | |
43 | UINT8 LabelSize;\r | |
44 | \r | |
45 | ///\r | |
46 | /// Sequence number used to identify which of the two Index Blocks is current.\r | |
47 | ///\r | |
48 | UINT32 Seq;\r | |
49 | \r | |
50 | ///\r | |
51 | /// The offset of this Index Block in the Label Storage Area.\r | |
52 | ///\r | |
53 | UINT64 MyOff;\r | |
54 | \r | |
55 | ///\r | |
56 | /// The size of this Index Block in bytes.\r | |
57 | /// This field must be a multiple of the EFI_NVDIMM_LABEL_INDEX_ALIGN.\r | |
58 | ///\r | |
59 | UINT64 MySize;\r | |
60 | \r | |
61 | ///\r | |
62 | /// The offset of the other Index Block paired with this one.\r | |
63 | ///\r | |
64 | UINT64 OtherOff;\r | |
65 | \r | |
66 | ///\r | |
67 | /// The offset of the first slot where labels are stored in this Label Storage Area.\r | |
68 | ///\r | |
69 | UINT64 LabelOff;\r | |
70 | \r | |
71 | ///\r | |
72 | /// The total number of slots for storing labels in this Label Storage Area.\r | |
73 | ///\r | |
74 | UINT32 NSlot;\r | |
75 | \r | |
76 | ///\r | |
77 | /// Major version number. Value shall be 1.\r | |
78 | ///\r | |
79 | UINT16 Major;\r | |
80 | \r | |
81 | ///\r | |
82 | /// Minor version number. Value shall be 2.\r | |
83 | ///\r | |
84 | UINT16 Minor;\r | |
85 | \r | |
86 | ///\r | |
87 | /// 64-bit Fletcher64 checksum of all fields in this Index Block.\r | |
88 | ///\r | |
89 | UINT64 Checksum;\r | |
90 | \r | |
91 | ///\r | |
92 | /// Array of unsigned bytes implementing a bitmask that tracks which label slots are free.\r | |
93 | /// A bit value of 0 indicates in use, 1 indicates free.\r | |
94 | /// The size of this field is the number of bytes required to hold the bitmask with NSlot bits,\r | |
95 | /// padded with additional zero bytes to make the Index Block size a multiple of EFI_NVDIMM_LABEL_INDEX_ALIGN.\r | |
96 | /// Any bits allocated beyond NSlot bits must be zero.\r | |
97 | ///\r | |
98 | UINT8 Free[];\r | |
99 | } EFI_NVDIMM_LABEL_INDEX_BLOCK;\r | |
100 | \r | |
101 | #define EFI_NVDIMM_LABEL_NAME_LEN 64\r | |
102 | \r | |
103 | ///\r | |
104 | /// The label is read-only.\r | |
105 | ///\r | |
106 | #define EFI_NVDIMM_LABEL_FLAGS_ROLABEL 0x00000001\r | |
107 | \r | |
108 | ///\r | |
109 | /// When set, the complete label set is local to a single NVDIMM Label Storage Area.\r | |
110 | /// When clear, the complete label set is contained on multiple NVDIMM Label Storage Areas.\r | |
111 | ///\r | |
112 | #define EFI_NVDIMM_LABEL_FLAGS_LOCAL 0x00000002\r | |
113 | \r | |
114 | ///\r | |
115 | /// This reserved flag is utilized on older implementations and has been deprecated.\r | |
116 | /// Do not use.\r | |
117 | //\r | |
118 | #define EFI_NVDIMM_LABEL_FLAGS_RESERVED 0x00000004\r | |
119 | \r | |
120 | ///\r | |
121 | /// When set, the label set is being updated.\r | |
122 | ///\r | |
123 | #define EFI_NVDIMM_LABEL_FLAGS_UPDATING 0x00000008\r | |
124 | \r | |
125 | typedef struct {\r | |
126 | ///\r | |
127 | /// Unique Label Identifier UUID per RFC 4122.\r | |
128 | ///\r | |
129 | EFI_GUID Uuid;\r | |
130 | \r | |
131 | ///\r | |
132 | /// NULL-terminated string using UTF-8 character formatting.\r | |
133 | ///\r | |
134 | CHAR8 Name[EFI_NVDIMM_LABEL_NAME_LEN];\r | |
135 | \r | |
136 | ///\r | |
137 | /// Attributes of this namespace.\r | |
138 | ///\r | |
139 | UINT32 Flags;\r | |
140 | \r | |
141 | ///\r | |
142 | /// Total number of labels describing this namespace.\r | |
143 | ///\r | |
144 | UINT16 NLabel;\r | |
145 | \r | |
146 | ///\r | |
147 | /// Position of this label in list of labels for this namespace.\r | |
148 | ///\r | |
149 | UINT16 Position;\r | |
150 | \r | |
151 | ///\r | |
152 | /// The SetCookie is utilized by SW to perform consistency checks on the Interleave Set to verify the current\r | |
153 | /// physical device configuration matches the original physical configuration when the labels were created\r | |
154 | /// for the set.The label is considered invalid if the actual label set cookie doesn't match the cookie stored here.\r | |
155 | ///\r | |
156 | UINT64 SetCookie;\r | |
157 | \r | |
158 | ///\r | |
159 | /// This is the default logical block size in bytes and may be superseded by a block size that is specified\r | |
160 | /// in the AbstractionGuid.\r | |
161 | ///\r | |
162 | UINT64 LbaSize;\r | |
163 | \r | |
164 | ///\r | |
165 | /// The DPA is the DIMM Physical address where the NVM contributing to this namespace begins on this NVDIMM.\r | |
166 | ///\r | |
167 | UINT64 Dpa;\r | |
168 | \r | |
169 | ///\r | |
170 | /// The extent of the DPA contributed by this label.\r | |
171 | ///\r | |
172 | UINT64 RawSize;\r | |
173 | \r | |
174 | ///\r | |
175 | /// Current slot in the Label Storage Area where this label is stored.\r | |
176 | ///\r | |
177 | UINT32 Slot;\r | |
178 | \r | |
179 | ///\r | |
180 | /// Alignment hint used to advertise the preferred alignment of the data from within the namespace defined by this label.\r | |
181 | ///\r | |
182 | UINT8 Alignment;\r | |
183 | \r | |
184 | ///\r | |
185 | /// Shall be 0.\r | |
186 | ///\r | |
187 | UINT8 Reserved[3];\r | |
188 | \r | |
189 | ///\r | |
190 | /// Range Type GUID that describes the access mechanism for the specified DPA range.\r | |
191 | ///\r | |
192 | EFI_GUID TypeGuid;\r | |
193 | \r | |
194 | ///\r | |
195 | /// Identifies the address abstraction mechanism for this namespace. A value of 0 indicates no mechanism used.\r | |
196 | ///\r | |
197 | EFI_GUID AddressAbstractionGuid;\r | |
198 | \r | |
199 | ///\r | |
200 | /// Shall be 0.\r | |
201 | ///\r | |
202 | UINT8 Reserved1[88];\r | |
203 | \r | |
204 | ///\r | |
205 | /// 64-bit Fletcher64 checksum of all fields in this Label.\r | |
206 | /// This field is considered zero when the checksum is computed.\r | |
207 | ///\r | |
208 | UINT64 Checksum;\r | |
209 | } EFI_NVDIMM_LABEL;\r | |
210 | \r | |
211 | typedef struct {\r | |
212 | ///\r | |
213 | /// The Region Offset field from the ACPI NFIT NVDIMM Region Mapping Structure for a given entry.\r | |
214 | ///\r | |
215 | UINT64 RegionOffset;\r | |
216 | \r | |
217 | ///\r | |
218 | /// The serial number of the NVDIMM, assigned by the module vendor.\r | |
219 | ///\r | |
220 | UINT32 SerialNumber;\r | |
221 | \r | |
222 | ///\r | |
223 | /// The identifier indicating the vendor of the NVDIMM.\r | |
224 | ///\r | |
225 | UINT16 VendorId;\r | |
226 | \r | |
227 | ///\r | |
228 | /// The manufacturing date of the NVDIMM, assigned by the module vendor.\r | |
229 | ///\r | |
230 | UINT16 ManufacturingDate;\r | |
231 | \r | |
232 | ///\r | |
233 | /// The manufacturing location from for the NVDIMM, assigned by the module vendor.\r | |
234 | ///\r | |
235 | UINT8 ManufacturingLocation;\r | |
236 | \r | |
237 | ///\r | |
238 | /// Shall be 0.\r | |
239 | ///\r | |
240 | UINT8 Reserved[31];\r | |
241 | } EFI_NVDIMM_LABEL_SET_COOKIE_MAP;\r | |
242 | \r | |
243 | typedef struct {\r | |
244 | ///\r | |
245 | /// Array size is 1 if EFI_NVDIMM_LABEL_FLAGS_LOCAL is set indicating a Local Namespaces.\r | |
246 | ///\r | |
247 | EFI_NVDIMM_LABEL_SET_COOKIE_MAP Mapping[0];\r | |
248 | } EFI_NVDIMM_LABEL_SET_COOKIE_INFO;\r | |
249 | \r | |
250 | /**\r | |
251 | Retrieves the Label Storage Area size and the maximum transfer size for the LabelStorageRead and\r | |
252 | LabelStorageWrite methods.\r | |
253 | \r | |
254 | @param This A pointer to the EFI_NVDIMM_LABEL_PROTOCOL instance.\r | |
255 | @param SizeOfLabelStorageArea The size of the Label Storage Area for the NVDIMM in bytes.\r | |
256 | @param MaxTransferLength The maximum number of bytes that can be transferred in a single call to\r | |
257 | LabelStorageRead or LabelStorageWrite.\r | |
258 | \r | |
259 | @retval EFI_SUCCESS The size of theLabel Storage Area and maximum transfer size returned are valid.\r | |
260 | @retval EFI_ACCESS_DENIED The Label Storage Area for the NVDIMM device is not currently accessible.\r | |
261 | @retval EFI_DEVICE_ERROR A physical device error occurred and the data transfer failed to complete.\r | |
262 | **/\r | |
263 | typedef\r | |
264 | EFI_STATUS\r | |
265 | (EFIAPI *EFI_NVDIMM_LABEL_STORAGE_INFORMATION) (\r | |
266 | IN EFI_NVDIMM_LABEL_PROTOCOL *This,\r | |
267 | OUT UINT32 *SizeOfLabelStorageArea,\r | |
268 | OUT UINT32 *MaxTransferLength\r | |
269 | );\r | |
270 | \r | |
271 | /**\r | |
272 | Retrieves the label data for the requested offset and length from within the Label Storage Area for\r | |
273 | the NVDIMM.\r | |
274 | \r | |
275 | @param This A pointer to the EFI_NVDIMM_LABEL_PROTOCOL instance.\r | |
276 | @param Offset The byte offset within the Label Storage Area to read from.\r | |
277 | @param TransferLength Number of bytes to read from the Label Storage Area beginning at the byte\r | |
278 | Offset specified. A TransferLength of 0 reads no data.\r | |
279 | @param LabelData The return label data read at the requested offset and length from within\r | |
280 | the Label Storage Area.\r | |
281 | \r | |
282 | @retval EFI_SUCCESS The label data from the Label Storage Area for the NVDIMM was read successfully\r | |
283 | at the specified Offset and TransferLength and LabelData contains valid data.\r | |
284 | @retval EFI_INVALID_PARAMETER Any of the following are true:\r | |
285 | - Offset > SizeOfLabelStorageArea reported in the LabelStorageInformation return data.\r | |
286 | - Offset + TransferLength is > SizeOfLabelStorageArea reported in the\r | |
287 | LabelStorageInformation return data.\r | |
288 | - TransferLength is > MaxTransferLength reported in the LabelStorageInformation return\r | |
289 | data.\r | |
290 | @retval EFI_ACCESS_DENIED The Label Storage Area for the NVDIMM device is not currently accessible and labels\r | |
291 | cannot be read at this time.\r | |
292 | @retval EFI_DEVICE_ERROR A physical device error occurred and the data transfer failed to complete.\r | |
293 | **/\r | |
294 | typedef\r | |
295 | EFI_STATUS\r | |
296 | (EFIAPI *EFI_NVDIMM_LABEL_STORAGE_READ) (\r | |
297 | IN CONST EFI_NVDIMM_LABEL_PROTOCOL *This,\r | |
298 | IN UINT32 Offset,\r | |
299 | IN UINT32 TransferLength,\r | |
300 | OUT UINT8 *LabelData\r | |
301 | );\r | |
302 | \r | |
303 | /**\r | |
304 | Writes the label data for the requested offset and length in to the Label Storage Area for the NVDIMM.\r | |
305 | \r | |
306 | @param This A pointer to the EFI_NVDIMM_LABEL_PROTOCOL instance.\r | |
307 | @param Offset The byte offset within the Label Storage Area to write to.\r | |
308 | @param TransferLength Number of bytes to write to the Label Storage Area beginning at the byte\r | |
309 | Offset specified. A TransferLength of 0 writes no data.\r | |
310 | @param LabelData The return label data write at the requested offset and length from within\r | |
311 | the Label Storage Area.\r | |
312 | \r | |
313 | @retval EFI_SUCCESS The label data from the Label Storage Area for the NVDIMM written read successfully\r | |
314 | at the specified Offset and TransferLength.\r | |
315 | @retval EFI_INVALID_PARAMETER Any of the following are true:\r | |
316 | - Offset > SizeOfLabelStorageArea reported in the LabelStorageInformation return data.\r | |
317 | - Offset + TransferLength is > SizeOfLabelStorageArea reported in the\r | |
318 | LabelStorageInformation return data.\r | |
319 | - TransferLength is > MaxTransferLength reported in the LabelStorageInformation return\r | |
320 | data.\r | |
321 | @retval EFI_ACCESS_DENIED The Label Storage Area for the NVDIMM device is not currently accessible and labels\r | |
322 | cannot be written at this time.\r | |
323 | @retval EFI_DEVICE_ERROR A physical device error occurred and the data transfer failed to complete.\r | |
324 | **/\r | |
325 | typedef\r | |
326 | EFI_STATUS\r | |
327 | (EFIAPI *EFI_NVDIMM_LABEL_STORAGE_WRITE) (\r | |
328 | IN CONST EFI_NVDIMM_LABEL_PROTOCOL *This,\r | |
329 | IN UINT32 Offset,\r | |
330 | IN UINT32 TransferLength,\r | |
331 | IN UINT8 *LabelData\r | |
332 | );\r | |
333 | \r | |
334 | ///\r | |
335 | /// Provides services that allow management of labels contained in a Label Storage Area.\r | |
336 | ///\r | |
337 | struct _EFI_NVDIMM_LABEL_PROTOCOL {\r | |
338 | EFI_NVDIMM_LABEL_STORAGE_INFORMATION LabelStorageInformation;\r | |
339 | EFI_NVDIMM_LABEL_STORAGE_READ LabelStorageRead;\r | |
340 | EFI_NVDIMM_LABEL_STORAGE_WRITE LabelStorageWrite;\r | |
341 | };\r | |
342 | \r | |
343 | extern EFI_GUID gEfiNvdimmLabelProtocolGuid;\r | |
344 | \r | |
345 | #endif\r |