xref: /freebsd/sys/contrib/dev/acpica/compiler/asltree.c (revision cc426dd31990b8b50b210efc450e404596548ca1)
1 /******************************************************************************
2  *
3  * Module Name: asltree - Parse tree management
4  *
5  *****************************************************************************/
6 
7 /******************************************************************************
8  *
9  * 1. Copyright Notice
10  *
11  * Some or all of this work - Copyright (c) 1999 - 2018, 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  * Alternatively, you may choose to be licensed under the terms of the
117  * following license:
118  *
119  * Redistribution and use in source and binary forms, with or without
120  * modification, are permitted provided that the following conditions
121  * are met:
122  * 1. Redistributions of source code must retain the above copyright
123  *    notice, this list of conditions, and the following disclaimer,
124  *    without modification.
125  * 2. Redistributions in binary form must reproduce at minimum a disclaimer
126  *    substantially similar to the "NO WARRANTY" disclaimer below
127  *    ("Disclaimer") and any redistribution must be conditioned upon
128  *    including a substantially similar Disclaimer requirement for further
129  *    binary redistribution.
130  * 3. Neither the names of the above-listed copyright holders nor the names
131  *    of any contributors may be used to endorse or promote products derived
132  *    from this software without specific prior written permission.
133  *
134  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
135  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
136  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
137  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
138  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
139  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
140  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
141  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
142  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
143  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
144  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
145  *
146  * Alternatively, you may choose to be licensed under the terms of the
147  * GNU General Public License ("GPL") version 2 as published by the Free
148  * Software Foundation.
149  *
150  *****************************************************************************/
151 
152 #include <contrib/dev/acpica/compiler/aslcompiler.h>
153 #include "aslcompiler.y.h"
154 #include <contrib/dev/acpica/include/acapps.h>
155 
156 #define _COMPONENT          ACPI_COMPILER
157         ACPI_MODULE_NAME    ("asltree")
158 
159 
160 /*******************************************************************************
161  *
162  * FUNCTION:    TrSetOpIntegerValue
163  *
164  * PARAMETERS:  ParseOpcode         - New opcode to be assigned to the op
165  *              Op                  - An existing parse op
166  *
167  * RETURN:      The updated op
168  *
169  * DESCRIPTION: Used to set the integer value of a op,
170  *              usually to a specific size (8, 16, 32, or 64 bits)
171  *
172  ******************************************************************************/
173 
174 ACPI_PARSE_OBJECT *
175 TrSetOpIntegerValue (
176     UINT32                  ParseOpcode,
177     ACPI_PARSE_OBJECT       *Op)
178 {
179 
180     if (!Op)
181     {
182         return (NULL);
183     }
184 
185     DbgPrint (ASL_PARSE_OUTPUT,
186         "\nUpdateOp: Old - %s, New - %s\n",
187         UtGetOpName (Op->Asl.ParseOpcode),
188         UtGetOpName (ParseOpcode));
189 
190     /* Assign new opcode and name */
191 
192     if (Op->Asl.ParseOpcode == PARSEOP_ONES)
193     {
194         switch (ParseOpcode)
195         {
196         case PARSEOP_BYTECONST:
197 
198             Op->Asl.Value.Integer = ACPI_UINT8_MAX;
199             break;
200 
201         case PARSEOP_WORDCONST:
202 
203             Op->Asl.Value.Integer = ACPI_UINT16_MAX;
204             break;
205 
206         case PARSEOP_DWORDCONST:
207 
208             Op->Asl.Value.Integer = ACPI_UINT32_MAX;
209             break;
210 
211         /* Don't need to do the QWORD case */
212 
213         default:
214 
215             /* Don't care about others */
216             break;
217         }
218     }
219 
220     Op->Asl.ParseOpcode = (UINT16) ParseOpcode;
221     UtSetParseOpName (Op);
222 
223     /*
224      * For the BYTE, WORD, and DWORD constants, make sure that the integer
225      * that was passed in will actually fit into the data type
226      */
227     switch (ParseOpcode)
228     {
229     case PARSEOP_BYTECONST:
230 
231         UtCheckIntegerRange (Op, 0x00, ACPI_UINT8_MAX);
232         Op->Asl.Value.Integer &= ACPI_UINT8_MAX;
233         break;
234 
235     case PARSEOP_WORDCONST:
236 
237         UtCheckIntegerRange (Op, 0x00, ACPI_UINT16_MAX);
238         Op->Asl.Value.Integer &= ACPI_UINT16_MAX;
239         break;
240 
241     case PARSEOP_DWORDCONST:
242 
243         UtCheckIntegerRange (Op, 0x00, ACPI_UINT32_MAX);
244         Op->Asl.Value.Integer &= ACPI_UINT32_MAX;
245         break;
246 
247     default:
248 
249         /* Don't care about others, don't need to check QWORD */
250 
251         break;
252     }
253 
254     /* Converter: if this is a method invocation, turn off capture comments */
255 
256     if (AcpiGbl_CaptureComments &&
257         (ParseOpcode == PARSEOP_METHODCALL))
258     {
259         AslGbl_CommentState.CaptureComments = FALSE;
260     }
261 
262     return (Op);
263 }
264 
265 
266 /*******************************************************************************
267  *
268  * FUNCTION:    TrSetOpFlags
269  *
270  * PARAMETERS:  Op                  - An existing parse op
271  *              Flags               - New flags word
272  *
273  * RETURN:      The updated parser op
274  *
275  * DESCRIPTION: Set bits in the op flags word. Will not clear bits, only set
276  *
277  ******************************************************************************/
278 
279 ACPI_PARSE_OBJECT *
280 TrSetOpFlags (
281     ACPI_PARSE_OBJECT       *Op,
282     UINT32                  Flags)
283 {
284 
285     if (!Op)
286     {
287         return (NULL);
288     }
289 
290     DbgPrint (ASL_PARSE_OUTPUT,
291         "\nSetOpFlags: %s Op %p, %8.8X", Op->Asl.ParseOpName, Op, Flags);
292 
293     TrPrintOpFlags (Flags, ASL_PARSE_OUTPUT);
294     DbgPrint (ASL_PARSE_OUTPUT, "\n\n");
295 
296     Op->Asl.CompileFlags |= Flags;
297     return (Op);
298 }
299 
300 
301 /*******************************************************************************
302  *
303  * FUNCTION:    TrSetOpAmlLength
304  *
305  * PARAMETERS:  Op                  - An existing parse op
306  *              Length              - AML Length
307  *
308  * RETURN:      The updated parser op
309  *
310  * DESCRIPTION: Set the AML Length in a op. Used by the parser to indicate
311  *              the presence of a op that must be reduced to a fixed length
312  *              constant.
313  *
314  ******************************************************************************/
315 
316 ACPI_PARSE_OBJECT *
317 TrSetOpAmlLength (
318     ACPI_PARSE_OBJECT       *Op,
319     UINT32                  Length)
320 {
321 
322     DbgPrint (ASL_PARSE_OUTPUT,
323         "\nSetOpAmlLength: Op %p, %8.8X\n", Op, Length);
324 
325     if (!Op)
326     {
327         return (NULL);
328     }
329 
330     Op->Asl.AmlLength = Length;
331     return (Op);
332 }
333 
334 
335 /*******************************************************************************
336  *
337  * FUNCTION:    TrSetOpParent
338  *
339  * PARAMETERS:  Op                  - To be set to new parent
340  *              ParentOp            - The parent
341  *
342  * RETURN:      None, sets Op parent directly
343  *
344  * DESCRIPTION: Change the parent of a parse op.
345  *
346  ******************************************************************************/
347 
348 void
349 TrSetOpParent (
350     ACPI_PARSE_OBJECT       *Op,
351     ACPI_PARSE_OBJECT       *ParentOp)
352 {
353 
354     Op->Asl.Parent = ParentOp;
355 }
356 
357 
358 /*******************************************************************************
359  *
360  * FUNCTION:    TrSetOpCurrentFilename
361  *
362  * PARAMETERS:  Op                  - An existing parse op
363  *
364  * RETURN:      None
365  *
366  * DESCRIPTION: Save the include file filename. Used for debug output only.
367  *
368  ******************************************************************************/
369 
370 void
371 TrSetOpCurrentFilename (
372     ACPI_PARSE_OBJECT       *Op)
373 {
374 
375     Op->Asl.Filename = AslGbl_PreviousIncludeFilename;
376 }
377 
378 
379 /*******************************************************************************
380  *
381  * FUNCTION:    TrSetOpIntegerWidth
382  *
383  * PARAMETERS:  Op                  - An existing parse op
384  *
385  * RETURN:      None
386  *
387  * DESCRIPTION:
388  *
389  ******************************************************************************/
390 
391 void
392 TrSetOpIntegerWidth (
393     ACPI_PARSE_OBJECT       *TableSignatureOp,
394     ACPI_PARSE_OBJECT       *RevisionOp)
395 {
396 
397     /* TBD: Check table sig? (DSDT vs. SSDT) */
398 
399     /* Handle command-line version override */
400 
401     if (AslGbl_RevisionOverride)
402     {
403         AcpiUtSetIntegerWidth (AslGbl_RevisionOverride);
404     }
405     else
406     {
407         AcpiUtSetIntegerWidth ((UINT8) RevisionOp->Asl.Value.Integer);
408     }
409 }
410 
411 
412 /*******************************************************************************
413  *
414  * FUNCTION:    TrSetOpEndLineNumber
415  *
416  * PARAMETERS:  Op                - An existing parse op
417  *
418  * RETURN:      None.
419  *
420  * DESCRIPTION: Set the ending line numbers (file line and logical line) of a
421  *              parse op to the current line numbers.
422  *
423  ******************************************************************************/
424 
425 void
426 TrSetOpEndLineNumber (
427     ACPI_PARSE_OBJECT       *Op)
428 {
429 
430     /* If the end line # is already set, just return */
431 
432     if (Op->Asl.EndLine)
433     {
434         return;
435     }
436 
437     Op->Asl.EndLine = AslGbl_CurrentLineNumber;
438     Op->Asl.EndLogicalLine = AslGbl_LogicalLineNumber;
439 }
440 
441 
442 /*******************************************************************************
443  *
444  * FUNCTION:    TrLinkOpChildren
445  *
446  * PARAMETERS:  Op                - An existing parse op
447  *              NumChildren        - Number of children to follow
448  *              ...                - A list of child ops to link to the new
449  *                                   op. NumChildren long.
450  *
451  * RETURN:      The updated (linked) op
452  *
453  * DESCRIPTION: Link a group of ops to an existing parse op
454  *
455  ******************************************************************************/
456 
457 ACPI_PARSE_OBJECT *
458 TrLinkOpChildren (
459     ACPI_PARSE_OBJECT       *Op,
460     UINT32                  NumChildren,
461     ...)
462 {
463     ACPI_PARSE_OBJECT       *Child;
464     ACPI_PARSE_OBJECT       *PrevChild;
465     va_list                 ap;
466     UINT32                  i;
467     BOOLEAN                 FirstChild;
468 
469 
470     va_start (ap, NumChildren);
471 
472     TrSetOpEndLineNumber (Op);
473 
474     DbgPrint (ASL_PARSE_OUTPUT,
475         "\nLinkChildren  Line [%u to %u] NewParent %p Child %u Op %s  ",
476         Op->Asl.LineNumber, Op->Asl.EndLine,
477         Op, NumChildren, UtGetOpName(Op->Asl.ParseOpcode));
478 
479     switch (Op->Asl.ParseOpcode)
480     {
481     case PARSEOP_ASL_CODE:
482 
483         AslGbl_ParseTreeRoot = Op;
484         Op->Asl.ParseOpcode = PARSEOP_DEFAULT_ARG;
485         DbgPrint (ASL_PARSE_OUTPUT, "ASLCODE (Tree Completed)->");
486         break;
487 
488     case PARSEOP_DEFINITION_BLOCK:
489 
490         DbgPrint (ASL_PARSE_OUTPUT, "DEFINITION_BLOCK (Tree Completed)->");
491         break;
492 
493     case PARSEOP_OPERATIONREGION:
494 
495         DbgPrint (ASL_PARSE_OUTPUT, "OPREGION->");
496         break;
497 
498     case PARSEOP_OR:
499 
500         DbgPrint (ASL_PARSE_OUTPUT, "OR->");
501         break;
502 
503     default:
504 
505         /* Nothing to do for other opcodes */
506 
507         break;
508     }
509 
510     /* The following is for capturing comments */
511 
512     if (AcpiGbl_CaptureComments)
513     {
514         /*
515          * If there are "regular comments" detected at this point,
516          * then is an endBlk comment. Categorize it as so and distribute
517          * all regular comments to this parse op.
518          */
519         if (AslGbl_CommentListHead)
520         {
521             Op->Asl.EndBlkComment = AslGbl_CommentListHead;
522             CvDbgPrint ("EndBlk Comment for %s: %s",
523                 Op->Asl.ParseOpName, AslGbl_CommentListHead->Comment);
524             AslGbl_CommentListHead = NULL;
525             AslGbl_CommentListTail = NULL;
526         }
527     }
528 
529     /* Link the new op to it's children */
530 
531     PrevChild = NULL;
532     FirstChild = TRUE;
533     for (i = 0; i < NumChildren; i++)
534     {
535         Child = va_arg (ap, ACPI_PARSE_OBJECT *);
536 
537         if ((Child == PrevChild) && (Child != NULL))
538         {
539             AslError (ASL_WARNING, ASL_MSG_COMPILER_INTERNAL, Child,
540                 "Child op list invalid");
541             va_end(ap);
542             return (Op);
543         }
544 
545         DbgPrint (ASL_PARSE_OUTPUT, "%p, ", Child);
546 
547         /*
548          * If child is NULL, this means that an optional argument
549          * was omitted. We must create a placeholder with a special
550          * opcode (DEFAULT_ARG) so that the code generator will know
551          * that it must emit the correct default for this argument
552          */
553         if (!Child)
554         {
555             Child = TrAllocateOp (PARSEOP_DEFAULT_ARG);
556         }
557 
558         /* Link first child to parent */
559 
560         if (FirstChild)
561         {
562             FirstChild = FALSE;
563             Op->Asl.Child = Child;
564         }
565 
566         /* Point all children to parent */
567 
568         Child->Asl.Parent = Op;
569 
570         /* Link children in a peer list */
571 
572         if (PrevChild)
573         {
574             PrevChild->Asl.Next = Child;
575         }
576 
577         /*
578          * This child might be a list, point all ops in the list
579          * to the same parent
580          */
581         while (Child->Asl.Next)
582         {
583             Child = Child->Asl.Next;
584             Child->Asl.Parent = Op;
585         }
586 
587         PrevChild = Child;
588     }
589 
590     va_end(ap);
591     DbgPrint (ASL_PARSE_OUTPUT, "\n\n");
592 
593     if (AcpiGbl_CaptureComments)
594     {
595         AslGbl_CommentState.LatestParseOp = Op;
596         CvDbgPrint ("TrLinkOpChildren=====Set latest parse op to this op.\n");
597     }
598 
599     return (Op);
600 }
601 
602 
603 /*******************************************************************************
604  *
605  * FUNCTION:    TrLinkPeerOp
606  *
607  * PARAMETERS:  Op1           - First peer
608  *              Op2           - Second peer
609  *
610  * RETURN:      Op1 or the non-null op.
611  *
612  * DESCRIPTION: Link two ops as peers. Handles cases where one peer is null.
613  *
614  ******************************************************************************/
615 
616 ACPI_PARSE_OBJECT *
617 TrLinkPeerOp (
618     ACPI_PARSE_OBJECT       *Op1,
619     ACPI_PARSE_OBJECT       *Op2)
620 {
621     ACPI_PARSE_OBJECT       *Next;
622 
623 
624     DbgPrint (ASL_PARSE_OUTPUT,
625         "\nLinkPeerOp: 1=%p (%s), 2=%p (%s)\n",
626         Op1, Op1 ? UtGetOpName(Op1->Asl.ParseOpcode) : NULL,
627         Op2, Op2 ? UtGetOpName(Op2->Asl.ParseOpcode) : NULL);
628 
629 
630     if ((!Op1) && (!Op2))
631     {
632         DbgPrint (ASL_PARSE_OUTPUT, "\nTwo Null ops!\n");
633         return (Op1);
634     }
635 
636     /* If one of the ops is null, just return the non-null op */
637 
638     if (!Op2)
639     {
640         return (Op1);
641     }
642 
643     if (!Op1)
644     {
645         return (Op2);
646     }
647 
648     if (Op1 == Op2)
649     {
650         DbgPrint (ASL_DEBUG_OUTPUT,
651             "\n************* Internal error, linking op to itself %p\n",
652             Op1);
653         AslError (ASL_WARNING, ASL_MSG_COMPILER_INTERNAL, Op1,
654             "Linking op to itself");
655         return (Op1);
656     }
657 
658     Op1->Asl.Parent = Op2->Asl.Parent;
659 
660     /*
661      * Op 1 may already have a peer list (such as an IF/ELSE pair),
662      * so we must walk to the end of the list and attach the new
663      * peer at the end
664      */
665     Next = Op1;
666     while (Next->Asl.Next)
667     {
668         Next = Next->Asl.Next;
669     }
670 
671     Next->Asl.Next = Op2;
672     return (Op1);
673 }
674 
675 
676 /*******************************************************************************
677  *
678  * FUNCTION:    TrLinkPeerOps
679  *
680  * PARAMETERS:  NumPeers            - The number of ops in the list to follow
681  *              ...                 - A list of ops to link together as peers
682  *
683  * RETURN:      The first op in the list (head of the peer list)
684  *
685  * DESCRIPTION: Link together an arbitrary number of peer ops.
686  *
687  ******************************************************************************/
688 
689 ACPI_PARSE_OBJECT *
690 TrLinkPeerOps (
691     UINT32                  NumPeers,
692     ...)
693 {
694     ACPI_PARSE_OBJECT       *This;
695     ACPI_PARSE_OBJECT       *Next;
696     va_list                 ap;
697     UINT32                  i;
698     ACPI_PARSE_OBJECT       *Start;
699 
700 
701     DbgPrint (ASL_PARSE_OUTPUT,
702         "\nLinkPeerOps: (%u) ", NumPeers);
703 
704     va_start (ap, NumPeers);
705     This = va_arg (ap, ACPI_PARSE_OBJECT *);
706     Start = This;
707 
708     /*
709      * Link all peers
710      */
711     for (i = 0; i < (NumPeers -1); i++)
712     {
713         DbgPrint (ASL_PARSE_OUTPUT, "%u=%p ", (i+1), This);
714 
715         while (This->Asl.Next)
716         {
717             This = This->Asl.Next;
718         }
719 
720         /* Get another peer op */
721 
722         Next = va_arg (ap, ACPI_PARSE_OBJECT *);
723         if (!Next)
724         {
725             Next = TrAllocateOp (PARSEOP_DEFAULT_ARG);
726         }
727 
728         /* link new op to the current op */
729 
730         This->Asl.Next = Next;
731         This = Next;
732     }
733 
734     va_end (ap);
735     DbgPrint (ASL_PARSE_OUTPUT,"\n");
736     return (Start);
737 }
738 
739 
740 /*******************************************************************************
741  *
742  * FUNCTION:    TrLinkChildOp
743  *
744  * PARAMETERS:  Op1           - Parent op
745  *              Op2           - Op to become a child
746  *
747  * RETURN:      The parent op
748  *
749  * DESCRIPTION: Link two ops together as a parent and child
750  *
751  ******************************************************************************/
752 
753 ACPI_PARSE_OBJECT *
754 TrLinkChildOp (
755     ACPI_PARSE_OBJECT       *Op1,
756     ACPI_PARSE_OBJECT       *Op2)
757 {
758     ACPI_PARSE_OBJECT       *Next;
759 
760 
761     DbgPrint (ASL_PARSE_OUTPUT,
762         "\nLinkChildOp: Parent=%p (%s), Child=%p (%s)\n",
763         Op1, Op1 ? UtGetOpName(Op1->Asl.ParseOpcode): NULL,
764         Op2, Op2 ? UtGetOpName(Op2->Asl.ParseOpcode): NULL);
765 
766     /*
767      * Converter: if TrLinkChildOp is called to link a method call,
768      * turn on capture comments as it signifies that we are done parsing
769      * a method call.
770      */
771     if (AcpiGbl_CaptureComments && Op1)
772     {
773         if (Op1->Asl.ParseOpcode == PARSEOP_METHODCALL)
774         {
775             AslGbl_CommentState.CaptureComments = TRUE;
776         }
777         AslGbl_CommentState.LatestParseOp = Op1;
778     }
779 
780     if (!Op1 || !Op2)
781     {
782         return (Op1);
783     }
784 
785     Op1->Asl.Child = Op2;
786 
787     /* Set the child and all peers of the child to point to the parent */
788 
789     Next = Op2;
790     while (Next)
791     {
792         Next->Asl.Parent = Op1;
793         Next = Next->Asl.Next;
794     }
795 
796     return (Op1);
797 }
798 
799 
800 /*******************************************************************************
801  *
802  * FUNCTION:    TrWalkParseTree
803  *
804  * PARAMETERS:  Op                      - Walk starting point
805  *              Visitation              - Type of walk
806  *              DescendingCallback      - Called during tree descent
807  *              AscendingCallback       - Called during tree ascent
808  *              Context                 - To be passed to the callbacks
809  *
810  * RETURN:      Status from callback(s)
811  *
812  * DESCRIPTION: Walk the entire parse tree.
813  *
814  ******************************************************************************/
815 
816 ACPI_STATUS
817 TrWalkParseTree (
818     ACPI_PARSE_OBJECT       *Op,
819     UINT32                  Visitation,
820     ASL_WALK_CALLBACK       DescendingCallback,
821     ASL_WALK_CALLBACK       AscendingCallback,
822     void                    *Context)
823 {
824     UINT32                  Level;
825     BOOLEAN                 OpPreviouslyVisited;
826     ACPI_PARSE_OBJECT       *StartOp = Op;
827     ACPI_STATUS             Status;
828 
829 
830     if (!AslGbl_ParseTreeRoot)
831     {
832         return (AE_OK);
833     }
834 
835     Level = 0;
836     OpPreviouslyVisited = FALSE;
837 
838     switch (Visitation)
839     {
840     case ASL_WALK_VISIT_DOWNWARD:
841 
842         while (Op)
843         {
844             if (!OpPreviouslyVisited)
845             {
846                 /* Let the callback process the op. */
847 
848                 Status = DescendingCallback (Op, Level, Context);
849                 if (ACPI_SUCCESS (Status))
850                 {
851                     /* Visit children first, once */
852 
853                     if (Op->Asl.Child)
854                     {
855                         Level++;
856                         Op = Op->Asl.Child;
857                         continue;
858                     }
859                 }
860                 else if (Status != AE_CTRL_DEPTH)
861                 {
862                     /* Exit immediately on any error */
863 
864                     return (Status);
865                 }
866             }
867 
868             /* Terminate walk at start op */
869 
870             if (Op == StartOp)
871             {
872                 break;
873             }
874 
875             /* No more children, visit peers */
876 
877             if (Op->Asl.Next)
878             {
879                 Op = Op->Asl.Next;
880                 OpPreviouslyVisited = FALSE;
881             }
882             else
883             {
884                 /* No children or peers, re-visit parent */
885 
886                 if (Level != 0 )
887                 {
888                     Level--;
889                 }
890                 Op = Op->Asl.Parent;
891                 OpPreviouslyVisited = TRUE;
892             }
893         }
894         break;
895 
896     case ASL_WALK_VISIT_UPWARD:
897 
898         while (Op)
899         {
900             /* Visit leaf op (no children) or parent op on return trip */
901 
902             if ((!Op->Asl.Child) ||
903                 (OpPreviouslyVisited))
904             {
905                 /* Let the callback process the op. */
906 
907                 Status = AscendingCallback (Op, Level, Context);
908                 if (ACPI_FAILURE (Status))
909                 {
910                     return (Status);
911                 }
912             }
913             else
914             {
915                 /* Visit children first, once */
916 
917                 Level++;
918                 Op = Op->Asl.Child;
919                 continue;
920             }
921 
922             /* Terminate walk at start op */
923 
924             if (Op == StartOp)
925             {
926                 break;
927             }
928 
929             /* No more children, visit peers */
930 
931             if (Op->Asl.Next)
932             {
933                 Op = Op->Asl.Next;
934                 OpPreviouslyVisited = FALSE;
935             }
936             else
937             {
938                 /* No children or peers, re-visit parent */
939 
940                 if (Level != 0 )
941                 {
942                     Level--;
943                 }
944                 Op = Op->Asl.Parent;
945                 OpPreviouslyVisited = TRUE;
946             }
947         }
948         break;
949 
950      case ASL_WALK_VISIT_TWICE:
951 
952         while (Op)
953         {
954             if (OpPreviouslyVisited)
955             {
956                 Status = AscendingCallback (Op, Level, Context);
957                 if (ACPI_FAILURE (Status))
958                 {
959                     return (Status);
960                 }
961             }
962             else
963             {
964                 /* Let the callback process the op. */
965 
966                 Status = DescendingCallback (Op, Level, Context);
967                 if (ACPI_SUCCESS (Status))
968                 {
969                     /* Visit children first, once */
970 
971                     if (Op->Asl.Child)
972                     {
973                         Level++;
974                         Op = Op->Asl.Child;
975                         continue;
976                     }
977                 }
978                 else if (Status != AE_CTRL_DEPTH)
979                 {
980                     /* Exit immediately on any error */
981 
982                     return (Status);
983                 }
984             }
985 
986             /* Terminate walk at start op */
987 
988             if (Op == StartOp)
989             {
990                 break;
991             }
992 
993             /* No more children, visit peers */
994 
995             if (Op->Asl.Next)
996             {
997                 Op = Op->Asl.Next;
998                 OpPreviouslyVisited = FALSE;
999             }
1000             else
1001             {
1002                 /* No children or peers, re-visit parent */
1003 
1004                 if (Level != 0 )
1005                 {
1006                     Level--;
1007                 }
1008                 Op = Op->Asl.Parent;
1009                 OpPreviouslyVisited = TRUE;
1010             }
1011         }
1012         break;
1013 
1014     default:
1015         /* No other types supported */
1016         break;
1017     }
1018 
1019     /* If we get here, the walk completed with no errors */
1020 
1021     return (AE_OK);
1022 }
1023