1 /** @file 2 ACPI Sdt Protocol Driver 3 4 Copyright (c) 2010 - 2015, Intel Corporation. All rights reserved. <BR> 5 This program and the accompanying materials 6 are licensed and made available under the terms and conditions of the BSD License 7 which accompanies this distribution. The full text of the license may be found at 8 http://opensource.org/licenses/bsd-license.php 9 10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 12 13 **/ 14 15 #ifndef _ACPI_SDT_H_ 16 #define _ACPI_SDT_H_ 17 18 // 19 // Privacy data structure 20 // 21 22 // 23 // ACPI Notify Linked List Signature. 24 // 25 #define EFI_ACPI_NOTIFY_LIST_SIGNATURE SIGNATURE_32 ('E', 'A', 'N', 'L') 26 27 // 28 // ACPI Notify List Entry definition. 29 // 30 // Signature must be set to EFI_ACPI_NOTIFY_LIST_SIGNATURE 31 // Link is the linked list data. 32 // Notification is the callback function. 33 // 34 typedef struct { 35 UINT32 Signature; 36 LIST_ENTRY Link; 37 EFI_ACPI_NOTIFICATION_FN Notification; 38 } EFI_ACPI_NOTIFY_LIST; 39 40 // 41 // Containment record for ACPI Notify linked list. 42 // 43 #define EFI_ACPI_NOTIFY_LIST_FROM_LINK(_link) CR (_link, EFI_ACPI_NOTIFY_LIST, Link, EFI_ACPI_NOTIFY_LIST_SIGNATURE) 44 45 typedef struct _AML_BYTE_ENCODING AML_BYTE_ENCODING; 46 typedef struct _EFI_AML_NODE_LIST EFI_AML_NODE_LIST; 47 48 // 49 // AML Node Linked List Signature. 50 // 51 #define EFI_AML_NODE_LIST_SIGNATURE SIGNATURE_32 ('E', 'A', 'M', 'L') 52 53 // 54 // AML Node Linked List Entry definition. 55 // 56 // Signature must be set to EFI_AML_NODE_LIST_SIGNATURE 57 // Link is the linked list data. 58 // Name is the ACPI node name. 59 // This is listed for PATH finding. 60 // Buffer is the ACPI node buffer pointer, the first/second bytes are opcode. 61 // This buffer should not be freed. 62 // Size is the total size of this ACPI node buffer. 63 // Children is the children linked list of this node. 64 // 65 #define AML_NAME_SEG_SIZE 4 66 67 struct _EFI_AML_NODE_LIST { 68 UINT32 Signature; 69 UINT8 Name[AML_NAME_SEG_SIZE]; 70 UINT8 *Buffer; 71 UINTN Size; 72 LIST_ENTRY Link; 73 LIST_ENTRY Children; 74 EFI_AML_NODE_LIST *Parent; 75 AML_BYTE_ENCODING *AmlByteEncoding; 76 }; 77 78 // 79 // Containment record for AML Node linked list. 80 // 81 #define EFI_AML_NODE_LIST_FROM_LINK(_link) CR (_link, EFI_AML_NODE_LIST, Link, EFI_AML_NODE_LIST_SIGNATURE) 82 83 // 84 // AML Handle Signature. 85 // 86 #define EFI_AML_HANDLE_SIGNATURE SIGNATURE_32 ('E', 'A', 'H', 'S') 87 #define EFI_AML_ROOT_HANDLE_SIGNATURE SIGNATURE_32 ('E', 'A', 'R', 'H') 88 89 // 90 // AML Handle Entry definition. 91 // 92 // Signature must be set to EFI_AML_HANDLE_SIGNATURE or EFI_AML_ROOT_HANDLE_SIGNATURE 93 // Buffer is the ACPI node buffer pointer, the first/second bytes are opcode. 94 // This buffer should not be freed. 95 // Size is the total size of this ACPI node buffer. 96 // 97 typedef struct { 98 UINT32 Signature; 99 UINT8 *Buffer; 100 UINTN Size; 101 AML_BYTE_ENCODING *AmlByteEncoding; 102 BOOLEAN Modified; 103 } EFI_AML_HANDLE; 104 105 typedef UINT32 AML_OP_PARSE_INDEX; 106 107 #define AML_OP_PARSE_INDEX_GET_OPCODE 0 108 #define AML_OP_PARSE_INDEX_GET_TERM1 1 109 #define AML_OP_PARSE_INDEX_GET_TERM2 2 110 #define AML_OP_PARSE_INDEX_GET_TERM3 3 111 #define AML_OP_PARSE_INDEX_GET_TERM4 4 112 #define AML_OP_PARSE_INDEX_GET_TERM5 5 113 #define AML_OP_PARSE_INDEX_GET_TERM6 6 114 #define AML_OP_PARSE_INDEX_GET_SIZE (AML_OP_PARSE_INDEX)-1 115 116 typedef UINT32 AML_OP_PARSE_FORMAT; 117 #define AML_NONE 0 118 #define AML_OPCODE 1 119 #define AML_UINT8 2 120 #define AML_UINT16 3 121 #define AML_UINT32 4 122 #define AML_UINT64 5 123 #define AML_NAME 6 124 #define AML_STRING 7 125 #define AML_OBJECT 8 126 127 typedef UINT32 AML_OP_ATTRIBUTE; 128 #define AML_HAS_PKG_LENGTH 0x1 // It is ACPI attribute - if OpCode has PkgLength 129 #define AML_IS_NAME_CHAR 0x2 // It is ACPI attribute - if this is NameChar 130 #define AML_HAS_CHILD_OBJ 0x4 // it is ACPI attribute - if OpCode has Child Object. 131 #define AML_IN_NAMESPACE 0x10000 // It is UEFI SDT attribute - if OpCode will be in NameSpace 132 // NOTE; Not all OBJECT will be in NameSpace 133 // For example, BankField | CreateBitField | CreateByteField | CreateDWordField | 134 // CreateField | CreateQWordField | CreateWordField | Field | IndexField. 135 136 struct _AML_BYTE_ENCODING { 137 UINT8 OpCode; 138 UINT8 SubOpCode; 139 AML_OP_PARSE_INDEX MaxIndex; 140 AML_OP_PARSE_FORMAT Format[6]; 141 AML_OP_ATTRIBUTE Attribute; 142 }; 143 144 // 145 // AcpiSdt protocol declaration 146 // 147 148 /** 149 Returns a requested ACPI table. 150 151 The GetAcpiTable() function returns a pointer to a buffer containing the ACPI table associated 152 with the Index that was input. The following structures are not considered elements in the list of 153 ACPI tables: 154 - Root System Description Pointer (RSD_PTR) 155 - Root System Description Table (RSDT) 156 - Extended System Description Table (XSDT) 157 Version is updated with a bit map containing all the versions of ACPI of which the table is a 158 member. For tables installed via the EFI_ACPI_TABLE_PROTOCOL.InstallAcpiTable() interface, 159 the function returns the value of EFI_ACPI_STD_PROTOCOL.AcpiVersion. 160 161 @param[in] Index The zero-based index of the table to retrieve. 162 @param[out] Table Pointer for returning the table buffer. 163 @param[out] Version On return, updated with the ACPI versions to which this table belongs. Type 164 EFI_ACPI_TABLE_VERSION is defined in "Related Definitions" in the 165 EFI_ACPI_SDT_PROTOCOL. 166 @param[out] TableKey On return, points to the table key for the specified ACPI system definition table. 167 This is identical to the table key used in the EFI_ACPI_TABLE_PROTOCOL. 168 The TableKey can be passed to EFI_ACPI_TABLE_PROTOCOL.UninstallAcpiTable() 169 to uninstall the table. 170 171 @retval EFI_SUCCESS The function completed successfully. 172 @retval EFI_NOT_FOUND The requested index is too large and a table was not found. 173 **/ 174 EFI_STATUS 175 EFIAPI 176 GetAcpiTable2 ( 177 IN UINTN Index, 178 OUT EFI_ACPI_SDT_HEADER **Table, 179 OUT EFI_ACPI_TABLE_VERSION *Version, 180 OUT UINTN *TableKey 181 ); 182 183 /** 184 Register or unregister a callback when an ACPI table is installed. 185 186 This function registers or unregisters a function which will be called whenever a new ACPI table is 187 installed. 188 189 @param[in] Register If TRUE, then the specified function will be registered. If FALSE, then the specified 190 function will be unregistered. 191 @param[in] Notification Points to the callback function to be registered or unregistered. 192 193 @retval EFI_SUCCESS Callback successfully registered or unregistered. 194 @retval EFI_INVALID_PARAMETER Notification is NULL 195 @retval EFI_INVALID_PARAMETER Register is FALSE and Notification does not match a known registration function. 196 **/ 197 EFI_STATUS 198 EFIAPI 199 RegisterNotify ( 200 IN BOOLEAN Register, 201 IN EFI_ACPI_NOTIFICATION_FN Notification 202 ); 203 204 /** 205 Create a handle for the first ACPI opcode in an ACPI system description table. 206 207 @param[in] TableKey The table key for the ACPI table, as returned by GetTable(). 208 @param[out] Handle On return, points to the newly created ACPI handle. 209 210 @retval EFI_SUCCESS Handle created successfully. 211 @retval EFI_NOT_FOUND TableKey does not refer to a valid ACPI table. 212 **/ 213 EFI_STATUS 214 EFIAPI 215 OpenSdt ( 216 IN UINTN TableKey, 217 OUT EFI_ACPI_HANDLE *Handle 218 ); 219 220 /** 221 Create a handle from an ACPI opcode 222 223 @param[in] Buffer Points to the ACPI opcode. 224 @param[out] Handle Upon return, holds the handle. 225 226 @retval EFI_SUCCESS Success 227 @retval EFI_INVALID_PARAMETER Buffer is NULL or Handle is NULL or Buffer points to an 228 invalid opcode. 229 230 **/ 231 EFI_STATUS 232 EFIAPI 233 Open ( 234 IN VOID *Buffer, 235 OUT EFI_ACPI_HANDLE *Handle 236 ); 237 238 /** 239 Close an ACPI handle. 240 241 @param[in] Handle Returns the handle. 242 243 @retval EFI_SUCCESS Success 244 @retval EFI_INVALID_PARAMETER Handle is NULL or does not refer to a valid ACPI object. 245 **/ 246 EFI_STATUS 247 EFIAPI 248 Close ( 249 IN EFI_ACPI_HANDLE Handle 250 ); 251 252 /** 253 Retrieve information about an ACPI object. 254 255 @param[in] Handle ACPI object handle. 256 @param[in] Index Index of the data to retrieve from the object. In general, indexes read from left-to-right 257 in the ACPI encoding, with index 0 always being the ACPI opcode. 258 @param[out] DataType Points to the returned data type or EFI_ACPI_DATA_TYPE_NONE if no data exists 259 for the specified index. 260 @param[out] Data Upon return, points to the pointer to the data. 261 @param[out] DataSize Upon return, points to the size of Data. 262 263 @retval EFI_SUCCESS Success. 264 @retval EFI_INVALID_PARAMETER Handle is NULL or does not refer to a valid ACPI object. 265 **/ 266 EFI_STATUS 267 EFIAPI 268 GetOption ( 269 IN EFI_ACPI_HANDLE Handle, 270 IN UINTN Index, 271 OUT EFI_ACPI_DATA_TYPE *DataType, 272 OUT CONST VOID **Data, 273 OUT UINTN *DataSize 274 ); 275 276 /** 277 Change information about an ACPI object. 278 279 @param[in] Handle ACPI object handle. 280 @param[in] Index Index of the data to retrieve from the object. In general, indexes read from left-to-right 281 in the ACPI encoding, with index 0 always being the ACPI opcode. 282 @param[in] Data Points to the data. 283 @param[in] DataSize The size of the Data. 284 285 @retval EFI_SUCCESS Success 286 @retval EFI_INVALID_PARAMETER Handle is NULL or does not refer to a valid ACPI object. 287 @retval EFI_BAD_BUFFER_SIZE Data cannot be accommodated in the space occupied by 288 the option. 289 290 **/ 291 EFI_STATUS 292 EFIAPI 293 SetOption ( 294 IN EFI_ACPI_HANDLE Handle, 295 IN UINTN Index, 296 IN CONST VOID *Data, 297 IN UINTN DataSize 298 ); 299 300 /** 301 Return the child ACPI objects. 302 303 @param[in] ParentHandle Parent handle. 304 @param[in, out] Handle On entry, points to the previously returned handle or NULL to start with the first 305 handle. On return, points to the next returned ACPI handle or NULL if there are no 306 child objects. 307 308 @retval EFI_SUCCESS Success 309 @retval EFI_INVALID_PARAMETER ParentHandle is NULL or does not refer to a valid ACPI object. 310 **/ 311 EFI_STATUS 312 EFIAPI 313 GetChild ( 314 IN EFI_ACPI_HANDLE ParentHandle, 315 IN OUT EFI_ACPI_HANDLE *Handle 316 ); 317 318 /** 319 Returns the handle of the ACPI object representing the specified ACPI path 320 321 @param[in] HandleIn Points to the handle of the object representing the starting point for the path search. 322 @param[in] AcpiPath Points to the ACPI path, which conforms to the ACPI encoded path format. 323 @param[out] HandleOut On return, points to the ACPI object which represents AcpiPath, relative to 324 HandleIn. 325 326 @retval EFI_SUCCESS Success 327 @retval EFI_INVALID_PARAMETER HandleIn is NULL or does not refer to a valid ACPI object. 328 **/ 329 EFI_STATUS 330 EFIAPI 331 FindPath ( 332 IN EFI_ACPI_HANDLE HandleIn, 333 IN VOID *AcpiPath, 334 OUT EFI_ACPI_HANDLE *HandleOut 335 ); 336 337 // 338 // ACPI SDT function 339 // 340 341 /** 342 Create a handle from an ACPI opcode 343 344 @param[in] Buffer Points to the ACPI opcode. 345 @param[in] BufferSize Max buffer size. 346 @param[out] Handle Upon return, holds the handle. 347 348 @retval EFI_SUCCESS Success 349 @retval EFI_INVALID_PARAMETER Buffer is NULL or Handle is NULL or Buffer points to an 350 invalid opcode. 351 352 **/ 353 EFI_STATUS 354 SdtOpenEx ( 355 IN VOID *Buffer, 356 IN UINTN BufferSize, 357 OUT EFI_ACPI_HANDLE *Handle 358 ); 359 360 // 361 // AML support function 362 // 363 364 /** 365 Get AML NameString size. 366 367 @param[in] Buffer AML NameString. 368 @param[out] BufferSize AML NameString size 369 370 @retval EFI_SUCCESS Success. 371 @retval EFI_INVALID_PARAMETER Buffer does not refer to a valid AML NameString. 372 **/ 373 EFI_STATUS 374 AmlGetNameStringSize ( 375 IN UINT8 *Buffer, 376 OUT UINTN *BufferSize 377 ); 378 379 /** 380 This function retuns package length from the buffer. 381 382 @param[in] Buffer AML buffer 383 @param[out] PkgLength The total length of package. 384 385 @return The byte data count to present the package length. 386 **/ 387 UINTN 388 AmlGetPkgLength ( 389 IN UINT8 *Buffer, 390 OUT UINTN *PkgLength 391 ); 392 393 /** 394 This function returns AcpiDataType according to AmlType. 395 396 @param[in] AmlType AML Type. 397 398 @return AcpiDataType 399 **/ 400 EFI_ACPI_DATA_TYPE 401 AmlTypeToAcpiType ( 402 IN AML_OP_PARSE_FORMAT AmlType 403 ); 404 405 /** 406 This function returns AmlByteEncoding according to OpCode Byte. 407 408 @param[in] OpByteBuffer OpCode byte buffer. 409 410 @return AmlByteEncoding 411 **/ 412 AML_BYTE_ENCODING * 413 AmlSearchByOpByte ( 414 IN UINT8 *OpByteBuffer 415 ); 416 417 /** 418 Return object size. 419 420 @param[in] AmlByteEncoding AML Byte Encoding. 421 @param[in] Buffer AML object buffer. 422 @param[in] MaxBufferSize AML object buffer MAX size. The parser can not parse any data exceed this region. 423 424 @return Size of the object. 425 **/ 426 UINTN 427 AmlGetObjectSize ( 428 IN AML_BYTE_ENCODING *AmlByteEncoding, 429 IN UINT8 *Buffer, 430 IN UINTN MaxBufferSize 431 ); 432 433 /** 434 Return object name. 435 436 @param[in] AmlHandle AML handle. 437 438 @return Name of the object. 439 **/ 440 CHAR8 * 441 AmlGetObjectName ( 442 IN EFI_AML_HANDLE *AmlHandle 443 ); 444 445 /** 446 Retrieve information according to AmlHandle 447 448 @param[in] AmlHandle AML handle. 449 @param[in] Index Index of the data to retrieve from the object. In general, indexes read from left-to-right 450 in the ACPI encoding, with index 0 always being the ACPI opcode. 451 @param[out] DataType Points to the returned data type or EFI_ACPI_DATA_TYPE_NONE if no data exists 452 for the specified index. 453 @param[out] Data Upon return, points to the pointer to the data. 454 @param[out] DataSize Upon return, points to the size of Data. 455 456 @retval EFI_SUCCESS Success. 457 @retval EFI_INVALID_PARAMETER AmlHandle does not refer to a valid ACPI object. 458 **/ 459 EFI_STATUS 460 AmlParseOptionHandleCommon ( 461 IN EFI_AML_HANDLE *AmlHandle, 462 IN AML_OP_PARSE_INDEX Index, 463 OUT EFI_ACPI_DATA_TYPE *DataType, 464 OUT VOID **Data, 465 OUT UINTN *DataSize 466 ); 467 468 /** 469 Return offset of last option. 470 471 @param[in] AmlHandle AML Handle. 472 @param[out] Buffer Upon return, points to the offset after last option. 473 474 @retval EFI_SUCCESS Success. 475 @retval EFI_INVALID_PARAMETER AmlHandle does not refer to a valid ACPI object. 476 **/ 477 EFI_STATUS 478 AmlGetOffsetAfterLastOption ( 479 IN EFI_AML_HANDLE *AmlHandle, 480 OUT UINT8 **Buffer 481 ); 482 483 /** 484 Return the child ACPI objects from Root Handle. 485 486 @param[in] AmlParentHandle Parent handle. It is Root Handle. 487 @param[in] AmlHandle The previously returned handle or NULL to start with the first handle. 488 @param[out] Buffer On return, points to the next returned ACPI handle or NULL if there are no 489 child objects. 490 491 @retval EFI_SUCCESS Success 492 @retval EFI_INVALID_PARAMETER ParentHandle is NULL or does not refer to a valid ACPI object. 493 **/ 494 EFI_STATUS 495 AmlGetChildFromRoot ( 496 IN EFI_AML_HANDLE *AmlParentHandle, 497 IN EFI_AML_HANDLE *AmlHandle, 498 OUT VOID **Buffer 499 ); 500 501 /** 502 Return the child ACPI objects from Non-Root Handle. 503 504 @param[in] AmlParentHandle Parent handle. It is Non-Root Handle. 505 @param[in] AmlHandle The previously returned handle or NULL to start with the first handle. 506 @param[out] Buffer On return, points to the next returned ACPI handle or NULL if there are no 507 child objects. 508 509 @retval EFI_SUCCESS Success 510 @retval EFI_INVALID_PARAMETER ParentHandle is NULL or does not refer to a valid ACPI object. 511 **/ 512 EFI_STATUS 513 AmlGetChildFromNonRoot ( 514 IN EFI_AML_HANDLE *AmlParentHandle, 515 IN EFI_AML_HANDLE *AmlHandle, 516 OUT VOID **Buffer 517 ); 518 519 /** 520 Return AML name according to ASL name. 521 The caller need free the AmlName returned. 522 523 @param[in] AslPath ASL name. 524 525 @return AmlName 526 **/ 527 UINT8 * 528 AmlNameFromAslName ( 529 IN UINT8 *AslPath 530 ); 531 532 /** 533 Returns the handle of the ACPI object representing the specified ACPI AML path 534 535 @param[in] AmlHandle Points to the handle of the object representing the starting point for the path search. 536 @param[in] AmlPath Points to the ACPI AML path. 537 @param[out] Buffer On return, points to the ACPI object which represents AcpiPath, relative to 538 HandleIn. 539 @param[in] FromRoot TRUE means to find AML path from \ (Root) Node. 540 FALSE means to find AML path from this Node (The HandleIn). 541 542 @retval EFI_SUCCESS Success 543 @retval EFI_INVALID_PARAMETER HandleIn does not refer to a valid ACPI object. 544 **/ 545 EFI_STATUS 546 AmlFindPath ( 547 IN EFI_AML_HANDLE *AmlHandle, 548 IN UINT8 *AmlPath, 549 OUT VOID **Buffer, 550 IN BOOLEAN FromRoot 551 ); 552 553 /** 554 Print AML NameString. 555 556 @param[in] Buffer AML NameString. 557 **/ 558 VOID 559 AmlPrintNameString ( 560 IN UINT8 *Buffer 561 ); 562 563 /** 564 Print AML NameSeg. 565 566 @param[in] Buffer AML NameSeg. 567 **/ 568 VOID 569 AmlPrintNameSeg ( 570 IN UINT8 *Buffer 571 ); 572 573 /** 574 Check if it is AML Root name 575 576 @param[in] Buffer AML path. 577 578 @retval TRUE AML path is root. 579 @retval FALSE AML path is not root. 580 **/ 581 BOOLEAN 582 AmlIsRootPath ( 583 IN UINT8 *Buffer 584 ); 585 586 #endif 587