sys/contrib/dev/acpica/source/tools/examples/examples.c

   1 /******************************************************************************
   2  *
   3  * Module Name: examples - Example ACPICA initialization and execution code
   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 __EXAMPLES_C__
  45 #include "examples.h"
  46
  47 #define _COMPONENT          ACPI_EXAMPLE
  48         ACPI_MODULE_NAME    ("examples")
  49
  50
  51 /******************************************************************************
  52  *
  53  * ACPICA Example Code
  54  *
  55  * This module contains examples of how the host OS should interface to the
  56  * ACPICA subsystem.
  57  *
  58  * 1) How to use the platform/acenv.h file and how to set configuration
  59  *      options.
  60  *
  61  * 2) main - using the debug output mechanism and the error/warning output
  62  *      macros.
  63  *
  64  * 3) Two examples of the ACPICA initialization sequence. The first is a
  65  *      initialization with no "early" ACPI table access. The second shows
  66  *      how to use ACPICA to obtain the tables very early during kernel
  67  *      initialization, even before dynamic memory is available.
  68  *
  69  * 4) How to invoke a control method, including argument setup and how to
  70  *      access the return value.
  71  *
  72  *****************************************************************************/
  73
  74
  75 /* Local Prototypes */
  76
  77 static ACPI_STATUS
  78 InitializeFullAcpica (void);
  79
  80 static ACPI_STATUS
  81 InstallHandlers (void);
  82
  83 static void
  84 NotifyHandler (
  85     ACPI_HANDLE             Device,
  86     UINT32                  Value,
  87     void                    *Context);
  88
  89 static void
  90 ExecuteMAIN (void);
  91
  92 static void
  93 ExecuteOSI (void);
  94
  95 ACPI_STATUS
  96 InitializeAcpiTables (
  97     void);
  98
  99 ACPI_STATUS
 100 InitializeAcpi (
 101     void);
 102
 103
 104 /******************************************************************************
 105  *
 106  * FUNCTION:    main
 107  *
 108  * PARAMETERS:  argc, argv
 109  *
 110  * RETURN:      Status
 111  *
 112  * DESCRIPTION: Main routine. Shows the use of the various output macros, as
 113  *              well as the use of the debug layer/level globals.
 114  *
 115  *****************************************************************************/
 116
 117 int ACPI_SYSTEM_XFACE
 118 main (
 119     int                     argc,
 120     char                    **argv)
 121 {
 122
 123     ACPI_DEBUG_INITIALIZE (); /* For debug version only */
 124
 125     printf (ACPI_COMMON_SIGNON ("ACPI Example Code"));
 126
 127     /* Initialize the local ACPI tables (RSDP/RSDT/XSDT/FADT/DSDT/FACS) */
 128
 129     ExInitializeAcpiTables ();
 130
 131     /* Initialize the ACPICA subsystem */
 132
 133     InitializeFullAcpica ();
 134
 135     /* Example warning and error output */
 136
 137     ACPI_INFO        ((AE_INFO, "Example ACPICA info message"));
 138     ACPI_WARNING     ((AE_INFO, "Example ACPICA warning message"));
 139     ACPI_ERROR       ((AE_INFO, "Example ACPICA error message"));
 140     ACPI_EXCEPTION   ((AE_INFO, AE_AML_OPERAND_TYPE, "Example ACPICA exception message"));
 141
 142     ExecuteOSI ();
 143     ExecuteMAIN ();
 144     return (0);
 145 }
 146
 147
 148 /******************************************************************************
 149  *
 150  * Example ACPICA initialization code. This shows a full initialization with
 151  * no early ACPI table access.
 152  *
 153  *****************************************************************************/
 154
 155 static ACPI_STATUS
 156 InitializeFullAcpica (void)
 157 {
 158     ACPI_STATUS             Status;
 159
 160
 161     /* Initialize the ACPICA subsystem */
 162
 163     Status = AcpiInitializeSubsystem ();
 164     if (ACPI_FAILURE (Status))
 165     {
 166         ACPI_EXCEPTION ((AE_INFO, Status, "While initializing ACPICA"));
 167         return (Status);
 168     }
 169
 170     /* Initialize the ACPICA Table Manager and get all ACPI tables */
 171
 172     ACPI_INFO ((AE_INFO, "Loading ACPI tables"));
 173
 174     Status = AcpiInitializeTables (NULL, 16, FALSE);
 175     if (ACPI_FAILURE (Status))
 176     {
 177         ACPI_EXCEPTION ((AE_INFO, Status, "While initializing Table Manager"));
 178         return (Status);
 179     }
 180
 181     /* Create the ACPI namespace from ACPI tables */
 182
 183     Status = AcpiLoadTables ();
 184     if (ACPI_FAILURE (Status))
 185     {
 186         ACPI_EXCEPTION ((AE_INFO, Status, "While loading ACPI tables"));
 187         return (Status);
 188     }
 189
 190     /* Install local handlers */
 191
 192     Status = InstallHandlers ();
 193     if (ACPI_FAILURE (Status))
 194     {
 195         ACPI_EXCEPTION ((AE_INFO, Status, "While installing handlers"));
 196         return (Status);
 197     }
 198
 199     /* Initialize the ACPI hardware */
 200
 201     Status = AcpiEnableSubsystem (ACPI_FULL_INITIALIZATION);
 202     if (ACPI_FAILURE (Status))
 203     {
 204         ACPI_EXCEPTION ((AE_INFO, Status, "While enabling ACPICA"));
 205         return (Status);
 206     }
 207
 208     /* Complete the ACPI namespace object initialization */
 209
 210     Status = AcpiInitializeObjects (ACPI_FULL_INITIALIZATION);
 211     if (ACPI_FAILURE (Status))
 212     {
 213         ACPI_EXCEPTION ((AE_INFO, Status, "While initializing ACPICA objects"));
 214         return (Status);
 215     }
 216
 217     return (AE_OK);
 218 }
 219
 220
 221 /******************************************************************************
 222  *
 223  * Example ACPICA initialization code with early ACPI table access. This shows
 224  * an initialization that requires early access to ACPI tables (before
 225  * kernel dynamic memory is available)
 226  *
 227  *****************************************************************************/
 228
 229 /*
 230  * The purpose of this static table array is to avoid the use of kernel
 231  * dynamic memory which may not be available during early ACPI table
 232  * access.
 233  */
 234 #define ACPI_MAX_INIT_TABLES    16
 235 static ACPI_TABLE_DESC      TableArray[ACPI_MAX_INIT_TABLES];
 236
 237
 238 /*
 239  * This function would be called early in kernel initialization. After this
 240  * is called, all ACPI tables are available to the host.
 241  */
 242 ACPI_STATUS
 243 InitializeAcpiTables (
 244     void)
 245 {
 246     ACPI_STATUS             Status;
 247
 248
 249     /* Initialize the ACPICA Table Manager and get all ACPI tables */
 250
 251     Status = AcpiInitializeTables (TableArray, ACPI_MAX_INIT_TABLES, TRUE);
 252     return (Status);
 253 }
 254
 255
 256 /*
 257  * This function would be called after the kernel is initialized and
 258  * dynamic/virtual memory is available. It completes the initialization of
 259  * the ACPICA subsystem.
 260  */
 261 ACPI_STATUS
 262 InitializeAcpi (
 263     void)
 264 {
 265     ACPI_STATUS             Status;
 266
 267
 268     /* Initialize the ACPICA subsystem */
 269
 270     Status = AcpiInitializeSubsystem ();
 271     if (ACPI_FAILURE (Status))
 272     {
 273         return (Status);
 274     }
 275
 276     /* Copy the root table list to dynamic memory */
 277
 278     Status = AcpiReallocateRootTable ();
 279     if (ACPI_FAILURE (Status))
 280     {
 281         return (Status);
 282     }
 283
 284     /* Create the ACPI namespace from ACPI tables */
 285
 286     Status = AcpiLoadTables ();
 287     if (ACPI_FAILURE (Status))
 288     {
 289         return (Status);
 290     }
 291
 292     /* Install local handlers */
 293
 294     Status = InstallHandlers ();
 295     if (ACPI_FAILURE (Status))
 296     {
 297         ACPI_EXCEPTION ((AE_INFO, Status, "While installing handlers"));
 298         return (Status);
 299     }
 300
 301     /* Initialize the ACPI hardware */
 302
 303     Status = AcpiEnableSubsystem (ACPI_FULL_INITIALIZATION);
 304     if (ACPI_FAILURE (Status))
 305     {
 306         return (Status);
 307     }
 308
 309     /* Complete the ACPI namespace object initialization */
 310
 311     Status = AcpiInitializeObjects (ACPI_FULL_INITIALIZATION);
 312     if (ACPI_FAILURE (Status))
 313     {
 314         return (Status);
 315     }
 316
 317     return (AE_OK);
 318 }
 319
 320
 321 /******************************************************************************
 322  *
 323  * Example ACPICA handler and handler installation
 324  *
 325  *****************************************************************************/
 326
 327 static void
 328 NotifyHandler (
 329     ACPI_HANDLE                 Device,
 330     UINT32                      Value,
 331     void                        *Context)
 332 {
 333
 334     ACPI_INFO ((AE_INFO, "Received a notify 0x%X", Value));
 335 }
 336
 337
 338 static ACPI_STATUS
 339 InstallHandlers (void)
 340 {
 341     ACPI_STATUS             Status;
 342
 343
 344     /* Install global notify handler */
 345
 346     Status = AcpiInstallNotifyHandler (ACPI_ROOT_OBJECT, ACPI_SYSTEM_NOTIFY,
 347                                         NotifyHandler, NULL);
 348     if (ACPI_FAILURE (Status))
 349     {
 350         ACPI_EXCEPTION ((AE_INFO, Status, "While installing Notify handler"));
 351         return (Status);
 352     }
 353
 354     return (AE_OK);
 355 }
 356
 357
 358 /******************************************************************************
 359  *
 360  * Examples of control method execution.
 361  *
 362  * _OSI is a predefined method that is implemented internally within ACPICA.
 363  *
 364  * Shows the following elements:
 365  *
 366  * 1) How to setup a control method argument and argument list
 367  * 2) How to setup the return value object
 368  * 3) How to invoke AcpiEvaluateObject
 369  * 4) How to check the returned ACPI_STATUS
 370  * 5) How to analyze the return value
 371  *
 372  *****************************************************************************/
 373
 374 static void
 375 ExecuteOSI (void)
 376 {
 377     ACPI_STATUS             Status;
 378     ACPI_OBJECT_LIST        ArgList;
 379     ACPI_OBJECT             Arg[1];
 380     ACPI_BUFFER             ReturnValue;
 381     ACPI_OBJECT             *Object;
 382
 383
 384     ACPI_INFO ((AE_INFO, "Executing _OSI reserved method"));
 385
 386     /* Setup input argument */
 387
 388     ArgList.Count = 1;
 389     ArgList.Pointer = Arg;
 390
 391     Arg[0].Type = ACPI_TYPE_STRING;
 392     Arg[0].String.Pointer = "Windows 2001";
 393     Arg[0].String.Length = strlen (Arg[0].String.Pointer);
 394
 395     /* Ask ACPICA to allocate space for the return object */
 396
 397     ReturnValue.Length = ACPI_ALLOCATE_BUFFER;
 398
 399     Status = AcpiEvaluateObject (NULL, "\\_OSI", &ArgList, &ReturnValue);
 400     if (ACPI_FAILURE (Status))
 401     {
 402         ACPI_EXCEPTION ((AE_INFO, Status, "While executing _OSI"));
 403         return;
 404     }
 405
 406     /* Ensure that the return object is large enough */
 407
 408     if (ReturnValue.Length < sizeof (ACPI_OBJECT))
 409     {
 410         AcpiOsPrintf ("Return value from _OSI method too small, %.8X\n",
 411             ReturnValue.Length);
 412         goto ErrorExit;
 413     }
 414
 415     /* Expect an integer return value from execution of _OSI */
 416
 417     Object = ReturnValue.Pointer;
 418     if (Object->Type != ACPI_TYPE_INTEGER)
 419     {
 420         AcpiOsPrintf ("Invalid return type from _OSI, %.2X\n", Object->Type);
 421     }
 422
 423     ACPI_INFO ((AE_INFO, "_OSI returned 0x%8.8X", (UINT32) Object->Integer.Value));
 424
 425
 426 ErrorExit:
 427
 428     /* Free a buffer created via ACPI_ALLOCATE_BUFFER */
 429
 430     AcpiOsFree (ReturnValue.Pointer);
 431 }
 432
 433
 434 /******************************************************************************
 435  *
 436  * Execute an actual control method in the DSDT (MAIN)
 437  *
 438  *****************************************************************************/
 439
 440 static void
 441 ExecuteMAIN (void)
 442 {
 443     ACPI_STATUS             Status;
 444     ACPI_OBJECT_LIST        ArgList;
 445     ACPI_OBJECT             Arg[1];
 446     ACPI_BUFFER             ReturnValue;
 447     ACPI_OBJECT             *Object;
 448
 449
 450     ACPI_INFO ((AE_INFO, "Executing MAIN method"));
 451
 452     /* Setup input argument */
 453
 454     ArgList.Count = 1;
 455     ArgList.Pointer = Arg;
 456
 457     Arg[0].Type = ACPI_TYPE_STRING;
 458     Arg[0].String.Pointer = "Method [MAIN] is executing";
 459     Arg[0].String.Length = strlen (Arg[0].String.Pointer);
 460
 461     /* Ask ACPICA to allocate space for the return object */
 462
 463     ReturnValue.Length = ACPI_ALLOCATE_BUFFER;
 464
 465     Status = AcpiEvaluateObject (NULL, "\\MAIN", &ArgList, &ReturnValue);
 466     if (ACPI_FAILURE (Status))
 467     {
 468         ACPI_EXCEPTION ((AE_INFO, Status, "While executing MAIN"));
 469         return;
 470     }
 471
 472     if (ReturnValue.Pointer)
 473     {
 474         /* Obtain and validate the returned ACPI_OBJECT */
 475
 476         Object = ReturnValue.Pointer;
 477         if (Object->Type == ACPI_TYPE_STRING)
 478         {
 479             AcpiOsPrintf ("Method [MAIN] returned: \"%s\"\n", Object->String.Pointer);
 480         }
 481
 482         ACPI_FREE (ReturnValue.Pointer);
 483     }
 484 }