reactos/drivers/bus/acpi/acpica/executer/exutils.c

   1
   2 /******************************************************************************
   3  *
   4  * Module Name: exutils - interpreter/scanner utilities
   5  *
   6  *****************************************************************************/
   7
   8 /******************************************************************************
   9  *
  10  * 1. Copyright Notice
  11  *
  12  * Some or all of this work - Copyright (c) 1999 - 2009, Intel Corp.
  13  * All rights reserved.
  14  *
  15  * 2. License
  16  *
  17  * 2.1. This is your license from Intel Corp. under its intellectual property
  18  * rights.  You may have additional license terms from the party that provided
  19  * you this software, covering your right to use that party's intellectual
  20  * property rights.
  21  *
  22  * 2.2. Intel grants, free of charge, to any person ("Licensee") obtaining a
  23  * copy of the source code appearing in this file ("Covered Code") an
  24  * irrevocable, perpetual, worldwide license under Intel's copyrights in the
  25  * base code distributed originally by Intel ("Original Intel Code") to copy,
  26  * make derivatives, distribute, use and display any portion of the Covered
  27  * Code in any form, with the right to sublicense such rights; and
  28  *
  29  * 2.3. Intel grants Licensee a non-exclusive and non-transferable patent
  30  * license (with the right to sublicense), under only those claims of Intel
  31  * patents that are infringed by the Original Intel Code, to make, use, sell,
  32  * offer to sell, and import the Covered Code and derivative works thereof
  33  * solely to the minimum extent necessary to exercise the above copyright
  34  * license, and in no event shall the patent license extend to any additions
  35  * to or modifications of the Original Intel Code.  No other license or right
  36  * is granted directly or by implication, estoppel or otherwise;
  37  *
  38  * The above copyright and patent license is granted only if the following
  39  * conditions are met:
  40  *
  41  * 3. Conditions
  42  *
  43  * 3.1. Redistribution of Source with Rights to Further Distribute Source.
  44  * Redistribution of source code of any substantial portion of the Covered
  45  * Code or modification with rights to further distribute source must include
  46  * the above Copyright Notice, the above License, this list of Conditions,
  47  * and the following Disclaimer and Export Compliance provision.  In addition,
  48  * Licensee must cause all Covered Code to which Licensee contributes to
  49  * contain a file documenting the changes Licensee made to create that Covered
  50  * Code and the date of any change.  Licensee must include in that file the
  51  * documentation of any changes made by any predecessor Licensee.  Licensee
  52  * must include a prominent statement that the modification is derived,
  53  * directly or indirectly, from Original Intel Code.
  54  *
  55  * 3.2. Redistribution of Source with no Rights to Further Distribute Source.
  56  * Redistribution of source code of any substantial portion of the Covered
  57  * Code or modification without rights to further distribute source must
  58  * include the following Disclaimer and Export Compliance provision in the
  59  * documentation and/or other materials provided with distribution.  In
  60  * addition, Licensee may not authorize further sublicense of source of any
  61  * portion of the Covered Code, and must include terms to the effect that the
  62  * license from Licensee to its licensee is limited to the intellectual
  63  * property embodied in the software Licensee provides to its licensee, and
  64  * not to intellectual property embodied in modifications its licensee may
  65  * make.
  66  *
  67  * 3.3. Redistribution of Executable. Redistribution in executable form of any
  68  * substantial portion of the Covered Code or modification must reproduce the
  69  * above Copyright Notice, and the following Disclaimer and Export Compliance
  70  * provision in the documentation and/or other materials provided with the
  71  * distribution.
  72  *
  73  * 3.4. Intel retains all right, title, and interest in and to the Original
  74  * Intel Code.
  75  *
  76  * 3.5. Neither the name Intel nor any other trademark owned or controlled by
  77  * Intel shall be used in advertising or otherwise to promote the sale, use or
  78  * other dealings in products derived from or relating to the Covered Code
  79  * without prior written authorization from Intel.
  80  *
  81  * 4. Disclaimer and Export Compliance
  82  *
  83  * 4.1. INTEL MAKES NO WARRANTY OF ANY KIND REGARDING ANY SOFTWARE PROVIDED
  84  * HERE.  ANY SOFTWARE ORIGINATING FROM INTEL OR DERIVED FROM INTEL SOFTWARE
  85  * IS PROVIDED "AS IS," AND INTEL WILL NOT PROVIDE ANY SUPPORT,  ASSISTANCE,
  86  * INSTALLATION, TRAINING OR OTHER SERVICES.  INTEL WILL NOT PROVIDE ANY
  87  * UPDATES, ENHANCEMENTS OR EXTENSIONS.  INTEL SPECIFICALLY DISCLAIMS ANY
  88  * IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A
  89  * PARTICULAR PURPOSE.
  90  *
  91  * 4.2. IN NO EVENT SHALL INTEL HAVE ANY LIABILITY TO LICENSEE, ITS LICENSEES
  92  * OR ANY OTHER THIRD PARTY, FOR ANY LOST PROFITS, LOST DATA, LOSS OF USE OR
  93  * COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR FOR ANY INDIRECT,
  94  * SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THIS AGREEMENT, UNDER ANY
  95  * CAUSE OF ACTION OR THEORY OF LIABILITY, AND IRRESPECTIVE OF WHETHER INTEL
  96  * HAS ADVANCE NOTICE OF THE POSSIBILITY OF SUCH DAMAGES.  THESE LIMITATIONS
  97  * SHALL APPLY NOTWITHSTANDING THE FAILURE OF THE ESSENTIAL PURPOSE OF ANY
  98  * LIMITED REMEDY.
  99  *
 100  * 4.3. Licensee shall not export, either directly or indirectly, any of this
 101  * software or system incorporating such software without first obtaining any
 102  * required license or other approval from the U. S. Department of Commerce or
 103  * any other agency or department of the United States Government.  In the
 104  * event Licensee exports any such software from the United States or
 105  * re-exports any such software from a foreign destination, Licensee shall
 106  * ensure that the distribution and export/re-export of the software is in
 107  * compliance with all laws, regulations, orders, or other restrictions of the
 108  * U.S. Export Administration Regulations. Licensee agrees that neither it nor
 109  * any of its subsidiaries will export/re-export any technical data, process,
 110  * software, or service, directly or indirectly, to any country for which the
 111  * United States government or any agency thereof requires an export license,
 112  * other governmental approval, or letter of assurance, without first obtaining
 113  * such license, approval or letter.
 114  *
 115  *****************************************************************************/
 116
 117 #define __EXUTILS_C__
 118
 119 /*
 120  * DEFINE_AML_GLOBALS is tested in amlcode.h
 121  * to determine whether certain global names should be "defined" or only
 122  * "declared" in the current compilation.  This enhances maintainability
 123  * by enabling a single header file to embody all knowledge of the names
 124  * in question.
 125  *
 126  * Exactly one module of any executable should #define DEFINE_GLOBALS
 127  * before #including the header files which use this convention.  The
 128  * names in question will be defined and initialized in that module,
 129  * and declared as extern in all other modules which #include those
 130  * header files.
 131  */
 132
 133 #define DEFINE_AML_GLOBALS
 134
 135 #include "acpi.h"
 136 #include "accommon.h"
 137 #include "acinterp.h"
 138 #include "amlcode.h"
 139
 140 #define _COMPONENT          ACPI_EXECUTER
 141         ACPI_MODULE_NAME    ("exutils")
 142
 143 /* Local prototypes */
 144
 145 static UINT32
 146 AcpiExDigitsNeeded (
 147     ACPI_INTEGER            Value,
 148     UINT32                  Base);
 149
 150
 151 #ifndef ACPI_NO_METHOD_EXECUTION
 152 /*******************************************************************************
 153  *
 154  * FUNCTION:    AcpiExEnterInterpreter
 155  *
 156  * PARAMETERS:  None
 157  *
 158  * RETURN:      None
 159  *
 160  * DESCRIPTION: Enter the interpreter execution region. Failure to enter
 161  *              the interpreter region is a fatal system error. Used in
 162  *              conjunction with ExitInterpreter.
 163  *
 164  ******************************************************************************/
 165
 166 void
 167 AcpiExEnterInterpreter (
 168     void)
 169 {
 170     ACPI_STATUS             Status;
 171
 172
 173     ACPI_FUNCTION_TRACE (ExEnterInterpreter);
 174
 175
 176     Status = AcpiUtAcquireMutex (ACPI_MTX_INTERPRETER);
 177     if (ACPI_FAILURE (Status))
 178     {
 179         ACPI_ERROR ((AE_INFO, "Could not acquire AML Interpreter mutex"));
 180     }
 181
 182     return_VOID;
 183 }
 184
 185
 186 /*******************************************************************************
 187  *
 188  * FUNCTION:    AcpiExReacquireInterpreter
 189  *
 190  * PARAMETERS:  None
 191  *
 192  * RETURN:      None
 193  *
 194  * DESCRIPTION: Reacquire the interpreter execution region from within the
 195  *              interpreter code. Failure to enter the interpreter region is a
 196  *              fatal system error. Used in  conjuction with
 197  *              RelinquishInterpreter
 198  *
 199  ******************************************************************************/
 200
 201 void
 202 AcpiExReacquireInterpreter (
 203     void)
 204 {
 205     ACPI_FUNCTION_TRACE (ExReacquireInterpreter);
 206
 207
 208     /*
 209      * If the global serialized flag is set, do not release the interpreter,
 210      * since it was not actually released by AcpiExRelinquishInterpreter.
 211      * This forces the interpreter to be single threaded.
 212      */
 213     if (!AcpiGbl_AllMethodsSerialized)
 214     {
 215         AcpiExEnterInterpreter ();
 216     }
 217
 218     return_VOID;
 219 }
 220
 221
 222 /*******************************************************************************
 223  *
 224  * FUNCTION:    AcpiExExitInterpreter
 225  *
 226  * PARAMETERS:  None
 227  *
 228  * RETURN:      None
 229  *
 230  * DESCRIPTION: Exit the interpreter execution region. This is the top level
 231  *              routine used to exit the interpreter when all processing has
 232  *              been completed.
 233  *
 234  ******************************************************************************/
 235
 236 void
 237 AcpiExExitInterpreter (
 238     void)
 239 {
 240     ACPI_STATUS             Status;
 241
 242
 243     ACPI_FUNCTION_TRACE (ExExitInterpreter);
 244
 245
 246     Status = AcpiUtReleaseMutex (ACPI_MTX_INTERPRETER);
 247     if (ACPI_FAILURE (Status))
 248     {
 249         ACPI_ERROR ((AE_INFO, "Could not release AML Interpreter mutex"));
 250     }
 251
 252     return_VOID;
 253 }
 254
 255
 256 /*******************************************************************************
 257  *
 258  * FUNCTION:    AcpiExRelinquishInterpreter
 259  *
 260  * PARAMETERS:  None
 261  *
 262  * RETURN:      None
 263  *
 264  * DESCRIPTION: Exit the interpreter execution region, from within the
 265  *              interpreter - before attempting an operation that will possibly
 266  *              block the running thread.
 267  *
 268  * Cases where the interpreter is unlocked internally
 269  *      1) Method to be blocked on a Sleep() AML opcode
 270  *      2) Method to be blocked on an Acquire() AML opcode
 271  *      3) Method to be blocked on a Wait() AML opcode
 272  *      4) Method to be blocked to acquire the global lock
 273  *      5) Method to be blocked waiting to execute a serialized control method
 274  *          that is currently executing
 275  *      6) About to invoke a user-installed opregion handler
 276  *
 277  ******************************************************************************/
 278
 279 void
 280 AcpiExRelinquishInterpreter (
 281     void)
 282 {
 283     ACPI_FUNCTION_TRACE (ExRelinquishInterpreter);
 284
 285
 286     /*
 287      * If the global serialized flag is set, do not release the interpreter.
 288      * This forces the interpreter to be single threaded.
 289      */
 290     if (!AcpiGbl_AllMethodsSerialized)
 291     {
 292         AcpiExExitInterpreter ();
 293     }
 294
 295     return_VOID;
 296 }
 297
 298
 299 /*******************************************************************************
 300  *
 301  * FUNCTION:    AcpiExTruncateFor32bitTable
 302  *
 303  * PARAMETERS:  ObjDesc         - Object to be truncated
 304  *
 305  * RETURN:      none
 306  *
 307  * DESCRIPTION: Truncate an ACPI Integer to 32 bits if the execution mode is
 308  *              32-bit, as determined by the revision of the DSDT.
 309  *
 310  ******************************************************************************/
 311
 312 void
 313 AcpiExTruncateFor32bitTable (
 314     ACPI_OPERAND_OBJECT     *ObjDesc)
 315 {
 316
 317     ACPI_FUNCTION_ENTRY ();
 318
 319
 320     /*
 321      * Object must be a valid number and we must be executing
 322      * a control method. NS node could be there for AML_INT_NAMEPATH_OP.
 323      */
 324     if ((!ObjDesc) ||
 325         (ACPI_GET_DESCRIPTOR_TYPE (ObjDesc) != ACPI_DESC_TYPE_OPERAND) ||
 326         (ObjDesc->Common.Type != ACPI_TYPE_INTEGER))
 327     {
 328         return;
 329     }
 330
 331     if (AcpiGbl_IntegerByteWidth == 4)
 332     {
 333         /*
 334          * We are running a method that exists in a 32-bit ACPI table.
 335          * Truncate the value to 32 bits by zeroing out the upper 32-bit field
 336          */
 337         ObjDesc->Integer.Value &= (ACPI_INTEGER) ACPI_UINT32_MAX;
 338     }
 339 }
 340
 341
 342 /*******************************************************************************
 343  *
 344  * FUNCTION:    AcpiExAcquireGlobalLock
 345  *
 346  * PARAMETERS:  FieldFlags            - Flags with Lock rule:
 347  *                                      AlwaysLock or NeverLock
 348  *
 349  * RETURN:      None
 350  *
 351  * DESCRIPTION: Obtain the ACPI hardware Global Lock, only if the field
 352  *              flags specifiy that it is to be obtained before field access.
 353  *
 354  ******************************************************************************/
 355
 356 void
 357 AcpiExAcquireGlobalLock (
 358     UINT32                  FieldFlags)
 359 {
 360     ACPI_STATUS             Status;
 361
 362
 363     ACPI_FUNCTION_TRACE (ExAcquireGlobalLock);
 364
 365
 366     /* Only use the lock if the AlwaysLock bit is set */
 367
 368     if (!(FieldFlags & AML_FIELD_LOCK_RULE_MASK))
 369     {
 370         return_VOID;
 371     }
 372
 373     /* Attempt to get the global lock, wait forever */
 374
 375     Status = AcpiExAcquireMutexObject (ACPI_WAIT_FOREVER,
 376                 AcpiGbl_GlobalLockMutex, AcpiOsGetThreadId ());
 377
 378     if (ACPI_FAILURE (Status))
 379     {
 380         ACPI_EXCEPTION ((AE_INFO, Status,
 381             "Could not acquire Global Lock"));
 382     }
 383
 384     return_VOID;
 385 }
 386
 387
 388 /*******************************************************************************
 389  *
 390  * FUNCTION:    AcpiExReleaseGlobalLock
 391  *
 392  * PARAMETERS:  FieldFlags            - Flags with Lock rule:
 393  *                                      AlwaysLock or NeverLock
 394  *
 395  * RETURN:      None
 396  *
 397  * DESCRIPTION: Release the ACPI hardware Global Lock
 398  *
 399  ******************************************************************************/
 400
 401 void
 402 AcpiExReleaseGlobalLock (
 403     UINT32                  FieldFlags)
 404 {
 405     ACPI_STATUS             Status;
 406
 407
 408     ACPI_FUNCTION_TRACE (ExReleaseGlobalLock);
 409
 410
 411     /* Only use the lock if the AlwaysLock bit is set */
 412
 413     if (!(FieldFlags & AML_FIELD_LOCK_RULE_MASK))
 414     {
 415         return_VOID;
 416     }
 417
 418     /* Release the global lock */
 419
 420     Status = AcpiExReleaseMutexObject (AcpiGbl_GlobalLockMutex);
 421     if (ACPI_FAILURE (Status))
 422     {
 423         /* Report the error, but there isn't much else we can do */
 424
 425         ACPI_EXCEPTION ((AE_INFO, Status,
 426             "Could not release Global Lock"));
 427     }
 428
 429     return_VOID;
 430 }
 431
 432
 433 /*******************************************************************************
 434  *
 435  * FUNCTION:    AcpiExDigitsNeeded
 436  *
 437  * PARAMETERS:  Value           - Value to be represented
 438  *              Base            - Base of representation
 439  *
 440  * RETURN:      The number of digits.
 441  *
 442  * DESCRIPTION: Calculate the number of digits needed to represent the Value
 443  *              in the given Base (Radix)
 444  *
 445  ******************************************************************************/
 446
 447 static UINT32
 448 AcpiExDigitsNeeded (
 449     ACPI_INTEGER            Value,
 450     UINT32                  Base)
 451 {
 452     UINT32                  NumDigits;
 453     ACPI_INTEGER            CurrentValue;
 454
 455
 456     ACPI_FUNCTION_TRACE (ExDigitsNeeded);
 457
 458
 459     /* ACPI_INTEGER is unsigned, so we don't worry about a '-' prefix */
 460
 461     if (Value == 0)
 462     {
 463         return_UINT32 (1);
 464     }
 465
 466     CurrentValue = Value;
 467     NumDigits = 0;
 468
 469     /* Count the digits in the requested base */
 470
 471     while (CurrentValue)
 472     {
 473         (void) AcpiUtShortDivide (CurrentValue, Base, &CurrentValue, NULL);
 474         NumDigits++;
 475     }
 476
 477     return_UINT32 (NumDigits);
 478 }
 479
 480
 481 /*******************************************************************************
 482  *
 483  * FUNCTION:    AcpiExEisaIdToString
 484  *
 485  * PARAMETERS:  CompressedId    - EISAID to be converted
 486  *              OutString       - Where to put the converted string (8 bytes)
 487  *
 488  * RETURN:      None
 489  *
 490  * DESCRIPTION: Convert a numeric EISAID to string representation. Return
 491  *              buffer must be large enough to hold the string. The string
 492  *              returned is always exactly of length ACPI_EISAID_STRING_SIZE
 493  *              (includes null terminator). The EISAID is always 32 bits.
 494  *
 495  ******************************************************************************/
 496
 497 void
 498 AcpiExEisaIdToString (
 499     char                    *OutString,
 500     ACPI_INTEGER            CompressedId)
 501 {
 502     UINT32                  SwappedId;
 503
 504
 505     ACPI_FUNCTION_ENTRY ();
 506
 507
 508     /* The EISAID should be a 32-bit integer */
 509
 510     if (CompressedId > ACPI_UINT32_MAX)
 511     {
 512         ACPI_WARNING ((AE_INFO,
 513             "Expected EISAID is larger than 32 bits: 0x%8.8X%8.8X, truncating",
 514             ACPI_FORMAT_UINT64 (CompressedId)));
 515     }
 516
 517     /* Swap ID to big-endian to get contiguous bits */
 518
 519     SwappedId = AcpiUtDwordByteSwap ((UINT32) CompressedId);
 520
 521     /* First 3 bytes are uppercase letters. Next 4 bytes are hexadecimal */
 522
 523     OutString[0] = (char) (0x40 + (((unsigned long) SwappedId >> 26) & 0x1F));
 524     OutString[1] = (char) (0x40 + ((SwappedId >> 21) & 0x1F));
 525     OutString[2] = (char) (0x40 + ((SwappedId >> 16) & 0x1F));
 526     OutString[3] = AcpiUtHexToAsciiChar ((ACPI_INTEGER) SwappedId, 12);
 527     OutString[4] = AcpiUtHexToAsciiChar ((ACPI_INTEGER) SwappedId, 8);
 528     OutString[5] = AcpiUtHexToAsciiChar ((ACPI_INTEGER) SwappedId, 4);
 529     OutString[6] = AcpiUtHexToAsciiChar ((ACPI_INTEGER) SwappedId, 0);
 530     OutString[7] = 0;
 531 }
 532
 533
 534 /*******************************************************************************
 535  *
 536  * FUNCTION:    AcpiExIntegerToString
 537  *
 538  * PARAMETERS:  OutString       - Where to put the converted string. At least
 539  *                                21 bytes are needed to hold the largest
 540  *                                possible 64-bit integer.
 541  *              Value           - Value to be converted
 542  *
 543  * RETURN:      None, string
 544  *
 545  * DESCRIPTION: Convert a 64-bit integer to decimal string representation.
 546  *              Assumes string buffer is large enough to hold the string. The
 547  *              largest string is (ACPI_MAX64_DECIMAL_DIGITS + 1).
 548  *
 549  ******************************************************************************/
 550
 551 void
 552 AcpiExIntegerToString (
 553     char                    *OutString,
 554     ACPI_INTEGER            Value)
 555 {
 556     UINT32                  Count;
 557     UINT32                  DigitsNeeded;
 558     UINT32                  Remainder;
 559
 560
 561     ACPI_FUNCTION_ENTRY ();
 562
 563
 564     DigitsNeeded = AcpiExDigitsNeeded (Value, 10);
 565     OutString[DigitsNeeded] = 0;
 566
 567     for (Count = DigitsNeeded; Count > 0; Count--)
 568     {
 569         (void) AcpiUtShortDivide (Value, 10, &Value, &Remainder);
 570         OutString[Count-1] = (char) ('0' + Remainder);\
 571     }
 572 }
 573
 574 #endif