sys/contrib/dev/acpica/source/components/dispatcher/dsmethod.c

   1 /******************************************************************************
   2  *
   3  * Module Name: dsmethod - Parser/Interpreter interface - control method parsing
   4  *
   5  *****************************************************************************/
   6
   7 /*
   8  * Copyright (C) 2000 - 2014, Intel Corp.
   9  * All rights reserved.
  10  *
  11  * Redistribution and use in source and binary forms, with or without
  12  * modification, are permitted provided that the following conditions
  13  * are met:
  14  * 1. Redistributions of source code must retain the above copyright
  15  *    notice, this list of conditions, and the following disclaimer,
  16  *    without modification.
  17  * 2. Redistributions in binary form must reproduce at minimum a disclaimer
  18  *    substantially similar to the "NO WARRANTY" disclaimer below
  19  *    ("Disclaimer") and any redistribution must be conditioned upon
  20  *    including a substantially similar Disclaimer requirement for further
  21  *    binary redistribution.
  22  * 3. Neither the names of the above-listed copyright holders nor the names
  23  *    of any contributors may be used to endorse or promote products derived
  24  *    from this software without specific prior written permission.
  25  *
  26  * Alternatively, this software may be distributed under the terms of the
  27  * GNU General Public License ("GPL") version 2 as published by the Free
  28  * Software Foundation.
  29  *
  30  * NO WARRANTY
  31  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  32  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  33  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
  34  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  35  * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  36  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  37  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  38  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  39  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  40  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  41  * POSSIBILITY OF SUCH DAMAGES.
  42  */
  43
  44 #define __DSMETHOD_C__
  45
  46 #include "acpi.h"
  47 #include "accommon.h"
  48 #include "acdispat.h"
  49 #include "acinterp.h"
  50 #include "acnamesp.h"
  51 #include "acdisasm.h"
  52 #include "acparser.h"
  53 #include "amlcode.h"
  54
  55
  56 #define _COMPONENT          ACPI_DISPATCHER
  57         ACPI_MODULE_NAME    ("dsmethod")
  58
  59 /* Local prototypes */
  60
  61 static ACPI_STATUS
  62 AcpiDsDetectNamedOpcodes (
  63     ACPI_WALK_STATE         *WalkState,
  64     ACPI_PARSE_OBJECT       **OutOp);
  65
  66 static ACPI_STATUS
  67 AcpiDsCreateMethodMutex (
  68     ACPI_OPERAND_OBJECT     *MethodDesc);
  69
  70
  71 /*******************************************************************************
  72  *
  73  * FUNCTION:    AcpiDsAutoSerializeMethod
  74  *
  75  * PARAMETERS:  Node                        - Namespace Node of the method
  76  *              ObjDesc                     - Method object attached to node
  77  *
  78  * RETURN:      Status
  79  *
  80  * DESCRIPTION: Parse a control method AML to scan for control methods that
  81  *              need serialization due to the creation of named objects.
  82  *
  83  * NOTE: It is a bit of overkill to mark all such methods serialized, since
  84  * there is only a problem if the method actually blocks during execution.
  85  * A blocking operation is, for example, a Sleep() operation, or any access
  86  * to an operation region. However, it is probably not possible to easily
  87  * detect whether a method will block or not, so we simply mark all suspicious
  88  * methods as serialized.
  89  *
  90  * NOTE2: This code is essentially a generic routine for parsing a single
  91  * control method.
  92  *
  93  ******************************************************************************/
  94
  95 ACPI_STATUS
  96 AcpiDsAutoSerializeMethod (
  97     ACPI_NAMESPACE_NODE     *Node,
  98     ACPI_OPERAND_OBJECT     *ObjDesc)
  99 {
 100     ACPI_STATUS             Status;
 101     ACPI_PARSE_OBJECT       *Op = NULL;
 102     ACPI_WALK_STATE         *WalkState;
 103
 104
 105     ACPI_FUNCTION_TRACE_PTR (DsAutoSerializeMethod, Node);
 106
 107
 108     ACPI_DEBUG_PRINT ((ACPI_DB_PARSE,
 109         "Method auto-serialization parse [%4.4s] %p\n",
 110         AcpiUtGetNodeName (Node), Node));
 111
 112     /* Create/Init a root op for the method parse tree */
 113
 114     Op = AcpiPsAllocOp (AML_METHOD_OP);
 115     if (!Op)
 116     {
 117         return_ACPI_STATUS (AE_NO_MEMORY);
 118     }
 119
 120     AcpiPsSetName (Op, Node->Name.Integer);
 121     Op->Common.Node = Node;
 122
 123     /* Create and initialize a new walk state */
 124
 125     WalkState = AcpiDsCreateWalkState (Node->OwnerId, NULL, NULL, NULL);
 126     if (!WalkState)
 127     {
 128         return_ACPI_STATUS (AE_NO_MEMORY);
 129     }
 130
 131     Status = AcpiDsInitAmlWalk (WalkState, Op, Node, ObjDesc->Method.AmlStart,
 132                 ObjDesc->Method.AmlLength, NULL, 0);
 133     if (ACPI_FAILURE (Status))
 134     {
 135         AcpiDsDeleteWalkState (WalkState);
 136         return_ACPI_STATUS (Status);
 137     }
 138
 139     WalkState->DescendingCallback = AcpiDsDetectNamedOpcodes;
 140
 141     /* Parse the method, scan for creation of named objects */
 142
 143     Status = AcpiPsParseAml (WalkState);
 144     if (ACPI_FAILURE (Status))
 145     {
 146         return_ACPI_STATUS (Status);
 147     }
 148
 149     AcpiPsDeleteParseTree (Op);
 150     return_ACPI_STATUS (Status);
 151 }
 152
 153
 154 /*******************************************************************************
 155  *
 156  * FUNCTION:    AcpiDsDetectNamedOpcodes
 157  *
 158  * PARAMETERS:  WalkState       - Current state of the parse tree walk
 159  *              OutOp           - Unused, required for parser interface
 160  *
 161  * RETURN:      Status
 162  *
 163  * DESCRIPTION: Descending callback used during the loading of ACPI tables.
 164  *              Currently used to detect methods that must be marked serialized
 165  *              in order to avoid problems with the creation of named objects.
 166  *
 167  ******************************************************************************/
 168
 169 static ACPI_STATUS
 170 AcpiDsDetectNamedOpcodes (
 171     ACPI_WALK_STATE         *WalkState,
 172     ACPI_PARSE_OBJECT       **OutOp)
 173 {
 174
 175     ACPI_FUNCTION_NAME (AcpiDsDetectNamedOpcodes);
 176
 177
 178     /* We are only interested in opcodes that create a new name */
 179
 180     if (!(WalkState->OpInfo->Flags & (AML_NAMED | AML_CREATE | AML_FIELD)))
 181     {
 182         return (AE_OK);
 183     }
 184
 185     /*
 186      * At this point, we know we have a Named object opcode.
 187      * Mark the method as serialized. Later code will create a mutex for
 188      * this method to enforce serialization.
 189      *
 190      * Note, ACPI_METHOD_IGNORE_SYNC_LEVEL flag means that we will ignore the
 191      * Sync Level mechanism for this method, even though it is now serialized.
 192      * Otherwise, there can be conflicts with existing ASL code that actually
 193      * uses sync levels.
 194      */
 195     WalkState->MethodDesc->Method.SyncLevel = 0;
 196     WalkState->MethodDesc->Method.InfoFlags |=
 197         (ACPI_METHOD_SERIALIZED | ACPI_METHOD_IGNORE_SYNC_LEVEL);
 198
 199     ACPI_DEBUG_PRINT ((ACPI_DB_INFO,
 200         "Method serialized [%4.4s] %p - [%s] (%4.4X)\n",
 201         WalkState->MethodNode->Name.Ascii, WalkState->MethodNode,
 202         WalkState->OpInfo->Name, WalkState->Opcode));
 203
 204     /* Abort the parse, no need to examine this method any further */
 205
 206     return (AE_CTRL_TERMINATE);
 207 }
 208
 209
 210 /*******************************************************************************
 211  *
 212  * FUNCTION:    AcpiDsMethodError
 213  *
 214  * PARAMETERS:  Status          - Execution status
 215  *              WalkState       - Current state
 216  *
 217  * RETURN:      Status
 218  *
 219  * DESCRIPTION: Called on method error. Invoke the global exception handler if
 220  *              present, dump the method data if the disassembler is configured
 221  *
 222  *              Note: Allows the exception handler to change the status code
 223  *
 224  ******************************************************************************/
 225
 226 ACPI_STATUS
 227 AcpiDsMethodError (
 228     ACPI_STATUS             Status,
 229     ACPI_WALK_STATE         *WalkState)
 230 {
 231     ACPI_FUNCTION_ENTRY ();
 232
 233
 234     /* Ignore AE_OK and control exception codes */
 235
 236     if (ACPI_SUCCESS (Status) ||
 237         (Status & AE_CODE_CONTROL))
 238     {
 239         return (Status);
 240     }
 241
 242     /* Invoke the global exception handler */
 243
 244     if (AcpiGbl_ExceptionHandler)
 245     {
 246         /* Exit the interpreter, allow handler to execute methods */
 247
 248         AcpiExExitInterpreter ();
 249
 250         /*
 251          * Handler can map the exception code to anything it wants, including
 252          * AE_OK, in which case the executing method will not be aborted.
 253          */
 254         Status = AcpiGbl_ExceptionHandler (Status,
 255                     WalkState->MethodNode ?
 256                         WalkState->MethodNode->Name.Integer : 0,
 257                     WalkState->Opcode, WalkState->AmlOffset, NULL);
 258         AcpiExEnterInterpreter ();
 259     }
 260
 261     AcpiDsClearImplicitReturn (WalkState);
 262
 263 #ifdef ACPI_DISASSEMBLER
 264     if (ACPI_FAILURE (Status))
 265     {
 266         /* Display method locals/args if disassembler is present */
 267
 268         AcpiDmDumpMethodInfo (Status, WalkState, WalkState->Op);
 269     }
 270 #endif
 271
 272     return (Status);
 273 }
 274
 275
 276 /*******************************************************************************
 277  *
 278  * FUNCTION:    AcpiDsCreateMethodMutex
 279  *
 280  * PARAMETERS:  ObjDesc             - The method object
 281  *
 282  * RETURN:      Status
 283  *
 284  * DESCRIPTION: Create a mutex object for a serialized control method
 285  *
 286  ******************************************************************************/
 287
 288 static ACPI_STATUS
 289 AcpiDsCreateMethodMutex (
 290     ACPI_OPERAND_OBJECT     *MethodDesc)
 291 {
 292     ACPI_OPERAND_OBJECT     *MutexDesc;
 293     ACPI_STATUS             Status;
 294
 295
 296     ACPI_FUNCTION_TRACE (DsCreateMethodMutex);
 297
 298
 299     /* Create the new mutex object */
 300
 301     MutexDesc = AcpiUtCreateInternalObject (ACPI_TYPE_MUTEX);
 302     if (!MutexDesc)
 303     {
 304         return_ACPI_STATUS (AE_NO_MEMORY);
 305     }
 306
 307     /* Create the actual OS Mutex */
 308
 309     Status = AcpiOsCreateMutex (&MutexDesc->Mutex.OsMutex);
 310     if (ACPI_FAILURE (Status))
 311     {
 312         AcpiUtDeleteObjectDesc (MutexDesc);
 313         return_ACPI_STATUS (Status);
 314     }
 315
 316     MutexDesc->Mutex.SyncLevel = MethodDesc->Method.SyncLevel;
 317     MethodDesc->Method.Mutex = MutexDesc;
 318     return_ACPI_STATUS (AE_OK);
 319 }
 320
 321
 322 /*******************************************************************************
 323  *
 324  * FUNCTION:    AcpiDsBeginMethodExecution
 325  *
 326  * PARAMETERS:  MethodNode          - Node of the method
 327  *              ObjDesc             - The method object
 328  *              WalkState           - current state, NULL if not yet executing
 329  *                                    a method.
 330  *
 331  * RETURN:      Status
 332  *
 333  * DESCRIPTION: Prepare a method for execution. Parses the method if necessary,
 334  *              increments the thread count, and waits at the method semaphore
 335  *              for clearance to execute.
 336  *
 337  ******************************************************************************/
 338
 339 ACPI_STATUS
 340 AcpiDsBeginMethodExecution (
 341     ACPI_NAMESPACE_NODE     *MethodNode,
 342     ACPI_OPERAND_OBJECT     *ObjDesc,
 343     ACPI_WALK_STATE         *WalkState)
 344 {
 345     ACPI_STATUS             Status = AE_OK;
 346
 347
 348     ACPI_FUNCTION_TRACE_PTR (DsBeginMethodExecution, MethodNode);
 349
 350
 351     if (!MethodNode)
 352     {
 353         return_ACPI_STATUS (AE_NULL_ENTRY);
 354     }
 355
 356     /* Prevent wraparound of thread count */
 357
 358     if (ObjDesc->Method.ThreadCount == ACPI_UINT8_MAX)
 359     {
 360         ACPI_ERROR ((AE_INFO,
 361             "Method reached maximum reentrancy limit (255)"));
 362         return_ACPI_STATUS (AE_AML_METHOD_LIMIT);
 363     }
 364
 365     /*
 366      * If this method is serialized, we need to acquire the method mutex.
 367      */
 368     if (ObjDesc->Method.InfoFlags & ACPI_METHOD_SERIALIZED)
 369     {
 370         /*
 371          * Create a mutex for the method if it is defined to be Serialized
 372          * and a mutex has not already been created. We defer the mutex creation
 373          * until a method is actually executed, to minimize the object count
 374          */
 375         if (!ObjDesc->Method.Mutex)
 376         {
 377             Status = AcpiDsCreateMethodMutex (ObjDesc);
 378             if (ACPI_FAILURE (Status))
 379             {
 380                 return_ACPI_STATUS (Status);
 381             }
 382         }
 383
 384         /*
 385          * The CurrentSyncLevel (per-thread) must be less than or equal to
 386          * the sync level of the method. This mechanism provides some
 387          * deadlock prevention.
 388          *
 389          * If the method was auto-serialized, we just ignore the sync level
 390          * mechanism, because auto-serialization of methods can interfere
 391          * with ASL code that actually uses sync levels.
 392          *
 393          * Top-level method invocation has no walk state at this point
 394          */
 395         if (WalkState &&
 396             (!(ObjDesc->Method.InfoFlags & ACPI_METHOD_IGNORE_SYNC_LEVEL)) &&
 397             (WalkState->Thread->CurrentSyncLevel > ObjDesc->Method.Mutex->Mutex.SyncLevel))
 398         {
 399             ACPI_ERROR ((AE_INFO,
 400                 "Cannot acquire Mutex for method [%4.4s], current SyncLevel is too large (%u)",
 401                 AcpiUtGetNodeName (MethodNode),
 402                 WalkState->Thread->CurrentSyncLevel));
 403
 404             return_ACPI_STATUS (AE_AML_MUTEX_ORDER);
 405         }
 406
 407         /*
 408          * Obtain the method mutex if necessary. Do not acquire mutex for a
 409          * recursive call.
 410          */
 411         if (!WalkState ||
 412             !ObjDesc->Method.Mutex->Mutex.ThreadId ||
 413             (WalkState->Thread->ThreadId != ObjDesc->Method.Mutex->Mutex.ThreadId))
 414         {
 415             /*
 416              * Acquire the method mutex. This releases the interpreter if we
 417              * block (and reacquires it before it returns)
 418              */
 419             Status = AcpiExSystemWaitMutex (ObjDesc->Method.Mutex->Mutex.OsMutex,
 420                         ACPI_WAIT_FOREVER);
 421             if (ACPI_FAILURE (Status))
 422             {
 423                 return_ACPI_STATUS (Status);
 424             }
 425
 426             /* Update the mutex and walk info and save the original SyncLevel */
 427
 428             if (WalkState)
 429             {
 430                 ObjDesc->Method.Mutex->Mutex.OriginalSyncLevel =
 431                     WalkState->Thread->CurrentSyncLevel;
 432
 433                 ObjDesc->Method.Mutex->Mutex.ThreadId = WalkState->Thread->ThreadId;
 434                 WalkState->Thread->CurrentSyncLevel = ObjDesc->Method.SyncLevel;
 435             }
 436             else
 437             {
 438                 ObjDesc->Method.Mutex->Mutex.OriginalSyncLevel =
 439                     ObjDesc->Method.Mutex->Mutex.SyncLevel;
 440             }
 441         }
 442
 443         /* Always increase acquisition depth */
 444
 445         ObjDesc->Method.Mutex->Mutex.AcquisitionDepth++;
 446     }
 447
 448     /*
 449      * Allocate an Owner ID for this method, only if this is the first thread
 450      * to begin concurrent execution. We only need one OwnerId, even if the
 451      * method is invoked recursively.
 452      */
 453     if (!ObjDesc->Method.OwnerId)
 454     {
 455         Status = AcpiUtAllocateOwnerId (&ObjDesc->Method.OwnerId);
 456         if (ACPI_FAILURE (Status))
 457         {
 458             goto Cleanup;
 459         }
 460     }
 461
 462     /*
 463      * Increment the method parse tree thread count since it has been
 464      * reentered one more time (even if it is the same thread)
 465      */
 466     ObjDesc->Method.ThreadCount++;
 467     AcpiMethodCount++;
 468     return_ACPI_STATUS (Status);
 469
 470
 471 Cleanup:
 472     /* On error, must release the method mutex (if present) */
 473
 474     if (ObjDesc->Method.Mutex)
 475     {
 476         AcpiOsReleaseMutex (ObjDesc->Method.Mutex->Mutex.OsMutex);
 477     }
 478     return_ACPI_STATUS (Status);
 479 }
 480
 481
 482 /*******************************************************************************
 483  *
 484  * FUNCTION:    AcpiDsCallControlMethod
 485  *
 486  * PARAMETERS:  Thread              - Info for this thread
 487  *              ThisWalkState       - Current walk state
 488  *              Op                  - Current Op to be walked
 489  *
 490  * RETURN:      Status
 491  *
 492  * DESCRIPTION: Transfer execution to a called control method
 493  *
 494  ******************************************************************************/
 495
 496 ACPI_STATUS
 497 AcpiDsCallControlMethod (
 498     ACPI_THREAD_STATE       *Thread,
 499     ACPI_WALK_STATE         *ThisWalkState,
 500     ACPI_PARSE_OBJECT       *Op)
 501 {
 502     ACPI_STATUS             Status;
 503     ACPI_NAMESPACE_NODE     *MethodNode;
 504     ACPI_WALK_STATE         *NextWalkState = NULL;
 505     ACPI_OPERAND_OBJECT     *ObjDesc;
 506     ACPI_EVALUATE_INFO      *Info;
 507     UINT32                  i;
 508
 509
 510     ACPI_FUNCTION_TRACE_PTR (DsCallControlMethod, ThisWalkState);
 511
 512     ACPI_DEBUG_PRINT ((ACPI_DB_DISPATCH, "Calling method %p, currentstate=%p\n",
 513         ThisWalkState->PrevOp, ThisWalkState));
 514
 515     /*
 516      * Get the namespace entry for the control method we are about to call
 517      */
 518     MethodNode = ThisWalkState->MethodCallNode;
 519     if (!MethodNode)
 520     {
 521         return_ACPI_STATUS (AE_NULL_ENTRY);
 522     }
 523
 524     ObjDesc = AcpiNsGetAttachedObject (MethodNode);
 525     if (!ObjDesc)
 526     {
 527         return_ACPI_STATUS (AE_NULL_OBJECT);
 528     }
 529
 530     /* Init for new method, possibly wait on method mutex */
 531
 532     Status = AcpiDsBeginMethodExecution (MethodNode, ObjDesc,
 533                 ThisWalkState);
 534     if (ACPI_FAILURE (Status))
 535     {
 536         return_ACPI_STATUS (Status);
 537     }
 538
 539     /* Begin method parse/execution. Create a new walk state */
 540
 541     NextWalkState = AcpiDsCreateWalkState (ObjDesc->Method.OwnerId,
 542                         NULL, ObjDesc, Thread);
 543     if (!NextWalkState)
 544     {
 545         Status = AE_NO_MEMORY;
 546         goto Cleanup;
 547     }
 548
 549     /*
 550      * The resolved arguments were put on the previous walk state's operand
 551      * stack. Operands on the previous walk state stack always
 552      * start at index 0. Also, null terminate the list of arguments
 553      */
 554     ThisWalkState->Operands [ThisWalkState->NumOperands] = NULL;
 555
 556     /*
 557      * Allocate and initialize the evaluation information block
 558      * TBD: this is somewhat inefficient, should change interface to
 559      * DsInitAmlWalk. For now, keeps this struct off the CPU stack
 560      */
 561     Info = ACPI_ALLOCATE_ZEROED (sizeof (ACPI_EVALUATE_INFO));
 562     if (!Info)
 563     {
 564         Status = AE_NO_MEMORY;
 565         goto Cleanup;
 566     }
 567
 568     Info->Parameters = &ThisWalkState->Operands[0];
 569
 570     Status = AcpiDsInitAmlWalk (NextWalkState, NULL, MethodNode,
 571                 ObjDesc->Method.AmlStart, ObjDesc->Method.AmlLength,
 572                 Info, ACPI_IMODE_EXECUTE);
 573
 574     ACPI_FREE (Info);
 575     if (ACPI_FAILURE (Status))
 576     {
 577         goto Cleanup;
 578     }
 579
 580     /*
 581      * Delete the operands on the previous walkstate operand stack
 582      * (they were copied to new objects)
 583      */
 584     for (i = 0; i < ObjDesc->Method.ParamCount; i++)
 585     {
 586         AcpiUtRemoveReference (ThisWalkState->Operands [i]);
 587         ThisWalkState->Operands [i] = NULL;
 588     }
 589
 590     /* Clear the operand stack */
 591
 592     ThisWalkState->NumOperands = 0;
 593
 594     ACPI_DEBUG_PRINT ((ACPI_DB_DISPATCH,
 595         "**** Begin nested execution of [%4.4s] **** WalkState=%p\n",
 596         MethodNode->Name.Ascii, NextWalkState));
 597
 598     /* Invoke an internal method if necessary */
 599
 600     if (ObjDesc->Method.InfoFlags & ACPI_METHOD_INTERNAL_ONLY)
 601     {
 602         Status = ObjDesc->Method.Dispatch.Implementation (NextWalkState);
 603         if (Status == AE_OK)
 604         {
 605             Status = AE_CTRL_TERMINATE;
 606         }
 607     }
 608
 609     return_ACPI_STATUS (Status);
 610
 611
 612 Cleanup:
 613
 614     /* On error, we must terminate the method properly */
 615
 616     AcpiDsTerminateControlMethod (ObjDesc, NextWalkState);
 617     if (NextWalkState)
 618     {
 619         AcpiDsDeleteWalkState (NextWalkState);
 620     }
 621
 622     return_ACPI_STATUS (Status);
 623 }
 624
 625
 626 /*******************************************************************************
 627  *
 628  * FUNCTION:    AcpiDsRestartControlMethod
 629  *
 630  * PARAMETERS:  WalkState           - State for preempted method (caller)
 631  *              ReturnDesc          - Return value from the called method
 632  *
 633  * RETURN:      Status
 634  *
 635  * DESCRIPTION: Restart a method that was preempted by another (nested) method
 636  *              invocation. Handle the return value (if any) from the callee.
 637  *
 638  ******************************************************************************/
 639
 640 ACPI_STATUS
 641 AcpiDsRestartControlMethod (
 642     ACPI_WALK_STATE         *WalkState,
 643     ACPI_OPERAND_OBJECT     *ReturnDesc)
 644 {
 645     ACPI_STATUS             Status;
 646     int                     SameAsImplicitReturn;
 647
 648
 649     ACPI_FUNCTION_TRACE_PTR (DsRestartControlMethod, WalkState);
 650
 651
 652     ACPI_DEBUG_PRINT ((ACPI_DB_DISPATCH,
 653         "****Restart [%4.4s] Op %p ReturnValueFromCallee %p\n",
 654         AcpiUtGetNodeName (WalkState->MethodNode),
 655         WalkState->MethodCallOp, ReturnDesc));
 656
 657     ACPI_DEBUG_PRINT ((ACPI_DB_DISPATCH,
 658         "    ReturnFromThisMethodUsed?=%X ResStack %p Walk %p\n",
 659         WalkState->ReturnUsed,
 660         WalkState->Results, WalkState));
 661
 662     /* Did the called method return a value? */
 663
 664     if (ReturnDesc)
 665     {
 666         /* Is the implicit return object the same as the return desc? */
 667
 668         SameAsImplicitReturn = (WalkState->ImplicitReturnObj == ReturnDesc);
 669
 670         /* Are we actually going to use the return value? */
 671
 672         if (WalkState->ReturnUsed)
 673         {
 674             /* Save the return value from the previous method */
 675
 676             Status = AcpiDsResultPush (ReturnDesc, WalkState);
 677             if (ACPI_FAILURE (Status))
 678             {
 679                 AcpiUtRemoveReference (ReturnDesc);
 680                 return_ACPI_STATUS (Status);
 681             }
 682
 683             /*
 684              * Save as THIS method's return value in case it is returned
 685              * immediately to yet another method
 686              */
 687             WalkState->ReturnDesc = ReturnDesc;
 688         }
 689
 690         /*
 691          * The following code is the optional support for the so-called
 692          * "implicit return". Some AML code assumes that the last value of the
 693          * method is "implicitly" returned to the caller, in the absence of an
 694          * explicit return value.
 695          *
 696          * Just save the last result of the method as the return value.
 697          *
 698          * NOTE: this is optional because the ASL language does not actually
 699          * support this behavior.
 700          */
 701         else if (!AcpiDsDoImplicitReturn (ReturnDesc, WalkState, FALSE) ||
 702                  SameAsImplicitReturn)
 703         {
 704             /*
 705              * Delete the return value if it will not be used by the
 706              * calling method or remove one reference if the explicit return
 707              * is the same as the implicit return value.
 708              */
 709             AcpiUtRemoveReference (ReturnDesc);
 710         }
 711     }
 712
 713     return_ACPI_STATUS (AE_OK);
 714 }
 715
 716
 717 /*******************************************************************************
 718  *
 719  * FUNCTION:    AcpiDsTerminateControlMethod
 720  *
 721  * PARAMETERS:  MethodDesc          - Method object
 722  *              WalkState           - State associated with the method
 723  *
 724  * RETURN:      None
 725  *
 726  * DESCRIPTION: Terminate a control method. Delete everything that the method
 727  *              created, delete all locals and arguments, and delete the parse
 728  *              tree if requested.
 729  *
 730  * MUTEX:       Interpreter is locked
 731  *
 732  ******************************************************************************/
 733
 734 void
 735 AcpiDsTerminateControlMethod (
 736     ACPI_OPERAND_OBJECT     *MethodDesc,
 737     ACPI_WALK_STATE         *WalkState)
 738 {
 739
 740     ACPI_FUNCTION_TRACE_PTR (DsTerminateControlMethod, WalkState);
 741
 742
 743     /* MethodDesc is required, WalkState is optional */
 744
 745     if (!MethodDesc)
 746     {
 747         return_VOID;
 748     }
 749
 750     if (WalkState)
 751     {
 752         /* Delete all arguments and locals */
 753
 754         AcpiDsMethodDataDeleteAll (WalkState);
 755
 756         /*
 757          * If method is serialized, release the mutex and restore the
 758          * current sync level for this thread
 759          */
 760         if (MethodDesc->Method.Mutex)
 761         {
 762             /* Acquisition Depth handles recursive calls */
 763
 764             MethodDesc->Method.Mutex->Mutex.AcquisitionDepth--;
 765             if (!MethodDesc->Method.Mutex->Mutex.AcquisitionDepth)
 766             {
 767                 WalkState->Thread->CurrentSyncLevel =
 768                     MethodDesc->Method.Mutex->Mutex.OriginalSyncLevel;
 769
 770                 AcpiOsReleaseMutex (MethodDesc->Method.Mutex->Mutex.OsMutex);
 771                 MethodDesc->Method.Mutex->Mutex.ThreadId = 0;
 772             }
 773         }
 774
 775         /*
 776          * Delete any namespace objects created anywhere within the
 777          * namespace by the execution of this method. Unless:
 778          * 1) This method is a module-level executable code method, in which
 779          *    case we want make the objects permanent.
 780          * 2) There are other threads executing the method, in which case we
 781          *    will wait until the last thread has completed.
 782          */
 783         if (!(MethodDesc->Method.InfoFlags & ACPI_METHOD_MODULE_LEVEL) &&
 784              (MethodDesc->Method.ThreadCount == 1))
 785         {
 786             /* Delete any direct children of (created by) this method */
 787
 788             AcpiNsDeleteNamespaceSubtree (WalkState->MethodNode);
 789
 790             /*
 791              * Delete any objects that were created by this method
 792              * elsewhere in the namespace (if any were created).
 793              * Use of the ACPI_METHOD_MODIFIED_NAMESPACE optimizes the
 794              * deletion such that we don't have to perform an entire
 795              * namespace walk for every control method execution.
 796              */
 797             if (MethodDesc->Method.InfoFlags & ACPI_METHOD_MODIFIED_NAMESPACE)
 798             {
 799                 AcpiNsDeleteNamespaceByOwner (MethodDesc->Method.OwnerId);
 800                 MethodDesc->Method.InfoFlags &= ~ACPI_METHOD_MODIFIED_NAMESPACE;
 801             }
 802         }
 803     }
 804
 805     /* Decrement the thread count on the method */
 806
 807     if (MethodDesc->Method.ThreadCount)
 808     {
 809         MethodDesc->Method.ThreadCount--;
 810     }
 811     else
 812     {
 813         ACPI_ERROR ((AE_INFO,
 814             "Invalid zero thread count in method"));
 815     }
 816
 817     /* Are there any other threads currently executing this method? */
 818
 819     if (MethodDesc->Method.ThreadCount)
 820     {
 821         /*
 822          * Additional threads. Do not release the OwnerId in this case,
 823          * we immediately reuse it for the next thread executing this method
 824          */
 825         ACPI_DEBUG_PRINT ((ACPI_DB_DISPATCH,
 826             "*** Completed execution of one thread, %u threads remaining\n",
 827             MethodDesc->Method.ThreadCount));
 828     }
 829     else
 830     {
 831         /* This is the only executing thread for this method */
 832
 833         /*
 834          * Support to dynamically change a method from NotSerialized to
 835          * Serialized if it appears that the method is incorrectly written and
 836          * does not support multiple thread execution. The best example of this
 837          * is if such a method creates namespace objects and blocks. A second
 838          * thread will fail with an AE_ALREADY_EXISTS exception.
 839          *
 840          * This code is here because we must wait until the last thread exits
 841          * before marking the method as serialized.
 842          */
 843         if (MethodDesc->Method.InfoFlags & ACPI_METHOD_SERIALIZED_PENDING)
 844         {
 845             if (WalkState)
 846             {
 847                 ACPI_INFO ((AE_INFO,
 848                     "Marking method %4.4s as Serialized because of AE_ALREADY_EXISTS error",
 849                     WalkState->MethodNode->Name.Ascii));
 850             }
 851
 852             /*
 853              * Method tried to create an object twice and was marked as
 854              * "pending serialized". The probable cause is that the method
 855              * cannot handle reentrancy.
 856              *
 857              * The method was created as NotSerialized, but it tried to create
 858              * a named object and then blocked, causing the second thread
 859              * entrance to begin and then fail. Workaround this problem by
 860              * marking the method permanently as Serialized when the last
 861              * thread exits here.
 862              */
 863             MethodDesc->Method.InfoFlags &= ~ACPI_METHOD_SERIALIZED_PENDING;
 864             MethodDesc->Method.InfoFlags |=
 865                 (ACPI_METHOD_SERIALIZED | ACPI_METHOD_IGNORE_SYNC_LEVEL);
 866             MethodDesc->Method.SyncLevel = 0;
 867         }
 868
 869         /* No more threads, we can free the OwnerId */
 870
 871         if (!(MethodDesc->Method.InfoFlags & ACPI_METHOD_MODULE_LEVEL))
 872         {
 873             AcpiUtReleaseOwnerId (&MethodDesc->Method.OwnerId);
 874         }
 875     }
 876
 877     return_VOID;
 878 }