1 /******************************************************************************
3 * Module Name: utobject - ACPI object create/delete/size/cache routines
5 *****************************************************************************/
8 * Copyright (C) 2000 - 2005, R. Byron Moore
11 * Redistribution and use in source and binary forms, with or without
12 * modification, are permitted provided that the following conditions
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.
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.
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.
45 #include <acpi/acpi.h>
46 #include <acpi/acnamesp.h>
47 #include <acpi/amlcode.h>
50 #define _COMPONENT ACPI_UTILITIES
51 ACPI_MODULE_NAME ("utobject")
53 /* Local prototypes */
56 acpi_ut_get_simple_object_size (
57 union acpi_operand_object
*obj
,
58 acpi_size
*obj_length
);
61 acpi_ut_get_package_object_size (
62 union acpi_operand_object
*obj
,
63 acpi_size
*obj_length
);
66 acpi_ut_get_element_length (
68 union acpi_operand_object
*source_object
,
69 union acpi_generic_state
*state
,
73 /*******************************************************************************
75 * FUNCTION: acpi_ut_create_internal_object_dbg
77 * PARAMETERS: module_name - Source file name of caller
78 * line_number - Line number of caller
79 * component_id - Component type of caller
80 * Type - ACPI Type of the new object
82 * RETURN: A new internal object, null on failure
84 * DESCRIPTION: Create and initialize a new internal object.
86 * NOTE: We always allocate the worst-case object descriptor because
87 * these objects are cached, and we want them to be
88 * one-size-satisifies-any-request. This in itself may not be
89 * the most memory efficient, but the efficiency of the object
90 * cache should more than make up for this!
92 ******************************************************************************/
94 union acpi_operand_object
*
95 acpi_ut_create_internal_object_dbg (
99 acpi_object_type type
)
101 union acpi_operand_object
*object
;
102 union acpi_operand_object
*second_object
;
105 ACPI_FUNCTION_TRACE_STR ("ut_create_internal_object_dbg",
106 acpi_ut_get_type_name (type
));
109 /* Allocate the raw object descriptor */
111 object
= acpi_ut_allocate_object_desc_dbg (module_name
, line_number
, component_id
);
117 case ACPI_TYPE_REGION
:
118 case ACPI_TYPE_BUFFER_FIELD
:
120 /* These types require a secondary object */
122 second_object
= acpi_ut_allocate_object_desc_dbg (module_name
,
123 line_number
, component_id
);
124 if (!second_object
) {
125 acpi_ut_delete_object_desc (object
);
129 second_object
->common
.type
= ACPI_TYPE_LOCAL_EXTRA
;
130 second_object
->common
.reference_count
= 1;
132 /* Link the second object to the first */
134 object
->common
.next_object
= second_object
;
138 /* All others have no secondary object */
142 /* Save the object type in the object descriptor */
144 object
->common
.type
= (u8
) type
;
146 /* Init the reference count */
148 object
->common
.reference_count
= 1;
150 /* Any per-type initialization should go here */
156 /*******************************************************************************
158 * FUNCTION: acpi_ut_create_buffer_object
160 * PARAMETERS: buffer_size - Size of buffer to be created
162 * RETURN: Pointer to a new Buffer object, null on failure
164 * DESCRIPTION: Create a fully initialized buffer object
166 ******************************************************************************/
168 union acpi_operand_object
*
169 acpi_ut_create_buffer_object (
170 acpi_size buffer_size
)
172 union acpi_operand_object
*buffer_desc
;
176 ACPI_FUNCTION_TRACE_U32 ("ut_create_buffer_object", buffer_size
);
179 /* Create a new Buffer object */
181 buffer_desc
= acpi_ut_create_internal_object (ACPI_TYPE_BUFFER
);
186 /* Create an actual buffer only if size > 0 */
188 if (buffer_size
> 0) {
189 /* Allocate the actual buffer */
191 buffer
= ACPI_MEM_CALLOCATE (buffer_size
);
193 ACPI_REPORT_ERROR (("create_buffer: could not allocate size %X\n",
195 acpi_ut_remove_reference (buffer_desc
);
200 /* Complete buffer object initialization */
202 buffer_desc
->buffer
.flags
|= AOPOBJ_DATA_VALID
;
203 buffer_desc
->buffer
.pointer
= buffer
;
204 buffer_desc
->buffer
.length
= (u32
) buffer_size
;
206 /* Return the new buffer descriptor */
208 return_PTR (buffer_desc
);
212 /*******************************************************************************
214 * FUNCTION: acpi_ut_create_string_object
216 * PARAMETERS: string_size - Size of string to be created. Does not
217 * include NULL terminator, this is added
220 * RETURN: Pointer to a new String object
222 * DESCRIPTION: Create a fully initialized string object
224 ******************************************************************************/
226 union acpi_operand_object
*
227 acpi_ut_create_string_object (
228 acpi_size string_size
)
230 union acpi_operand_object
*string_desc
;
234 ACPI_FUNCTION_TRACE_U32 ("ut_create_string_object", string_size
);
237 /* Create a new String object */
239 string_desc
= acpi_ut_create_internal_object (ACPI_TYPE_STRING
);
245 * Allocate the actual string buffer -- (Size + 1) for NULL terminator.
246 * NOTE: Zero-length strings are NULL terminated
248 string
= ACPI_MEM_CALLOCATE (string_size
+ 1);
250 ACPI_REPORT_ERROR (("create_string: could not allocate size %X\n",
252 acpi_ut_remove_reference (string_desc
);
256 /* Complete string object initialization */
258 string_desc
->string
.pointer
= string
;
259 string_desc
->string
.length
= (u32
) string_size
;
261 /* Return the new string descriptor */
263 return_PTR (string_desc
);
267 /*******************************************************************************
269 * FUNCTION: acpi_ut_valid_internal_object
271 * PARAMETERS: Object - Object to be validated
273 * RETURN: TRUE if object is valid, FALSE otherwise
275 * DESCRIPTION: Validate a pointer to be an union acpi_operand_object
277 ******************************************************************************/
280 acpi_ut_valid_internal_object (
284 ACPI_FUNCTION_NAME ("ut_valid_internal_object");
287 /* Check for a null pointer */
290 ACPI_DEBUG_PRINT ((ACPI_DB_INFO
, "**** Null Object Ptr\n"));
294 /* Check the descriptor type field */
296 switch (ACPI_GET_DESCRIPTOR_TYPE (object
)) {
297 case ACPI_DESC_TYPE_OPERAND
:
299 /* The object appears to be a valid union acpi_operand_object */
304 ACPI_DEBUG_PRINT ((ACPI_DB_INFO
,
305 "%p is not not an ACPI operand obj [%s]\n",
306 object
, acpi_ut_get_descriptor_name (object
)));
314 /*******************************************************************************
316 * FUNCTION: acpi_ut_allocate_object_desc_dbg
318 * PARAMETERS: module_name - Caller's module name (for error output)
319 * line_number - Caller's line number (for error output)
320 * component_id - Caller's component ID (for error output)
322 * RETURN: Pointer to newly allocated object descriptor. Null on error
324 * DESCRIPTION: Allocate a new object descriptor. Gracefully handle
327 ******************************************************************************/
330 acpi_ut_allocate_object_desc_dbg (
335 union acpi_operand_object
*object
;
338 ACPI_FUNCTION_TRACE ("ut_allocate_object_desc_dbg");
341 object
= acpi_ut_acquire_from_cache (ACPI_MEM_LIST_OPERAND
);
343 _ACPI_REPORT_ERROR (module_name
, line_number
, component_id
,
344 ("Could not allocate an object descriptor\n"));
349 /* Mark the descriptor type */
351 ACPI_SET_DESCRIPTOR_TYPE (object
, ACPI_DESC_TYPE_OPERAND
);
353 ACPI_DEBUG_PRINT ((ACPI_DB_ALLOCATIONS
, "%p Size %X\n",
354 object
, (u32
) sizeof (union acpi_operand_object
)));
360 /*******************************************************************************
362 * FUNCTION: acpi_ut_delete_object_desc
364 * PARAMETERS: Object - An Acpi internal object to be deleted
368 * DESCRIPTION: Free an ACPI object descriptor or add it to the object cache
370 ******************************************************************************/
373 acpi_ut_delete_object_desc (
374 union acpi_operand_object
*object
)
376 ACPI_FUNCTION_TRACE_PTR ("ut_delete_object_desc", object
);
379 /* Object must be an union acpi_operand_object */
381 if (ACPI_GET_DESCRIPTOR_TYPE (object
) != ACPI_DESC_TYPE_OPERAND
) {
382 ACPI_DEBUG_PRINT ((ACPI_DB_ERROR
,
383 "%p is not an ACPI Operand object [%s]\n", object
,
384 acpi_ut_get_descriptor_name (object
)));
388 acpi_ut_release_to_cache (ACPI_MEM_LIST_OPERAND
, object
);
394 #ifdef ACPI_ENABLE_OBJECT_CACHE
395 /*******************************************************************************
397 * FUNCTION: acpi_ut_delete_object_cache
403 * DESCRIPTION: Purge the global state object cache. Used during subsystem
406 ******************************************************************************/
409 acpi_ut_delete_object_cache (
412 ACPI_FUNCTION_TRACE ("ut_delete_object_cache");
415 acpi_ut_delete_generic_cache (ACPI_MEM_LIST_OPERAND
);
421 /*******************************************************************************
423 * FUNCTION: acpi_ut_get_simple_object_size
425 * PARAMETERS: internal_object - An ACPI operand object
426 * obj_length - Where the length is returned
430 * DESCRIPTION: This function is called to determine the space required to
431 * contain a simple object for return to an external user.
433 * The length includes the object structure plus any additional
436 ******************************************************************************/
439 acpi_ut_get_simple_object_size (
440 union acpi_operand_object
*internal_object
,
441 acpi_size
*obj_length
)
444 acpi_status status
= AE_OK
;
447 ACPI_FUNCTION_TRACE_PTR ("ut_get_simple_object_size", internal_object
);
451 * Handle a null object (Could be a uninitialized package
452 * element -- which is legal)
454 if (!internal_object
) {
456 return_ACPI_STATUS (AE_OK
);
459 /* Start with the length of the Acpi object */
461 length
= sizeof (union acpi_object
);
463 if (ACPI_GET_DESCRIPTOR_TYPE (internal_object
) == ACPI_DESC_TYPE_NAMED
) {
464 /* Object is a named object (reference), just return the length */
466 *obj_length
= ACPI_ROUND_UP_TO_NATIVE_WORD (length
);
467 return_ACPI_STATUS (status
);
471 * The final length depends on the object type
472 * Strings and Buffers are packed right up against the parent object and
473 * must be accessed bytewise or there may be alignment problems on
476 switch (ACPI_GET_OBJECT_TYPE (internal_object
)) {
477 case ACPI_TYPE_STRING
:
479 length
+= (acpi_size
) internal_object
->string
.length
+ 1;
483 case ACPI_TYPE_BUFFER
:
485 length
+= (acpi_size
) internal_object
->buffer
.length
;
489 case ACPI_TYPE_INTEGER
:
490 case ACPI_TYPE_PROCESSOR
:
491 case ACPI_TYPE_POWER
:
494 * No extra data for these types
499 case ACPI_TYPE_LOCAL_REFERENCE
:
501 switch (internal_object
->reference
.opcode
) {
502 case AML_INT_NAMEPATH_OP
:
505 * Get the actual length of the full pathname to this object.
506 * The reference will be converted to the pathname to the object
508 length
+= ACPI_ROUND_UP_TO_NATIVE_WORD (
509 acpi_ns_get_pathname_length (internal_object
->reference
.node
));
515 * No other reference opcodes are supported.
516 * Notably, Locals and Args are not supported, but this may be
517 * required eventually.
519 ACPI_DEBUG_PRINT ((ACPI_DB_ERROR
,
520 "Unsupported Reference opcode=%X in object %p\n",
521 internal_object
->reference
.opcode
, internal_object
));
530 ACPI_DEBUG_PRINT ((ACPI_DB_ERROR
, "Unsupported type=%X in object %p\n",
531 ACPI_GET_OBJECT_TYPE (internal_object
), internal_object
));
537 * Account for the space required by the object rounded up to the next
538 * multiple of the machine word size. This keeps each object aligned
539 * on a machine word boundary. (preventing alignment faults on some
542 *obj_length
= ACPI_ROUND_UP_TO_NATIVE_WORD (length
);
543 return_ACPI_STATUS (status
);
547 /*******************************************************************************
549 * FUNCTION: acpi_ut_get_element_length
551 * PARAMETERS: acpi_pkg_callback
555 * DESCRIPTION: Get the length of one package element.
557 ******************************************************************************/
560 acpi_ut_get_element_length (
562 union acpi_operand_object
*source_object
,
563 union acpi_generic_state
*state
,
566 acpi_status status
= AE_OK
;
567 struct acpi_pkg_info
*info
= (struct acpi_pkg_info
*) context
;
568 acpi_size object_space
;
571 switch (object_type
) {
572 case ACPI_COPY_TYPE_SIMPLE
:
575 * Simple object - just get the size (Null object/entry is handled
576 * here also) and sum it into the running package length
578 status
= acpi_ut_get_simple_object_size (source_object
, &object_space
);
579 if (ACPI_FAILURE (status
)) {
583 info
->length
+= object_space
;
587 case ACPI_COPY_TYPE_PACKAGE
:
589 /* Package object - nothing much to do here, let the walk handle it */
591 info
->num_packages
++;
592 state
->pkg
.this_target_obj
= NULL
;
598 /* No other types allowed */
600 return (AE_BAD_PARAMETER
);
607 /*******************************************************************************
609 * FUNCTION: acpi_ut_get_package_object_size
611 * PARAMETERS: internal_object - An ACPI internal object
612 * obj_length - Where the length is returned
616 * DESCRIPTION: This function is called to determine the space required to
617 * contain a package object for return to an external user.
619 * This is moderately complex since a package contains other
620 * objects including packages.
622 ******************************************************************************/
625 acpi_ut_get_package_object_size (
626 union acpi_operand_object
*internal_object
,
627 acpi_size
*obj_length
)
630 struct acpi_pkg_info info
;
633 ACPI_FUNCTION_TRACE_PTR ("ut_get_package_object_size", internal_object
);
637 info
.object_space
= 0;
638 info
.num_packages
= 1;
640 status
= acpi_ut_walk_package_tree (internal_object
, NULL
,
641 acpi_ut_get_element_length
, &info
);
642 if (ACPI_FAILURE (status
)) {
643 return_ACPI_STATUS (status
);
647 * We have handled all of the objects in all levels of the package.
648 * just add the length of the package objects themselves.
649 * Round up to the next machine word.
651 info
.length
+= ACPI_ROUND_UP_TO_NATIVE_WORD (sizeof (union acpi_object
)) *
652 (acpi_size
) info
.num_packages
;
654 /* Return the total package length */
656 *obj_length
= info
.length
;
657 return_ACPI_STATUS (status
);
661 /*******************************************************************************
663 * FUNCTION: acpi_ut_get_object_size
665 * PARAMETERS: internal_object - An ACPI internal object
666 * obj_length - Where the length will be returned
670 * DESCRIPTION: This function is called to determine the space required to
671 * contain an object for return to an API user.
673 ******************************************************************************/
676 acpi_ut_get_object_size (
677 union acpi_operand_object
*internal_object
,
678 acpi_size
*obj_length
)
683 ACPI_FUNCTION_ENTRY ();
686 if ((ACPI_GET_DESCRIPTOR_TYPE (internal_object
) == ACPI_DESC_TYPE_OPERAND
) &&
687 (ACPI_GET_OBJECT_TYPE (internal_object
) == ACPI_TYPE_PACKAGE
)) {
688 status
= acpi_ut_get_package_object_size (internal_object
, obj_length
);
691 status
= acpi_ut_get_simple_object_size (internal_object
, obj_length
);