sys/contrib/dev/acpica-unix/tools/examples/examples.c

   1 /******************************************************************************
   2  *
   3  * Module Name: examples - Example ACPICA code
   4  *
   5  *****************************************************************************/
   6
   7 /******************************************************************************
   8  *
   9  * 1. Copyright Notice
  10  *
  11  * Some or all of this work - Copyright (c) 1999 - 2009, Intel Corp.
  12  * All rights reserved.
  13  *
  14  * 2. License
  15  *
  16  * 2.1. This is your license from Intel Corp. under its intellectual property
  17  * rights.  You may have additional license terms from the party that provided
  18  * you this software, covering your right to use that party's intellectual
  19  * property rights.
  20  *
  21  * 2.2. Intel grants, free of charge, to any person ("Licensee") obtaining a
  22  * copy of the source code appearing in this file ("Covered Code") an
  23  * irrevocable, perpetual, worldwide license under Intel's copyrights in the
  24  * base code distributed originally by Intel ("Original Intel Code") to copy,
  25  * make derivatives, distribute, use and display any portion of the Covered
  26  * Code in any form, with the right to sublicense such rights; and
  27  *
  28  * 2.3. Intel grants Licensee a non-exclusive and non-transferable patent
  29  * license (with the right to sublicense), under only those claims of Intel
  30  * patents that are infringed by the Original Intel Code, to make, use, sell,
  31  * offer to sell, and import the Covered Code and derivative works thereof
  32  * solely to the minimum extent necessary to exercise the above copyright
  33  * license, and in no event shall the patent license extend to any additions
  34  * to or modifications of the Original Intel Code.  No other license or right
  35  * is granted directly or by implication, estoppel or otherwise;
  36  *
  37  * The above copyright and patent license is granted only if the following
  38  * conditions are met:
  39  *
  40  * 3. Conditions
  41  *
  42  * 3.1. Redistribution of Source with Rights to Further Distribute Source.
  43  * Redistribution of source code of any substantial portion of the Covered
  44  * Code or modification with rights to further distribute source must include
  45  * the above Copyright Notice, the above License, this list of Conditions,
  46  * and the following Disclaimer and Export Compliance provision.  In addition,
  47  * Licensee must cause all Covered Code to which Licensee contributes to
  48  * contain a file documenting the changes Licensee made to create that Covered
  49  * Code and the date of any change.  Licensee must include in that file the
  50  * documentation of any changes made by any predecessor Licensee.  Licensee
  51  * must include a prominent statement that the modification is derived,
  52  * directly or indirectly, from Original Intel Code.
  53  *
  54  * 3.2. Redistribution of Source with no Rights to Further Distribute Source.
  55  * Redistribution of source code of any substantial portion of the Covered
  56  * Code or modification without rights to further distribute source must
  57  * include the following Disclaimer and Export Compliance provision in the
  58  * documentation and/or other materials provided with distribution.  In
  59  * addition, Licensee may not authorize further sublicense of source of any
  60  * portion of the Covered Code, and must include terms to the effect that the
  61  * license from Licensee to its licensee is limited to the intellectual
  62  * property embodied in the software Licensee provides to its licensee, and
  63  * not to intellectual property embodied in modifications its licensee may
  64  * make.
  65  *
  66  * 3.3. Redistribution of Executable. Redistribution in executable form of any
  67  * substantial portion of the Covered Code or modification must reproduce the
  68  * above Copyright Notice, and the following Disclaimer and Export Compliance
  69  * provision in the documentation and/or other materials provided with the
  70  * distribution.
  71  *
  72  * 3.4. Intel retains all right, title, and interest in and to the Original
  73  * Intel Code.
  74  *
  75  * 3.5. Neither the name Intel nor any other trademark owned or controlled by
  76  * Intel shall be used in advertising or otherwise to promote the sale, use or
  77  * other dealings in products derived from or relating to the Covered Code
  78  * without prior written authorization from Intel.
  79  *
  80  * 4. Disclaimer and Export Compliance
  81  *
  82  * 4.1. INTEL MAKES NO WARRANTY OF ANY KIND REGARDING ANY SOFTWARE PROVIDED
  83  * HERE.  ANY SOFTWARE ORIGINATING FROM INTEL OR DERIVED FROM INTEL SOFTWARE
  84  * IS PROVIDED "AS IS," AND INTEL WILL NOT PROVIDE ANY SUPPORT,  ASSISTANCE,
  85  * INSTALLATION, TRAINING OR OTHER SERVICES.  INTEL WILL NOT PROVIDE ANY
  86  * UPDATES, ENHANCEMENTS OR EXTENSIONS.  INTEL SPECIFICALLY DISCLAIMS ANY
  87  * IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A
  88  * PARTICULAR PURPOSE.
  89  *
  90  * 4.2. IN NO EVENT SHALL INTEL HAVE ANY LIABILITY TO LICENSEE, ITS LICENSEES
  91  * OR ANY OTHER THIRD PARTY, FOR ANY LOST PROFITS, LOST DATA, LOSS OF USE OR
  92  * COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR FOR ANY INDIRECT,
  93  * SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THIS AGREEMENT, UNDER ANY
  94  * CAUSE OF ACTION OR THEORY OF LIABILITY, AND IRRESPECTIVE OF WHETHER INTEL
  95  * HAS ADVANCE NOTICE OF THE POSSIBILITY OF SUCH DAMAGES.  THESE LIMITATIONS
  96  * SHALL APPLY NOTWITHSTANDING THE FAILURE OF THE ESSENTIAL PURPOSE OF ANY
  97  * LIMITED REMEDY.
  98  *
  99  * 4.3. Licensee shall not export, either directly or indirectly, any of this
 100  * software or system incorporating such software without first obtaining any
 101  * required license or other approval from the U. S. Department of Commerce or
 102  * any other agency or department of the United States Government.  In the
 103  * event Licensee exports any such software from the United States or
 104  * re-exports any such software from a foreign destination, Licensee shall
 105  * ensure that the distribution and export/re-export of the software is in
 106  * compliance with all laws, regulations, orders, or other restrictions of the
 107  * U.S. Export Administration Regulations. Licensee agrees that neither it nor
 108  * any of its subsidiaries will export/re-export any technical data, process,
 109  * software, or service, directly or indirectly, to any country for which the
 110  * United States government or any agency thereof requires an export license,
 111  * other governmental approval, or letter of assurance, without first obtaining
 112  * such license, approval or letter.
 113  *
 114  *****************************************************************************/
 115
 116
 117 /* Set the ACPICA application type for use in include/platform/acenv.h */
 118
 119 #ifndef WIN32
 120 #define WIN32
 121 #endif
 122
 123 #define ACPI_DEBUG_OUTPUT
 124
 125 /* ACPICA public headers */
 126
 127 #include "acpi.h"
 128
 129 #define _COMPONENT          ACPI_EXAMPLE
 130         ACPI_MODULE_NAME    ("examples")
 131
 132
 133 /******************************************************************************
 134  *
 135  * ACPICA Example Code
 136  *
 137  * This module contains examples of how the host OS should interface to the
 138  * ACPICA subsystem.
 139  *
 140  * 1) How to use the platform/acenv.h file and how to set configuration
 141  *      options.
 142  *
 143  * 2) main - using the debug output mechanism and the error/warning output
 144  *      macros.
 145  *
 146  * 3) Two examples of the ACPICA initialization sequence. The first is a
 147  *      initialization with no "early" ACPI table access. The second shows
 148  *      how to use ACPICA to obtain the tables very early during kernel
 149  *      initialization, even before dynamic memory is available.
 150  *
 151  * 4) How to invoke a control method, including argument setup and how to
 152  *      access the return value.
 153  *
 154  *****************************************************************************/
 155
 156 /* Standard Clib headers */
 157
 158 #include <stdio.h>
 159 #include <string.h>
 160
 161 /* Local Prototypes */
 162
 163 ACPI_STATUS
 164 InitializeFullAcpi (void);
 165
 166 ACPI_STATUS
 167 InstallHandlers (void);
 168
 169 void
 170 ExecuteOSI (void);
 171
 172
 173 /******************************************************************************
 174  *
 175  * FUNCTION:    main
 176  *
 177  * PARAMETERS:  argc, argv
 178  *
 179  * RETURN:      Status
 180  *
 181  * DESCRIPTION: Main routine. Shows the use of the various output macros, as
 182  *              well as the use of the debug layer/level globals.
 183  *
 184  *****************************************************************************/
 185
 186 int ACPI_SYSTEM_XFACE
 187 main (
 188     int                     argc,
 189     char                    **argv)
 190 {
 191     ACPI_FUNCTION_NAME (Examples-main);
 192
 193
 194     InitializeFullAcpi ();
 195
 196     /* Enable debug output, example debug print */
 197
 198     AcpiDbgLayer = ACPI_EXAMPLE;
 199     AcpiDbgLevel = ACPI_LV_INIT;
 200     ACPI_DEBUG_PRINT ((ACPI_DB_INIT, "Example Debug output\n"));
 201
 202     /* Example warning and error output */
 203
 204     ACPI_INFO        ((AE_INFO, "ACPICA example info message"));
 205     ACPI_WARNING     ((AE_INFO, "ACPICA example warning message"));
 206     ACPI_ERROR       ((AE_INFO, "ACPICA example error message"));
 207     ACPI_EXCEPTION   ((AE_INFO, AE_AML_OPERAND_TYPE, "Example exception message"));
 208
 209     ExecuteOSI ();
 210     return (0);
 211 }
 212
 213
 214 /******************************************************************************
 215  *
 216  * Example ACPICA initialization code. This shows a full initialization with
 217  * no early ACPI table access.
 218  *
 219  *****************************************************************************/
 220
 221 ACPI_STATUS
 222 InitializeFullAcpi (void)
 223 {
 224     ACPI_STATUS             Status;
 225
 226
 227     /* Initialize the ACPICA subsystem */
 228
 229     Status = AcpiInitializeSubsystem ();
 230     if (ACPI_FAILURE (Status))
 231     {
 232         ACPI_EXCEPTION ((AE_INFO, Status, "While initializing ACPICA"));
 233         return (Status);
 234     }
 235
 236     /* Initialize the ACPICA Table Manager and get all ACPI tables */
 237
 238     Status = AcpiInitializeTables (NULL, 16, FALSE);
 239     if (ACPI_FAILURE (Status))
 240     {
 241         ACPI_EXCEPTION ((AE_INFO, Status, "While initializing Table Manager"));
 242         return (Status);
 243     }
 244
 245     /* Create the ACPI namespace from ACPI tables */
 246
 247     Status = AcpiLoadTables ();
 248     if (ACPI_FAILURE (Status))
 249     {
 250         ACPI_EXCEPTION ((AE_INFO, Status, "While loading ACPI tables"));
 251         return (Status);
 252     }
 253
 254     /* Install local handlers */
 255
 256     Status = InstallHandlers ();
 257     if (ACPI_FAILURE (Status))
 258     {
 259         ACPI_EXCEPTION ((AE_INFO, Status, "While installing handlers"));
 260         return (Status);
 261     }
 262
 263     /* Initialize the ACPI hardware */
 264
 265     Status = AcpiEnableSubsystem (ACPI_FULL_INITIALIZATION);
 266     if (ACPI_FAILURE (Status))
 267     {
 268         ACPI_EXCEPTION ((AE_INFO, Status, "While enabling ACPICA"));
 269         return (Status);
 270     }
 271
 272     /* Complete the ACPI namespace object initialization */
 273
 274     Status = AcpiInitializeObjects (ACPI_FULL_INITIALIZATION);
 275     if (ACPI_FAILURE (Status))
 276     {
 277         ACPI_EXCEPTION ((AE_INFO, Status, "While initializing ACPICA objects"));
 278         return (Status);
 279     }
 280
 281     return (AE_OK);
 282 }
 283
 284
 285 /******************************************************************************
 286  *
 287  * Example ACPICA initialization code with early ACPI table access. This shows
 288  * an initialization that requires early access to ACPI tables (before
 289  * kernel dynamic memory is available)
 290  *
 291  *****************************************************************************/
 292
 293 /*
 294  * The purpose of this static table array is to avoid the use of kernel
 295  * dynamic memory which may not be available during early ACPI table
 296  * access.
 297  */
 298 #define ACPI_MAX_INIT_TABLES    16
 299 static ACPI_TABLE_DESC      TableArray[ACPI_MAX_INIT_TABLES];
 300
 301
 302 /*
 303  * This function would be called early in kernel initialization. After this
 304  * is called, all ACPI tables are available to the host.
 305  */
 306 ACPI_STATUS
 307 InitializeAcpiTables (void)
 308 {
 309     ACPI_STATUS             Status;
 310
 311
 312     /* Initialize the ACPICA Table Manager and get all ACPI tables */
 313
 314     Status = AcpiInitializeTables (TableArray, ACPI_MAX_INIT_TABLES, TRUE);
 315     return (Status);
 316 }
 317
 318
 319 /*
 320  * This function would be called after the kernel is initialized and
 321  * dynamic/virtual memory is available. It completes the initialization of
 322  * the ACPICA subsystem.
 323  */
 324 ACPI_STATUS
 325 InitializeAcpi (void)
 326 {
 327     ACPI_STATUS             Status;
 328
 329
 330     /* Initialize the ACPICA subsystem */
 331
 332     Status = AcpiInitializeSubsystem ();
 333     if (ACPI_FAILURE (Status))
 334     {
 335         return (Status);
 336     }
 337
 338     /* Copy the root table list to dynamic memory */
 339
 340     Status = AcpiReallocateRootTable ();
 341     if (ACPI_FAILURE (Status))
 342     {
 343         return (Status);
 344     }
 345
 346     /* Create the ACPI namespace from ACPI tables */
 347
 348     Status = AcpiLoadTables ();
 349     if (ACPI_FAILURE (Status))
 350     {
 351         return (Status);
 352     }
 353
 354     /* Install local handlers */
 355
 356     Status = InstallHandlers ();
 357     if (ACPI_FAILURE (Status))
 358     {
 359         ACPI_EXCEPTION ((AE_INFO, Status, "While installing handlers"));
 360         return (Status);
 361     }
 362
 363     /* Initialize the ACPI hardware */
 364
 365     Status = AcpiEnableSubsystem (ACPI_FULL_INITIALIZATION);
 366     if (ACPI_FAILURE (Status))
 367     {
 368         return (Status);
 369     }
 370
 371     /* Complete the ACPI namespace object initialization */
 372
 373     Status = AcpiInitializeObjects (ACPI_FULL_INITIALIZATION);
 374     if (ACPI_FAILURE (Status))
 375     {
 376         return (Status);
 377     }
 378
 379     return (AE_OK);
 380 }
 381
 382
 383 /******************************************************************************
 384  *
 385  * Example ACPICA handler and handler installation
 386  *
 387  *****************************************************************************/
 388
 389 void
 390 NotifyHandler (
 391     ACPI_HANDLE                 Device,
 392     UINT32                      Value,
 393     void                        *Context)
 394 {
 395
 396     ACPI_INFO ((AE_INFO, "Received a notify %X", Value));
 397 }
 398
 399
 400 ACPI_STATUS
 401 InstallHandlers (void)
 402 {
 403     ACPI_STATUS             Status;
 404
 405
 406     /* Install global notify handler */
 407
 408     Status = AcpiInstallNotifyHandler (ACPI_ROOT_OBJECT, ACPI_SYSTEM_NOTIFY,
 409                                         NotifyHandler, NULL);
 410     if (ACPI_FAILURE (Status))
 411     {
 412         ACPI_EXCEPTION ((AE_INFO, Status, "While installing Notify handler"));
 413         return (Status);
 414     }
 415
 416     return (AE_OK);
 417 }
 418
 419
 420 /******************************************************************************
 421  *
 422  * Example control method execution.
 423  *
 424  * _OSI is a predefined method that is implemented internally within ACPICA.
 425  *
 426  * Shows the following elements:
 427  *
 428  * 1) How to setup a control method argument and argument list
 429  * 2) How to setup the return value object
 430  * 3) How to invoke AcpiEvaluateObject
 431  * 4) How to check the returned ACPI_STATUS
 432  * 5) How to analyze the return value
 433  *
 434  *****************************************************************************/
 435
 436 void
 437 ExecuteOSI (void)
 438 {
 439     ACPI_STATUS             Status;
 440     ACPI_OBJECT_LIST        ArgList;
 441     ACPI_OBJECT             Arg[1];
 442     ACPI_BUFFER             ReturnValue;
 443     ACPI_OBJECT             *Object;
 444
 445
 446     ACPI_INFO ((AE_INFO, "Executing OSI method"));
 447
 448     /* Setup input argument */
 449
 450     ArgList.Count = 1;
 451     ArgList.Pointer = Arg;
 452
 453     Arg[0].Type = ACPI_TYPE_STRING;
 454     Arg[0].String.Pointer = "Windows 2001";
 455     Arg[0].String.Length = strlen (Arg[0].String.Pointer);
 456
 457     /* Ask ACPICA to allocate space for the return object */
 458
 459     ReturnValue.Length = ACPI_ALLOCATE_BUFFER;
 460
 461     Status = AcpiEvaluateObject (NULL, "\\_OSI", &ArgList, &ReturnValue);
 462     if (ACPI_FAILURE (Status))
 463     {
 464         ACPI_EXCEPTION ((AE_INFO, Status, "While executing _OSI"));
 465         return;
 466     }
 467
 468     /* Ensure that the return object is large enough */
 469
 470     if (ReturnValue.Length < sizeof (ACPI_OBJECT))
 471     {
 472         AcpiOsPrintf ("Return value from _OSI method too small, %.8X\n",
 473             ReturnValue.Length);
 474         return;
 475     }
 476
 477     /* Expect an integer return value from execution of _OSI */
 478
 479     Object = ReturnValue.Pointer;
 480     if (Object->Type != ACPI_TYPE_INTEGER)
 481     {
 482         AcpiOsPrintf ("Invalid return type from _OSI, %.2X\n", Object->Type);
 483     }
 484
 485     ACPI_INFO ((AE_INFO, "_OSI returned %.8X", (UINT32) Object->Integer.Value));
 486     AcpiOsFree (Object);
 487     return;
 488 }
 489
 490
 491 /******************************************************************************
 492  *
 493  * OSL support (only needed to link to the windows OSL)
 494  *
 495  *****************************************************************************/
 496
 497 FILE    *AcpiGbl_DebugFile;
 498
 499 ACPI_PHYSICAL_ADDRESS
 500 AeLocalGetRootPointer (
 501     void)
 502 {
 503
 504     return (0);
 505 }
 506