include/acpi/acutils.h

   1 /******************************************************************************
   2  *
   3  * Name: acutils.h -- prototypes for the common (subsystem-wide) procedures
   4  *
   5  *****************************************************************************/
   6
   7 /*
   8  * Copyright (C) 2000 - 2005, R. Byron Moore
   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 #ifndef _ACUTILS_H
  45 #define _ACUTILS_H
  46
  47
  48 typedef
  49 acpi_status (*acpi_pkg_callback) (
  50         u8                              object_type,
  51         union acpi_operand_object       *source_object,
  52         union acpi_generic_state        *state,
  53         void                            *context);
  54
  55 struct acpi_pkg_info
  56 {
  57         u8                              *free_space;
  58         acpi_size                       length;
  59         u32                             object_space;
  60         u32                             num_packages;
  61 };
  62
  63 #define REF_INCREMENT       (u16) 0
  64 #define REF_DECREMENT       (u16) 1
  65 #define REF_FORCE_DELETE    (u16) 2
  66
  67 /* acpi_ut_dump_buffer */
  68
  69 #define DB_BYTE_DISPLAY     1
  70 #define DB_WORD_DISPLAY     2
  71 #define DB_DWORD_DISPLAY    4
  72 #define DB_QWORD_DISPLAY    8
  73
  74
  75 /*
  76  * utglobal - Global data structures and procedures
  77  */
  78 void
  79 acpi_ut_init_globals (
  80         void);
  81
  82 #if defined(ACPI_DEBUG_OUTPUT) || defined(ACPI_DEBUGGER)
  83
  84 char *
  85 acpi_ut_get_mutex_name (
  86         u32                             mutex_id);
  87
  88 #endif
  89
  90 char *
  91 acpi_ut_get_type_name (
  92         acpi_object_type                type);
  93
  94 char *
  95 acpi_ut_get_node_name (
  96         void                            *object);
  97
  98 char *
  99 acpi_ut_get_descriptor_name (
 100         void                            *object);
 101
 102 char *
 103 acpi_ut_get_object_type_name (
 104         union acpi_operand_object       *obj_desc);
 105
 106 char *
 107 acpi_ut_get_region_name (
 108         u8                              space_id);
 109
 110 char *
 111 acpi_ut_get_event_name (
 112         u32                             event_id);
 113
 114 char
 115 acpi_ut_hex_to_ascii_char (
 116         acpi_integer                    integer,
 117         u32                             position);
 118
 119 u8
 120 acpi_ut_valid_object_type (
 121         acpi_object_type                type);
 122
 123
 124 /*
 125  * utinit - miscellaneous initialization and shutdown
 126  */
 127 acpi_status
 128 acpi_ut_hardware_initialize (
 129         void);
 130
 131 void
 132 acpi_ut_subsystem_shutdown (
 133         void);
 134
 135 acpi_status
 136 acpi_ut_validate_fadt (
 137         void);
 138
 139
 140 /*
 141  * utclib - Local implementations of C library functions
 142  */
 143 #ifndef ACPI_USE_SYSTEM_CLIBRARY
 144
 145 acpi_size
 146 acpi_ut_strlen (
 147         const char                      *string);
 148
 149 char *
 150 acpi_ut_strcpy (
 151         char                            *dst_string,
 152         const char                      *src_string);
 153
 154 char *
 155 acpi_ut_strncpy (
 156         char                            *dst_string,
 157         const char                      *src_string,
 158         acpi_size                       count);
 159
 160 int
 161 acpi_ut_memcmp (
 162         const char                      *buffer1,
 163         const char                      *buffer2,
 164         acpi_size                       count);
 165
 166 int
 167 acpi_ut_strncmp (
 168         const char                      *string1,
 169         const char                      *string2,
 170         acpi_size                       count);
 171
 172 int
 173 acpi_ut_strcmp (
 174         const char                      *string1,
 175         const char                      *string2);
 176
 177 char *
 178 acpi_ut_strcat (
 179         char                            *dst_string,
 180         const char                      *src_string);
 181
 182 char *
 183 acpi_ut_strncat (
 184         char                            *dst_string,
 185         const char                      *src_string,
 186         acpi_size                       count);
 187
 188 u32
 189 acpi_ut_strtoul (
 190         const char                      *string,
 191         char                            **terminator,
 192         u32                             base);
 193
 194 char *
 195 acpi_ut_strstr (
 196         char                            *string1,
 197         char                            *string2);
 198
 199 void *
 200 acpi_ut_memcpy (
 201         void                            *dest,
 202         const void                      *src,
 203         acpi_size                       count);
 204
 205 void *
 206 acpi_ut_memset (
 207         void                            *dest,
 208         acpi_native_uint                value,
 209         acpi_size                       count);
 210
 211 int
 212 acpi_ut_to_upper (
 213         int                             c);
 214
 215 int
 216 acpi_ut_to_lower (
 217         int                             c);
 218
 219 extern const u8 _acpi_ctype[];
 220
 221 #define _ACPI_XA     0x00    /* extra alphabetic - not supported */
 222 #define _ACPI_XS     0x40    /* extra space */
 223 #define _ACPI_BB     0x00    /* BEL, BS, etc. - not supported */
 224 #define _ACPI_CN     0x20    /* CR, FF, HT, NL, VT */
 225 #define _ACPI_DI     0x04    /* '0'-'9' */
 226 #define _ACPI_LO     0x02    /* 'a'-'z' */
 227 #define _ACPI_PU     0x10    /* punctuation */
 228 #define _ACPI_SP     0x08    /* space */
 229 #define _ACPI_UP     0x01    /* 'A'-'Z' */
 230 #define _ACPI_XD     0x80    /* '0'-'9', 'A'-'F', 'a'-'f' */
 231
 232 #define ACPI_IS_DIGIT(c)  (_acpi_ctype[(unsigned char)(c)] & (_ACPI_DI))
 233 #define ACPI_IS_SPACE(c)  (_acpi_ctype[(unsigned char)(c)] & (_ACPI_SP))
 234 #define ACPI_IS_XDIGIT(c) (_acpi_ctype[(unsigned char)(c)] & (_ACPI_XD))
 235 #define ACPI_IS_UPPER(c)  (_acpi_ctype[(unsigned char)(c)] & (_ACPI_UP))
 236 #define ACPI_IS_LOWER(c)  (_acpi_ctype[(unsigned char)(c)] & (_ACPI_LO))
 237 #define ACPI_IS_PRINT(c)  (_acpi_ctype[(unsigned char)(c)] & (_ACPI_LO | _ACPI_UP | _ACPI_DI | _ACPI_SP | _ACPI_PU))
 238 #define ACPI_IS_ALPHA(c)  (_acpi_ctype[(unsigned char)(c)] & (_ACPI_LO | _ACPI_UP))
 239 #define ACPI_IS_ASCII(c)  ((c) < 0x80)
 240
 241 #endif /* ACPI_USE_SYSTEM_CLIBRARY */
 242
 243
 244 /*
 245  * utcopy - Object construction and conversion interfaces
 246  */
 247 acpi_status
 248 acpi_ut_build_simple_object(
 249         union acpi_operand_object       *obj,
 250         union acpi_object               *user_obj,
 251         u8                              *data_space,
 252         u32                             *buffer_space_used);
 253
 254 acpi_status
 255 acpi_ut_build_package_object (
 256         union acpi_operand_object       *obj,
 257         u8                              *buffer,
 258         u32                             *space_used);
 259
 260 acpi_status
 261 acpi_ut_copy_iobject_to_eobject (
 262         union acpi_operand_object       *obj,
 263         struct acpi_buffer              *ret_buffer);
 264
 265 acpi_status
 266 acpi_ut_copy_eobject_to_iobject (
 267         union acpi_object               *obj,
 268         union acpi_operand_object       **internal_obj);
 269
 270 acpi_status
 271 acpi_ut_copy_isimple_to_isimple (
 272         union acpi_operand_object       *source_obj,
 273         union acpi_operand_object       *dest_obj);
 274
 275 acpi_status
 276 acpi_ut_copy_iobject_to_iobject (
 277         union acpi_operand_object       *source_desc,
 278         union acpi_operand_object       **dest_desc,
 279         struct acpi_walk_state          *walk_state);
 280
 281
 282 /*
 283  * utcreate - Object creation
 284  */
 285 acpi_status
 286 acpi_ut_update_object_reference (
 287         union acpi_operand_object       *object,
 288         u16                             action);
 289
 290
 291 /*
 292  * utdebug - Debug interfaces
 293  */
 294 void
 295 acpi_ut_init_stack_ptr_trace (
 296         void);
 297
 298 void
 299 acpi_ut_track_stack_ptr (
 300         void);
 301
 302 void
 303 acpi_ut_trace (
 304         u32                             line_number,
 305         char                            *function_name,
 306         char                            *module_name,
 307         u32                             component_id);
 308
 309 void
 310 acpi_ut_trace_ptr (
 311         u32                             line_number,
 312         char                            *function_name,
 313         char                            *module_name,
 314         u32                             component_id,
 315         void                            *pointer);
 316
 317 void
 318 acpi_ut_trace_u32 (
 319         u32                             line_number,
 320         char                            *function_name,
 321         char                            *module_name,
 322         u32                             component_id,
 323         u32                             integer);
 324
 325 void
 326 acpi_ut_trace_str (
 327         u32                             line_number,
 328         char                            *function_name,
 329         char                            *module_name,
 330         u32                             component_id,
 331         char                            *string);
 332
 333 void
 334 acpi_ut_exit (
 335         u32                             line_number,
 336         char                            *function_name,
 337         char                            *module_name,
 338         u32                             component_id);
 339
 340 void
 341 acpi_ut_status_exit (
 342         u32                             line_number,
 343         char                            *function_name,
 344         char                            *module_name,
 345         u32                             component_id,
 346         acpi_status                     status);
 347
 348 void
 349 acpi_ut_value_exit (
 350         u32                             line_number,
 351         char                            *function_name,
 352         char                            *module_name,
 353         u32                             component_id,
 354         acpi_integer                    value);
 355
 356 void
 357 acpi_ut_ptr_exit (
 358         u32                             line_number,
 359         char                            *function_name,
 360         char                            *module_name,
 361         u32                             component_id,
 362         u8                              *ptr);
 363
 364 void
 365 acpi_ut_report_info (
 366         char                            *module_name,
 367         u32                             line_number,
 368         u32                             component_id);
 369
 370 void
 371 acpi_ut_report_error (
 372         char                            *module_name,
 373         u32                             line_number,
 374         u32                             component_id);
 375
 376 void
 377 acpi_ut_report_warning (
 378         char                            *module_name,
 379         u32                             line_number,
 380         u32                             component_id);
 381
 382 void
 383 acpi_ut_dump_buffer (
 384         u8                              *buffer,
 385         u32                             count,
 386         u32                             display,
 387         u32                             component_id);
 388
 389 void ACPI_INTERNAL_VAR_XFACE
 390 acpi_ut_debug_print (
 391         u32                             requested_debug_level,
 392         u32                             line_number,
 393         char                            *function_name,
 394         char                            *module_name,
 395         u32                             component_id,
 396         char                            *format,
 397         ...) ACPI_PRINTF_LIKE_FUNC;
 398
 399 void ACPI_INTERNAL_VAR_XFACE
 400 acpi_ut_debug_print_raw (
 401         u32                             requested_debug_level,
 402         u32                             line_number,
 403         char                            *function_name,
 404         char                            *module_name,
 405         u32                             component_id,
 406         char                            *format,
 407         ...) ACPI_PRINTF_LIKE_FUNC;
 408
 409
 410 /*
 411  * utdelete - Object deletion and reference counts
 412  */
 413 void
 414 acpi_ut_add_reference (
 415         union acpi_operand_object       *object);
 416
 417 void
 418 acpi_ut_remove_reference (
 419         union acpi_operand_object       *object);
 420
 421 void
 422 acpi_ut_delete_internal_package_object (
 423         union acpi_operand_object       *object);
 424
 425 void
 426 acpi_ut_delete_internal_simple_object (
 427         union acpi_operand_object       *object);
 428
 429 void
 430 acpi_ut_delete_internal_object_list (
 431         union acpi_operand_object       **obj_list);
 432
 433
 434 /*
 435  * uteval - object evaluation
 436  */
 437 acpi_status
 438 acpi_ut_osi_implementation (
 439         struct acpi_walk_state          *walk_state);
 440
 441 acpi_status
 442 acpi_ut_evaluate_object (
 443         struct acpi_namespace_node      *prefix_node,
 444         char                            *path,
 445         u32                             expected_return_btypes,
 446         union acpi_operand_object       **return_desc);
 447
 448 acpi_status
 449 acpi_ut_evaluate_numeric_object (
 450         char                            *object_name,
 451         struct acpi_namespace_node      *device_node,
 452         acpi_integer                    *address);
 453
 454 acpi_status
 455 acpi_ut_execute_HID (
 456         struct acpi_namespace_node      *device_node,
 457         struct acpi_device_id           *hid);
 458
 459 acpi_status
 460 acpi_ut_execute_CID (
 461         struct acpi_namespace_node      *device_node,
 462         struct acpi_compatible_id_list **return_cid_list);
 463
 464 acpi_status
 465 acpi_ut_execute_STA (
 466         struct acpi_namespace_node      *device_node,
 467         u32                             *status_flags);
 468
 469 acpi_status
 470 acpi_ut_execute_UID (
 471         struct acpi_namespace_node      *device_node,
 472         struct acpi_device_id           *uid);
 473
 474 acpi_status
 475 acpi_ut_execute_sxds (
 476         struct acpi_namespace_node      *device_node,
 477         u8                              *highest);
 478
 479
 480 /*
 481  * utobject - internal object create/delete/cache routines
 482  */
 483 union acpi_operand_object    *
 484 acpi_ut_create_internal_object_dbg (
 485         char                            *module_name,
 486         u32                             line_number,
 487         u32                             component_id,
 488         acpi_object_type                type);
 489
 490 void *
 491 acpi_ut_allocate_object_desc_dbg (
 492         char                            *module_name,
 493         u32                             line_number,
 494         u32                             component_id);
 495
 496 #define acpi_ut_create_internal_object(t) acpi_ut_create_internal_object_dbg (_acpi_module_name,__LINE__,_COMPONENT,t)
 497 #define acpi_ut_allocate_object_desc()  acpi_ut_allocate_object_desc_dbg (_acpi_module_name,__LINE__,_COMPONENT)
 498
 499 void
 500 acpi_ut_delete_object_desc (
 501         union acpi_operand_object       *object);
 502
 503 u8
 504 acpi_ut_valid_internal_object (
 505         void                            *object);
 506
 507 union acpi_operand_object *
 508 acpi_ut_create_buffer_object (
 509         acpi_size                       buffer_size);
 510
 511 union acpi_operand_object *
 512 acpi_ut_create_string_object (
 513         acpi_size                       string_size);
 514
 515 acpi_status
 516 acpi_ut_get_object_size(
 517         union acpi_operand_object       *obj,
 518         acpi_size                       *obj_length);
 519
 520
 521 /*
 522  * utstate - Generic state creation/cache routines
 523  */
 524 void
 525 acpi_ut_push_generic_state (
 526         union acpi_generic_state        **list_head,
 527         union acpi_generic_state        *state);
 528
 529 union acpi_generic_state *
 530 acpi_ut_pop_generic_state (
 531         union acpi_generic_state        **list_head);
 532
 533
 534 union acpi_generic_state *
 535 acpi_ut_create_generic_state (
 536         void);
 537
 538 struct acpi_thread_state *
 539 acpi_ut_create_thread_state (
 540         void);
 541
 542 union acpi_generic_state *
 543 acpi_ut_create_update_state (
 544         union acpi_operand_object       *object,
 545         u16                             action);
 546
 547 union acpi_generic_state *
 548 acpi_ut_create_pkg_state (
 549         void                            *internal_object,
 550         void                            *external_object,
 551         u16                             index);
 552
 553 acpi_status
 554 acpi_ut_create_update_state_and_push (
 555         union acpi_operand_object       *object,
 556         u16                             action,
 557         union acpi_generic_state        **state_list);
 558
 559 #ifdef  ACPI_FUTURE_USAGE
 560 acpi_status
 561 acpi_ut_create_pkg_state_and_push (
 562         void                            *internal_object,
 563         void                            *external_object,
 564         u16                             index,
 565         union acpi_generic_state        **state_list);
 566 #endif  /* ACPI_FUTURE_USAGE */
 567
 568 union acpi_generic_state *
 569 acpi_ut_create_control_state (
 570         void);
 571
 572 void
 573 acpi_ut_delete_generic_state (
 574         union acpi_generic_state        *state);
 575
 576
 577 /*
 578  * utmath
 579  */
 580 acpi_status
 581 acpi_ut_divide (
 582         acpi_integer                    in_dividend,
 583         acpi_integer                    in_divisor,
 584         acpi_integer                    *out_quotient,
 585         acpi_integer                    *out_remainder);
 586
 587 acpi_status
 588 acpi_ut_short_divide (
 589         acpi_integer                    in_dividend,
 590         u32                             divisor,
 591         acpi_integer                    *out_quotient,
 592         u32                             *out_remainder);
 593
 594 /*
 595  * utmisc
 596  */
 597 acpi_status
 598 acpi_ut_allocate_owner_id (
 599         acpi_owner_id                   *owner_id);
 600
 601 acpi_status
 602 acpi_ut_release_owner_id (
 603         acpi_owner_id                   owner_id);
 604
 605 acpi_status
 606 acpi_ut_walk_package_tree (
 607         union acpi_operand_object       *source_object,
 608         void                            *target_object,
 609         acpi_pkg_callback               walk_callback,
 610         void                            *context);
 611
 612 char *
 613 acpi_ut_strupr (
 614         char                            *src_string);
 615
 616 void
 617 acpi_ut_print_string (
 618         char                            *string,
 619         u8                              max_length);
 620
 621 u8
 622 acpi_ut_valid_acpi_name (
 623         u32                             name);
 624
 625 u8
 626 acpi_ut_valid_acpi_character (
 627         char                            character);
 628
 629 acpi_status
 630 acpi_ut_strtoul64 (
 631         char                            *string,
 632         u32                             base,
 633         acpi_integer                    *ret_integer);
 634
 635 /* Values for Base above (16=Hex, 10=Decimal) */
 636
 637 #define ACPI_ANY_BASE        0
 638
 639 u8 *
 640 acpi_ut_get_resource_end_tag (
 641         union acpi_operand_object       *obj_desc);
 642
 643 u8
 644 acpi_ut_generate_checksum (
 645         u8                              *buffer,
 646         u32                             length);
 647
 648 u32
 649 acpi_ut_dword_byte_swap (
 650         u32                             value);
 651
 652 void
 653 acpi_ut_set_integer_width (
 654         u8                              revision);
 655
 656 #ifdef ACPI_DEBUG_OUTPUT
 657 void
 658 acpi_ut_display_init_pathname (
 659         u8                              type,
 660         struct acpi_namespace_node      *obj_handle,
 661         char                            *path);
 662
 663 #endif
 664
 665
 666 /*
 667  * utmutex - mutex support
 668  */
 669 acpi_status
 670 acpi_ut_mutex_initialize (
 671         void);
 672
 673 void
 674 acpi_ut_mutex_terminate (
 675         void);
 676
 677 acpi_status
 678 acpi_ut_acquire_mutex (
 679         acpi_mutex_handle               mutex_id);
 680
 681 acpi_status
 682 acpi_ut_release_mutex (
 683         acpi_mutex_handle               mutex_id);
 684
 685
 686 /*
 687  * utalloc - memory allocation and object caching
 688  */
 689 acpi_status
 690 acpi_ut_create_caches (
 691         void);
 692
 693 acpi_status
 694 acpi_ut_delete_caches (
 695         void);
 696
 697 acpi_status
 698 acpi_ut_validate_buffer (
 699         struct acpi_buffer              *buffer);
 700
 701 acpi_status
 702 acpi_ut_initialize_buffer (
 703         struct acpi_buffer              *buffer,
 704         acpi_size                       required_length);
 705
 706 void *
 707 acpi_ut_allocate (
 708         acpi_size                       size,
 709         u32                             component,
 710         char                            *module,
 711         u32                             line);
 712
 713 void *
 714 acpi_ut_callocate (
 715         acpi_size                       size,
 716         u32                             component,
 717         char                            *module,
 718         u32                             line);
 719
 720 #ifdef ACPI_DBG_TRACK_ALLOCATIONS
 721 void *
 722 acpi_ut_allocate_and_track (
 723         acpi_size                       size,
 724         u32                             component,
 725         char                            *module,
 726         u32                             line);
 727
 728 void *
 729 acpi_ut_callocate_and_track (
 730         acpi_size                       size,
 731         u32                             component,
 732         char                            *module,
 733         u32                             line);
 734
 735 void
 736 acpi_ut_free_and_track (
 737         void                            *address,
 738         u32                             component,
 739         char                            *module,
 740         u32                             line);
 741
 742 #ifdef  ACPI_FUTURE_USAGE
 743 void
 744 acpi_ut_dump_allocation_info (
 745         void);
 746 #endif  /* ACPI_FUTURE_USAGE */
 747
 748 void
 749 acpi_ut_dump_allocations (
 750         u32                             component,
 751         char                            *module);
 752 #endif
 753
 754 #endif /* _ACUTILS_H */