acpi/acpica/acobject.h

0001 /* SPDX-License-Identifier: BSD-3-Clause OR GPL-2.0 */
0002 /******************************************************************************
0003  *
0004  * Name: acobject.h - Definition of union acpi_operand_object  (Internal object only)
0005  *
0006  * Copyright (C) 2000 - 2022, Intel Corp.
0007  *
0008  *****************************************************************************/
0009
0010 #ifndef _ACOBJECT_H
0011 #define _ACOBJECT_H
0012
0013 /* acpisrc:struct_defs -- for acpisrc conversion */
0014
0015 /*
0016  * The union acpi_operand_object is used to pass AML operands from the dispatcher
0017  * to the interpreter, and to keep track of the various handlers such as
0018  * address space handlers and notify handlers. The object is a constant
0019  * size in order to allow it to be cached and reused.
0020  *
0021  * Note: The object is optimized to be aligned and will not work if it is
0022  * byte-packed.
0023  */
0024 #if ACPI_MACHINE_WIDTH == 64
0025 #pragma pack(8)
0026 #else
0027 #pragma pack(4)
0028 #endif
0029
0030 /*******************************************************************************
0031  *
0032  * Common Descriptors
0033  *
0034  ******************************************************************************/
0035
0036 /*
0037  * Common area for all objects.
0038  *
0039  * descriptor_type is used to differentiate between internal descriptors, and
0040  * must be in the same place across all descriptors
0041  *
0042  * Note: The descriptor_type and Type fields must appear in the identical
0043  * position in both the struct acpi_namespace_node and union acpi_operand_object
0044  * structures.
0045  */
0046 #define ACPI_OBJECT_COMMON_HEADER \
0047     union acpi_operand_object       *next_object;       /* Objects linked to parent NS node */\
0048     u8                              descriptor_type;    /* To differentiate various internal objs */\
0049     u8                              type;               /* acpi_object_type */\
0050     u16                             reference_count;    /* For object deletion management */\
0051     u8                              flags;
0052     /*
0053      * Note: There are 3 bytes available here before the
0054      * next natural alignment boundary (for both 32/64 cases)
0055      */
0056
0057 /* Values for Flag byte above */
0058
0059 #define AOPOBJ_AML_CONSTANT         0x01    /* Integer is an AML constant */
0060 #define AOPOBJ_STATIC_POINTER       0x02    /* Data is part of an ACPI table, don't delete */
0061 #define AOPOBJ_DATA_VALID           0x04    /* Object is initialized and data is valid */
0062 #define AOPOBJ_OBJECT_INITIALIZED   0x08    /* Region is initialized */
0063 #define AOPOBJ_REG_CONNECTED        0x10    /* _REG was run */
0064 #define AOPOBJ_SETUP_COMPLETE       0x20    /* Region setup is complete */
0065 #define AOPOBJ_INVALID              0x40    /* Host OS won't allow a Region address */
0066
0067 /******************************************************************************
0068  *
0069  * Basic data types
0070  *
0071  *****************************************************************************/
0072
0073 struct acpi_object_common {
0074 ACPI_OBJECT_COMMON_HEADER};
0075
0076 struct acpi_object_integer {
0077     ACPI_OBJECT_COMMON_HEADER u8 fill[3];   /* Prevent warning on some compilers */
0078     u64 value;
0079 };
0080
0081 /*
0082  * Note: The String and Buffer object must be identical through the
0083  * pointer and length elements. There is code that depends on this.
0084  *
0085  * Fields common to both Strings and Buffers
0086  */
0087 #define ACPI_COMMON_BUFFER_INFO(_type) \
0088     _type                           *pointer; \
0089     u32                             length;
0090
0091 /* Null terminated, ASCII characters only */
0092
0093 struct acpi_object_string {
0094     ACPI_OBJECT_COMMON_HEADER ACPI_COMMON_BUFFER_INFO(char) /* String in AML stream or allocated string */
0095 };
0096
0097 struct acpi_object_buffer {
0098     ACPI_OBJECT_COMMON_HEADER ACPI_COMMON_BUFFER_INFO(u8)   /* Buffer in AML stream or allocated buffer */
0099     u32 aml_length;
0100     u8 *aml_start;
0101     struct acpi_namespace_node *node;   /* Link back to parent node */
0102 };
0103
0104 struct acpi_object_package {
0105     ACPI_OBJECT_COMMON_HEADER struct acpi_namespace_node *node; /* Link back to parent node */
0106     union acpi_operand_object **elements;   /* Array of pointers to acpi_objects */
0107     u8 *aml_start;
0108     u32 aml_length;
0109     u32 count;      /* # of elements in package */
0110 };
0111
0112 /******************************************************************************
0113  *
0114  * Complex data types
0115  *
0116  *****************************************************************************/
0117
0118 struct acpi_object_event {
0119     ACPI_OBJECT_COMMON_HEADER acpi_semaphore os_semaphore;  /* Actual OS synchronization object */
0120 };
0121
0122 struct acpi_object_mutex {
0123     ACPI_OBJECT_COMMON_HEADER u8 sync_level;    /* 0-15, specified in Mutex() call */
0124     u16 acquisition_depth;  /* Allow multiple Acquires, same thread */
0125     acpi_mutex os_mutex;    /* Actual OS synchronization object */
0126     acpi_thread_id thread_id;   /* Current owner of the mutex */
0127     struct acpi_thread_state *owner_thread; /* Current owner of the mutex */
0128     union acpi_operand_object *prev;    /* Link for list of acquired mutexes */
0129     union acpi_operand_object *next;    /* Link for list of acquired mutexes */
0130     struct acpi_namespace_node *node;   /* Containing namespace node */
0131     u8 original_sync_level; /* Owner's original sync level (0-15) */
0132 };
0133
0134 struct acpi_object_region {
0135     ACPI_OBJECT_COMMON_HEADER u8 space_id;
0136     struct acpi_namespace_node *node;   /* Containing namespace node */
0137     union acpi_operand_object *handler; /* Handler for region access */
0138     union acpi_operand_object *next;
0139     acpi_physical_address address;
0140     u32 length;
0141     void *pointer;      /* Only for data table regions */
0142 };
0143
0144 struct acpi_object_method {
0145     ACPI_OBJECT_COMMON_HEADER u8 info_flags;
0146     u8 param_count;
0147     u8 sync_level;
0148     union acpi_operand_object *mutex;
0149     union acpi_operand_object *node;
0150     u8 *aml_start;
0151     union {
0152         acpi_internal_method implementation;
0153         union acpi_operand_object *handler;
0154     } dispatch;
0155
0156     u32 aml_length;
0157     acpi_owner_id owner_id;
0158     u8 thread_count;
0159 };
0160
0161 /* Flags for info_flags field above */
0162
0163 #define ACPI_METHOD_MODULE_LEVEL        0x01    /* Method is actually module-level code */
0164 #define ACPI_METHOD_INTERNAL_ONLY       0x02    /* Method is implemented internally (_OSI) */
0165 #define ACPI_METHOD_SERIALIZED          0x04    /* Method is serialized */
0166 #define ACPI_METHOD_SERIALIZED_PENDING  0x08    /* Method is to be marked serialized */
0167 #define ACPI_METHOD_IGNORE_SYNC_LEVEL   0x10    /* Method was auto-serialized at table load time */
0168 #define ACPI_METHOD_MODIFIED_NAMESPACE  0x20    /* Method modified the namespace */
0169
0170 /******************************************************************************
0171  *
0172  * Objects that can be notified. All share a common notify_info area.
0173  *
0174  *****************************************************************************/
0175
0176 /*
0177  * Common fields for objects that support ASL notifications
0178  */
0179 #define ACPI_COMMON_NOTIFY_INFO \
0180     union acpi_operand_object       *notify_list[2];    /* Handlers for system/device notifies */\
0181     union acpi_operand_object       *handler;   /* Handler for Address space */
0182
0183 /* COMMON NOTIFY for POWER, PROCESSOR, DEVICE, and THERMAL */
0184
0185 struct acpi_object_notify_common {
0186 ACPI_OBJECT_COMMON_HEADER ACPI_COMMON_NOTIFY_INFO};
0187
0188 struct acpi_object_device {
0189     ACPI_OBJECT_COMMON_HEADER
0190         ACPI_COMMON_NOTIFY_INFO struct acpi_gpe_block_info *gpe_block;
0191 };
0192
0193 struct acpi_object_power_resource {
0194     ACPI_OBJECT_COMMON_HEADER ACPI_COMMON_NOTIFY_INFO u32 system_level;
0195     u32 resource_order;
0196 };
0197
0198 struct acpi_object_processor {
0199     ACPI_OBJECT_COMMON_HEADER
0200         /* The next two fields take advantage of the 3-byte space before NOTIFY_INFO */
0201     u8 proc_id;
0202     u8 length;
0203     ACPI_COMMON_NOTIFY_INFO acpi_io_address address;
0204 };
0205
0206 struct acpi_object_thermal_zone {
0207 ACPI_OBJECT_COMMON_HEADER ACPI_COMMON_NOTIFY_INFO};
0208
0209 /******************************************************************************
0210  *
0211  * Fields. All share a common header/info field.
0212  *
0213  *****************************************************************************/
0214
0215 /*
0216  * Common bitfield for the field objects
0217  * "Field Datum"  -- a datum from the actual field object
0218  * "Buffer Datum" -- a datum from a user buffer, read from or to be written to the field
0219  */
0220 #define ACPI_COMMON_FIELD_INFO \
0221     u8                              field_flags;        /* Access, update, and lock bits */\
0222     u8                              attribute;          /* From access_as keyword */\
0223     u8                              access_byte_width;  /* Read/Write size in bytes */\
0224     struct acpi_namespace_node      *node;              /* Link back to parent node */\
0225     u32                             bit_length;         /* Length of field in bits */\
0226     u32                             base_byte_offset;   /* Byte offset within containing object */\
0227     u32                             value;              /* Value to store into the Bank or Index register */\
0228     u8                              start_field_bit_offset;/* Bit offset within first field datum (0-63) */\
0229     u8                              access_length;  /* For serial regions/fields */
0230
0231
0232 /* COMMON FIELD (for BUFFER, REGION, BANK, and INDEX fields) */
0233
0234 struct acpi_object_field_common {
0235     ACPI_OBJECT_COMMON_HEADER ACPI_COMMON_FIELD_INFO union acpi_operand_object *region_obj; /* Parent Operation Region object (REGION/BANK fields only) */
0236 };
0237
0238 struct acpi_object_region_field {
0239     ACPI_OBJECT_COMMON_HEADER ACPI_COMMON_FIELD_INFO u16 resource_length;
0240     union acpi_operand_object *region_obj;  /* Containing op_region object */
0241     u8 *resource_buffer;    /* resource_template for serial regions/fields */
0242     u16 pin_number_index;   /* Index relative to previous Connection/Template */
0243     u8 *internal_pcc_buffer;    /* Internal buffer for fields associated with PCC */
0244 };
0245
0246 struct acpi_object_bank_field {
0247     ACPI_OBJECT_COMMON_HEADER ACPI_COMMON_FIELD_INFO union acpi_operand_object *region_obj; /* Containing op_region object */
0248     union acpi_operand_object *bank_obj;    /* bank_select Register object */
0249 };
0250
0251 struct acpi_object_index_field {
0252     ACPI_OBJECT_COMMON_HEADER ACPI_COMMON_FIELD_INFO
0253         /*
0254          * No "RegionObj" pointer needed since the Index and Data registers
0255          * are each field definitions unto themselves.
0256          */
0257     union acpi_operand_object *index_obj;   /* Index register */
0258     union acpi_operand_object *data_obj;    /* Data register */
0259 };
0260
0261 /* The buffer_field is different in that it is part of a Buffer, not an op_region */
0262
0263 struct acpi_object_buffer_field {
0264     ACPI_OBJECT_COMMON_HEADER ACPI_COMMON_FIELD_INFO u8 is_create_field;    /* Special case for objects created by create_field() */
0265     union acpi_operand_object *buffer_obj;  /* Containing Buffer object */
0266 };
0267
0268 /******************************************************************************
0269  *
0270  * Objects for handlers
0271  *
0272  *****************************************************************************/
0273
0274 struct acpi_object_notify_handler {
0275     ACPI_OBJECT_COMMON_HEADER struct acpi_namespace_node *node; /* Parent device */
0276     u32 handler_type;   /* Type: Device/System/Both */
0277     acpi_notify_handler handler;    /* Handler address */
0278     void *context;
0279     union acpi_operand_object *next[2]; /* Device and System handler lists */
0280 };
0281
0282 struct acpi_object_addr_handler {
0283     ACPI_OBJECT_COMMON_HEADER u8 space_id;
0284     u8 handler_flags;
0285     acpi_adr_space_handler handler;
0286     struct acpi_namespace_node *node;   /* Parent device */
0287     void *context;
0288     acpi_mutex context_mutex;
0289     acpi_adr_space_setup setup;
0290     union acpi_operand_object *region_list; /* Regions using this handler */
0291     union acpi_operand_object *next;
0292 };
0293
0294 /* Flags for address handler (handler_flags) */
0295
0296 #define ACPI_ADDR_HANDLER_DEFAULT_INSTALLED  0x01
0297
0298 /******************************************************************************
0299  *
0300  * Special internal objects
0301  *
0302  *****************************************************************************/
0303
0304 /*
0305  * The Reference object is used for these opcodes:
0306  * Arg[0-6], Local[0-7], index_op, name_op, ref_of_op, load_op, load_table_op, debug_op
0307  * The Reference.Class differentiates these types.
0308  */
0309 struct acpi_object_reference {
0310     ACPI_OBJECT_COMMON_HEADER u8 class; /* Reference Class */
0311     u8 target_type;     /* Used for Index Op */
0312     u8 resolved;        /* Reference has been resolved to a value */
0313     void *object;       /* name_op=>HANDLE to obj, index_op=>union acpi_operand_object */
0314     struct acpi_namespace_node *node;   /* ref_of or Namepath */
0315     union acpi_operand_object **where;  /* Target of Index */
0316     u8 *index_pointer;  /* Used for Buffers and Strings */
0317     u8 *aml;        /* Used for deferred resolution of the ref */
0318     u32 value;      /* Used for Local/Arg/Index/ddb_handle */
0319 };
0320
0321 /* Values for Reference.Class above */
0322
0323 typedef enum {
0324     ACPI_REFCLASS_LOCAL = 0,    /* Method local */
0325     ACPI_REFCLASS_ARG = 1,  /* Method argument */
0326     ACPI_REFCLASS_REFOF = 2,    /* Result of ref_of() TBD: Split to Ref/Node and Ref/operand_obj? */
0327     ACPI_REFCLASS_INDEX = 3,    /* Result of Index() */
0328     ACPI_REFCLASS_TABLE = 4,    /* ddb_handle - Load(), load_table() */
0329     ACPI_REFCLASS_NAME = 5, /* Reference to a named object */
0330     ACPI_REFCLASS_DEBUG = 6,    /* Debug object */
0331
0332     ACPI_REFCLASS_MAX = 6
0333 } ACPI_REFERENCE_CLASSES;
0334
0335 /*
0336  * Extra object is used as additional storage for types that
0337  * have AML code in their declarations (term_args) that must be
0338  * evaluated at run time.
0339  *
0340  * Currently: Region and field_unit types
0341  */
0342 struct acpi_object_extra {
0343     ACPI_OBJECT_COMMON_HEADER struct acpi_namespace_node *method_REG;   /* _REG method for this region (if any) */
0344     struct acpi_namespace_node *scope_node;
0345     void *region_context;   /* Region-specific data */
0346     u8 *aml_start;
0347     u32 aml_length;
0348 };
0349
0350 /* Additional data that can be attached to namespace nodes */
0351
0352 struct acpi_object_data {
0353     ACPI_OBJECT_COMMON_HEADER acpi_object_handler handler;
0354     void *pointer;
0355 };
0356
0357 /* Structure used when objects are cached for reuse */
0358
0359 struct acpi_object_cache_list {
0360     ACPI_OBJECT_COMMON_HEADER union acpi_operand_object *next;  /* Link for object cache and internal lists */
0361 };
0362
0363 /******************************************************************************
0364  *
0365  * union acpi_operand_object descriptor - a giant union of all of the above
0366  *
0367  *****************************************************************************/
0368
0369 union acpi_operand_object {
0370     struct acpi_object_common common;
0371     struct acpi_object_integer integer;
0372     struct acpi_object_string string;
0373     struct acpi_object_buffer buffer;
0374     struct acpi_object_package package;
0375     struct acpi_object_event event;
0376     struct acpi_object_method method;
0377     struct acpi_object_mutex mutex;
0378     struct acpi_object_region region;
0379     struct acpi_object_notify_common common_notify;
0380     struct acpi_object_device device;
0381     struct acpi_object_power_resource power_resource;
0382     struct acpi_object_processor processor;
0383     struct acpi_object_thermal_zone thermal_zone;
0384     struct acpi_object_field_common common_field;
0385     struct acpi_object_region_field field;
0386     struct acpi_object_buffer_field buffer_field;
0387     struct acpi_object_bank_field bank_field;
0388     struct acpi_object_index_field index_field;
0389     struct acpi_object_notify_handler notify;
0390     struct acpi_object_addr_handler address_space;
0391     struct acpi_object_reference reference;
0392     struct acpi_object_extra extra;
0393     struct acpi_object_data data;
0394     struct acpi_object_cache_list cache;
0395
0396     /*
0397      * Add namespace node to union in order to simplify code that accepts both
0398      * ACPI_OPERAND_OBJECTs and ACPI_NAMESPACE_NODEs. The structures share
0399      * a common descriptor_type field in order to differentiate them.
0400      */
0401     struct acpi_namespace_node node;
0402 };
0403
0404 /******************************************************************************
0405  *
0406  * union acpi_descriptor - objects that share a common descriptor identifier
0407  *
0408  *****************************************************************************/
0409
0410 /* Object descriptor types */
0411
0412 #define ACPI_DESC_TYPE_CACHED           0x01    /* Used only when object is cached */
0413 #define ACPI_DESC_TYPE_STATE            0x02
0414 #define ACPI_DESC_TYPE_STATE_UPDATE     0x03
0415 #define ACPI_DESC_TYPE_STATE_PACKAGE    0x04
0416 #define ACPI_DESC_TYPE_STATE_CONTROL    0x05
0417 #define ACPI_DESC_TYPE_STATE_RPSCOPE    0x06
0418 #define ACPI_DESC_TYPE_STATE_PSCOPE     0x07
0419 #define ACPI_DESC_TYPE_STATE_WSCOPE     0x08
0420 #define ACPI_DESC_TYPE_STATE_RESULT     0x09
0421 #define ACPI_DESC_TYPE_STATE_NOTIFY     0x0A
0422 #define ACPI_DESC_TYPE_STATE_THREAD     0x0B
0423 #define ACPI_DESC_TYPE_WALK             0x0C
0424 #define ACPI_DESC_TYPE_PARSER           0x0D
0425 #define ACPI_DESC_TYPE_OPERAND          0x0E
0426 #define ACPI_DESC_TYPE_NAMED            0x0F
0427 #define ACPI_DESC_TYPE_MAX              0x0F
0428
0429 struct acpi_common_descriptor {
0430     void *common_pointer;
0431     u8 descriptor_type; /* To differentiate various internal objs */
0432 };
0433
0434 union acpi_descriptor {
0435     struct acpi_common_descriptor common;
0436     union acpi_operand_object object;
0437     struct acpi_namespace_node node;
0438     union acpi_parse_object op;
0439 };
0440
0441 #pragma pack()
0442
0443 #endif              /* _ACOBJECT_H */