drivers/acpi/namespace/nseval.c

   1 /*******************************************************************************
   2  *
   3  * Module Name: nseval - Object evaluation interfaces -- includes control
   4  *                       method lookup and execution.
   5  *
   6  ******************************************************************************/
   7
   8 /*
   9  * Copyright (C) 2000 - 2004, R. Byron Moore
  10  * All rights reserved.
  11  *
  12  * Redistribution and use in source and binary forms, with or without
  13  * modification, are permitted provided that the following conditions
  14  * are met:
  15  * 1. Redistributions of source code must retain the above copyright
  16  *    notice, this list of conditions, and the following disclaimer,
  17  *    without modification.
  18  * 2. Redistributions in binary form must reproduce at minimum a disclaimer
  19  *    substantially similar to the "NO WARRANTY" disclaimer below
  20  *    ("Disclaimer") and any redistribution must be conditioned upon
  21  *    including a substantially similar Disclaimer requirement for further
  22  *    binary redistribution.
  23  * 3. Neither the names of the above-listed copyright holders nor the names
  24  *    of any contributors may be used to endorse or promote products derived
  25  *    from this software without specific prior written permission.
  26  *
  27  * Alternatively, this software may be distributed under the terms of the
  28  * GNU General Public License ("GPL") version 2 as published by the Free
  29  * Software Foundation.
  30  *
  31  * NO WARRANTY
  32  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  33  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  34  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
  35  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  36  * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  37  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  38  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  39  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  40  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  41  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  42  * POSSIBILITY OF SUCH DAMAGES.
  43  */
  44
  45
  46 #include <acpi/acpi.h>
  47 #include <acpi/acparser.h>
  48 #include <acpi/acinterp.h>
  49 #include <acpi/acnamesp.h>
  50
  51
  52 #define _COMPONENT          ACPI_NAMESPACE
  53          ACPI_MODULE_NAME    ("nseval")
  54
  55
  56 /*******************************************************************************
  57  *
  58  * FUNCTION:    acpi_ns_evaluate_relative
  59  *
  60  * PARAMETERS:  Handle              - The relative containing object
  61  *              Pathname            - Name of method to execute, If NULL, the
  62  *                                    handle is the object to execute
  63  *              Params              - List of parameters to pass to the method,
  64  *                                    terminated by NULL.  Params itself may be
  65  *                                    NULL if no parameters are being passed.
  66  *              return_object       - Where to put method's return value (if
  67  *                                    any).  If NULL, no value is returned.
  68  *
  69  * RETURN:      Status
  70  *
  71  * DESCRIPTION: Find and execute the requested method using the handle as a
  72  *              scope
  73  *
  74  * MUTEX:       Locks Namespace
  75  *
  76  ******************************************************************************/
  77
  78 acpi_status
  79 acpi_ns_evaluate_relative (
  80         char                            *pathname,
  81         struct acpi_parameter_info      *info)
  82 {
  83         acpi_status                     status;
  84         struct acpi_namespace_node      *node = NULL;
  85         union acpi_generic_state        *scope_info;
  86         char                            *internal_path = NULL;
  87
  88
  89         ACPI_FUNCTION_TRACE ("ns_evaluate_relative");
  90
  91
  92         /*
  93          * Must have a valid object handle
  94          */
  95         if (!info || !info->node) {
  96                 return_ACPI_STATUS (AE_BAD_PARAMETER);
  97         }
  98
  99         /* Build an internal name string for the method */
 100
 101         status = acpi_ns_internalize_name (pathname, &internal_path);
 102         if (ACPI_FAILURE (status)) {
 103                 return_ACPI_STATUS (status);
 104         }
 105
 106         scope_info = acpi_ut_create_generic_state ();
 107         if (!scope_info) {
 108                 goto cleanup1;
 109         }
 110
 111         /* Get the prefix handle and Node */
 112
 113         status = acpi_ut_acquire_mutex (ACPI_MTX_NAMESPACE);
 114         if (ACPI_FAILURE (status)) {
 115                 goto cleanup;
 116         }
 117
 118         info->node = acpi_ns_map_handle_to_node (info->node);
 119         if (!info->node) {
 120                 (void) acpi_ut_release_mutex (ACPI_MTX_NAMESPACE);
 121                 status = AE_BAD_PARAMETER;
 122                 goto cleanup;
 123         }
 124
 125         /* Lookup the name in the namespace */
 126
 127         scope_info->scope.node = info->node;
 128         status = acpi_ns_lookup (scope_info, internal_path, ACPI_TYPE_ANY,
 129                          ACPI_IMODE_EXECUTE, ACPI_NS_NO_UPSEARCH, NULL,
 130                          &node);
 131
 132         (void) acpi_ut_release_mutex (ACPI_MTX_NAMESPACE);
 133
 134         if (ACPI_FAILURE (status)) {
 135                 ACPI_DEBUG_PRINT ((ACPI_DB_NAMES, "Object [%s] not found [%s]\n",
 136                         pathname, acpi_format_exception (status)));
 137                 goto cleanup;
 138         }
 139
 140         /*
 141          * Now that we have a handle to the object, we can attempt
 142          * to evaluate it.
 143          */
 144         ACPI_DEBUG_PRINT ((ACPI_DB_NAMES, "%s [%p] Value %p\n",
 145                 pathname, node, acpi_ns_get_attached_object (node)));
 146
 147         info->node = node;
 148         status = acpi_ns_evaluate_by_handle (info);
 149
 150         ACPI_DEBUG_PRINT ((ACPI_DB_NAMES, "*** Completed eval of object %s ***\n",
 151                 pathname));
 152
 153 cleanup:
 154         acpi_ut_delete_generic_state (scope_info);
 155
 156 cleanup1:
 157         ACPI_MEM_FREE (internal_path);
 158         return_ACPI_STATUS (status);
 159 }
 160
 161
 162 /*******************************************************************************
 163  *
 164  * FUNCTION:    acpi_ns_evaluate_by_name
 165  *
 166  * PARAMETERS:  Pathname            - Fully qualified pathname to the object
 167  *              Info                - Contains:
 168  *              return_object       - Where to put method's return value (if
 169  *                                    any).  If NULL, no value is returned.
 170  *              Params              - List of parameters to pass to the method,
 171  *                                    terminated by NULL.  Params itself may be
 172  *                                    NULL if no parameters are being passed.
 173  *
 174  * RETURN:      Status
 175  *
 176  * DESCRIPTION: Find and execute the requested method passing the given
 177  *              parameters
 178  *
 179  * MUTEX:       Locks Namespace
 180  *
 181  ******************************************************************************/
 182
 183 acpi_status
 184 acpi_ns_evaluate_by_name (
 185         char                            *pathname,
 186         struct acpi_parameter_info      *info)
 187 {
 188         acpi_status                     status;
 189         char                            *internal_path = NULL;
 190
 191
 192         ACPI_FUNCTION_TRACE ("ns_evaluate_by_name");
 193
 194
 195         /* Build an internal name string for the method */
 196
 197         status = acpi_ns_internalize_name (pathname, &internal_path);
 198         if (ACPI_FAILURE (status)) {
 199                 return_ACPI_STATUS (status);
 200         }
 201
 202         status = acpi_ut_acquire_mutex (ACPI_MTX_NAMESPACE);
 203         if (ACPI_FAILURE (status)) {
 204                 goto cleanup;
 205         }
 206
 207         /* Lookup the name in the namespace */
 208
 209         status = acpi_ns_lookup (NULL, internal_path, ACPI_TYPE_ANY,
 210                          ACPI_IMODE_EXECUTE, ACPI_NS_NO_UPSEARCH, NULL,
 211                          &info->node);
 212
 213         (void) acpi_ut_release_mutex (ACPI_MTX_NAMESPACE);
 214
 215         if (ACPI_FAILURE (status)) {
 216                 ACPI_DEBUG_PRINT ((ACPI_DB_NAMES, "Object at [%s] was not found, status=%.4X\n",
 217                         pathname, status));
 218                 goto cleanup;
 219         }
 220
 221         /*
 222          * Now that we have a handle to the object, we can attempt
 223          * to evaluate it.
 224          */
 225         ACPI_DEBUG_PRINT ((ACPI_DB_NAMES, "%s [%p] Value %p\n",
 226                 pathname, info->node, acpi_ns_get_attached_object (info->node)));
 227
 228         status = acpi_ns_evaluate_by_handle (info);
 229
 230         ACPI_DEBUG_PRINT ((ACPI_DB_NAMES, "*** Completed eval of object %s ***\n",
 231                 pathname));
 232
 233
 234 cleanup:
 235
 236         /* Cleanup */
 237
 238         if (internal_path) {
 239                 ACPI_MEM_FREE (internal_path);
 240         }
 241
 242         return_ACPI_STATUS (status);
 243 }
 244
 245
 246 /*******************************************************************************
 247  *
 248  * FUNCTION:    acpi_ns_evaluate_by_handle
 249  *
 250  * PARAMETERS:  Handle              - Method Node to execute
 251  *              Params              - List of parameters to pass to the method,
 252  *                                    terminated by NULL.  Params itself may be
 253  *                                    NULL if no parameters are being passed.
 254  *              param_type          - Type of Parameter list
 255  *              return_object       - Where to put method's return value (if
 256  *                                    any).  If NULL, no value is returned.
 257  *
 258  * RETURN:      Status
 259  *
 260  * DESCRIPTION: Execute the requested method passing the given parameters
 261  *
 262  * MUTEX:       Locks Namespace
 263  *
 264  ******************************************************************************/
 265
 266 acpi_status
 267 acpi_ns_evaluate_by_handle (
 268         struct acpi_parameter_info      *info)
 269 {
 270         acpi_status                     status;
 271
 272
 273         ACPI_FUNCTION_TRACE ("ns_evaluate_by_handle");
 274
 275
 276         /* Check if namespace has been initialized */
 277
 278         if (!acpi_gbl_root_node) {
 279                 return_ACPI_STATUS (AE_NO_NAMESPACE);
 280         }
 281
 282         /* Parameter Validation */
 283
 284         if (!info) {
 285                 return_ACPI_STATUS (AE_BAD_PARAMETER);
 286         }
 287
 288         /* Initialize the return value to an invalid object */
 289
 290         info->return_object = NULL;
 291
 292         /* Get the prefix handle and Node */
 293
 294         status = acpi_ut_acquire_mutex (ACPI_MTX_NAMESPACE);
 295         if (ACPI_FAILURE (status)) {
 296                 return_ACPI_STATUS (status);
 297         }
 298
 299         info->node = acpi_ns_map_handle_to_node (info->node);
 300         if (!info->node) {
 301                 (void) acpi_ut_release_mutex (ACPI_MTX_NAMESPACE);
 302                 return_ACPI_STATUS (AE_BAD_PARAMETER);
 303         }
 304
 305         /*
 306          * For a method alias, we must grab the actual method node
 307          * so that proper scoping context will be established
 308          * before execution.
 309          */
 310         if (acpi_ns_get_type (info->node) == ACPI_TYPE_LOCAL_METHOD_ALIAS) {
 311                 info->node = ACPI_CAST_PTR (struct acpi_namespace_node, info->node->object);
 312         }
 313
 314         /*
 315          * Two major cases here:
 316          * 1) The object is an actual control method -- execute it.
 317          * 2) The object is not a method -- just return it's current
 318          *      value
 319          *
 320          * In both cases, the namespace is unlocked by the
 321          *  acpi_ns* procedure
 322          */
 323         if (acpi_ns_get_type (info->node) == ACPI_TYPE_METHOD) {
 324                 /*
 325                  * Case 1) We have an actual control method to execute
 326                  */
 327                 status = acpi_ns_execute_control_method (info);
 328         }
 329         else {
 330                 /*
 331                  * Case 2) Object is NOT a method, just return its
 332                  * current value
 333                  */
 334                 status = acpi_ns_get_object_value (info);
 335         }
 336
 337         /*
 338          * Check if there is a return value on the stack that must
 339          * be dealt with
 340          */
 341         if (status == AE_CTRL_RETURN_VALUE) {
 342                 /* Map AE_CTRL_RETURN_VALUE to AE_OK, we are done with it */
 343
 344                 status = AE_OK;
 345         }
 346
 347         /*
 348          * Namespace was unlocked by the handling acpi_ns* function,
 349          * so we just return
 350          */
 351         return_ACPI_STATUS (status);
 352 }
 353
 354
 355 /*******************************************************************************
 356  *
 357  * FUNCTION:    acpi_ns_execute_control_method
 358  *
 359  * PARAMETERS:  method_node         - The method to execute
 360  *              Params              - List of parameters to pass to the method,
 361  *                                    terminated by NULL.  Params itself may be
 362  *                                    NULL if no parameters are being passed.
 363  *              return_obj_desc     - List of result objects to be returned
 364  *                                    from the method.
 365  *
 366  * RETURN:      Status
 367  *
 368  * DESCRIPTION: Execute the requested method passing the given parameters
 369  *
 370  * MUTEX:       Assumes namespace is locked
 371  *
 372  ******************************************************************************/
 373
 374 acpi_status
 375 acpi_ns_execute_control_method (
 376         struct acpi_parameter_info      *info)
 377 {
 378         acpi_status                     status;
 379         union acpi_operand_object       *obj_desc;
 380
 381
 382         ACPI_FUNCTION_TRACE ("ns_execute_control_method");
 383
 384
 385         /* Verify that there is a method associated with this object */
 386
 387         obj_desc = acpi_ns_get_attached_object (info->node);
 388         if (!obj_desc) {
 389                 ACPI_DEBUG_PRINT ((ACPI_DB_ERROR, "No attached method object\n"));
 390
 391                 (void) acpi_ut_release_mutex (ACPI_MTX_NAMESPACE);
 392                 return_ACPI_STATUS (AE_NULL_OBJECT);
 393         }
 394
 395         ACPI_DUMP_PATHNAME (info->node, "Execute Method:",
 396                 ACPI_LV_INFO, _COMPONENT);
 397
 398         ACPI_DEBUG_PRINT ((ACPI_DB_EXEC, "Method at AML address %p Length %X\n",
 399                 obj_desc->method.aml_start + 1, obj_desc->method.aml_length - 1));
 400
 401         /*
 402          * Unlock the namespace before execution.  This allows namespace access
 403          * via the external Acpi* interfaces while a method is being executed.
 404          * However, any namespace deletion must acquire both the namespace and
 405          * interpreter locks to ensure that no thread is using the portion of the
 406          * namespace that is being deleted.
 407          */
 408         status = acpi_ut_release_mutex (ACPI_MTX_NAMESPACE);
 409         if (ACPI_FAILURE (status)) {
 410                 return_ACPI_STATUS (status);
 411         }
 412
 413         /*
 414          * Execute the method via the interpreter.  The interpreter is locked
 415          * here before calling into the AML parser
 416          */
 417         status = acpi_ex_enter_interpreter ();
 418         if (ACPI_FAILURE (status)) {
 419                 return_ACPI_STATUS (status);
 420         }
 421
 422         status = acpi_psx_execute (info);
 423         acpi_ex_exit_interpreter ();
 424
 425         return_ACPI_STATUS (status);
 426 }
 427
 428
 429 /*******************************************************************************
 430  *
 431  * FUNCTION:    acpi_ns_get_object_value
 432  *
 433  * PARAMETERS:  Node                - The object
 434  *              return_obj_desc     - Where the objects value is returned
 435  *
 436  * RETURN:      Status
 437  *
 438  * DESCRIPTION: Return the current value of the object
 439  *
 440  * MUTEX:       Assumes namespace is locked, leaves namespace unlocked
 441  *
 442  ******************************************************************************/
 443
 444 acpi_status
 445 acpi_ns_get_object_value (
 446         struct acpi_parameter_info      *info)
 447 {
 448         acpi_status                     status = AE_OK;
 449         struct acpi_namespace_node      *resolved_node = info->node;
 450
 451
 452         ACPI_FUNCTION_TRACE ("ns_get_object_value");
 453
 454
 455         /*
 456          * Objects require additional resolution steps (e.g., the
 457          * Node may be a field that must be read, etc.) -- we can't just grab
 458          * the object out of the node.
 459          */
 460
 461         /*
 462          * Use resolve_node_to_value() to get the associated value. This call
 463          * always deletes obj_desc (allocated above).
 464          *
 465          * NOTE: we can get away with passing in NULL for a walk state
 466          * because obj_desc is guaranteed to not be a reference to either
 467          * a method local or a method argument (because this interface can only be
 468          * called from the acpi_evaluate external interface, never called from
 469          * a running control method.)
 470          *
 471          * Even though we do not directly invoke the interpreter
 472          * for this, we must enter it because we could access an opregion.
 473          * The opregion access code assumes that the interpreter
 474          * is locked.
 475          *
 476          * We must release the namespace lock before entering the
 477          * intepreter.
 478          */
 479         status = acpi_ut_release_mutex (ACPI_MTX_NAMESPACE);
 480         if (ACPI_FAILURE (status)) {
 481                 return_ACPI_STATUS (status);
 482         }
 483
 484         status = acpi_ex_enter_interpreter ();
 485         if (ACPI_SUCCESS (status)) {
 486                 status = acpi_ex_resolve_node_to_value (&resolved_node, NULL);
 487                 /*
 488                  * If acpi_ex_resolve_node_to_value() succeeded, the return value was
 489                  * placed in resolved_node.
 490                  */
 491                 acpi_ex_exit_interpreter ();
 492
 493                 if (ACPI_SUCCESS (status)) {
 494                         status = AE_CTRL_RETURN_VALUE;
 495                         info->return_object = ACPI_CAST_PTR (union acpi_operand_object, resolved_node);
 496                         ACPI_DEBUG_PRINT ((ACPI_DB_NAMES, "Returning object %p [%s]\n",
 497                                 info->return_object, acpi_ut_get_object_type_name (info->return_object)));
 498                 }
 499         }
 500
 501         /* Namespace is unlocked */
 502
 503         return_ACPI_STATUS (status);
 504 }
 505