1 /******************************************************************************
2  *
3  * Module Name: utpredef - support functions for predefined names
4  *
5  *****************************************************************************/
6 
7 /*
8  * Copyright (C) 2000 - 2016, Intel Corp.
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 #include "acpi.h"
45 #include "accommon.h"
46 #include "acpredef.h"
47 
48 
49 #define _COMPONENT          ACPI_UTILITIES
50         ACPI_MODULE_NAME    ("utpredef")
51 
52 
53 /*
54  * Names for the types that can be returned by the predefined objects.
55  * Used for warning messages. Must be in the same order as the ACPI_RTYPEs
56  */
57 static const char   *UtRtypeNames[] =
58 {
59     "/Integer",
60     "/String",
61     "/Buffer",
62     "/Package",
63     "/Reference",
64 };
65 
66 
67 /*******************************************************************************
68  *
69  * FUNCTION:    AcpiUtGetNextPredefinedMethod
70  *
71  * PARAMETERS:  ThisName            - Entry in the predefined method/name table
72  *
73  * RETURN:      Pointer to next entry in predefined table.
74  *
75  * DESCRIPTION: Get the next entry in the predefine method table. Handles the
76  *              cases where a package info entry follows a method name that
77  *              returns a package.
78  *
79  ******************************************************************************/
80 
81 const ACPI_PREDEFINED_INFO *
82 AcpiUtGetNextPredefinedMethod (
83     const ACPI_PREDEFINED_INFO  *ThisName)
84 {
85 
86     /*
87      * Skip next entry in the table if this name returns a Package
88      * (next entry contains the package info)
89      */
90     if ((ThisName->Info.ExpectedBtypes & ACPI_RTYPE_PACKAGE) &&
91         (ThisName->Info.ExpectedBtypes != ACPI_RTYPE_ALL))
92     {
93         ThisName++;
94     }
95 
96     ThisName++;
97     return (ThisName);
98 }
99 
100 
101 /*******************************************************************************
102  *
103  * FUNCTION:    AcpiUtMatchPredefinedMethod
104  *
105  * PARAMETERS:  Name                - Name to find
106  *
107  * RETURN:      Pointer to entry in predefined table. NULL indicates not found.
108  *
109  * DESCRIPTION: Check an object name against the predefined object list.
110  *
111  ******************************************************************************/
112 
113 const ACPI_PREDEFINED_INFO *
114 AcpiUtMatchPredefinedMethod (
115     char                        *Name)
116 {
117     const ACPI_PREDEFINED_INFO  *ThisName;
118 
119 
120     /* Quick check for a predefined name, first character must be underscore */
121 
122     if (Name[0] != '_')
123     {
124         return (NULL);
125     }
126 
127     /* Search info table for a predefined method/object name */
128 
129     ThisName = AcpiGbl_PredefinedMethods;
130     while (ThisName->Info.Name[0])
131     {
132         if (ACPI_COMPARE_NAME (Name, ThisName->Info.Name))
133         {
134             return (ThisName);
135         }
136 
137         ThisName = AcpiUtGetNextPredefinedMethod (ThisName);
138     }
139 
140     return (NULL); /* Not found */
141 }
142 
143 
144 /*******************************************************************************
145  *
146  * FUNCTION:    AcpiUtGetExpectedReturnTypes
147  *
148  * PARAMETERS:  Buffer              - Where the formatted string is returned
149  *              ExpectedBTypes      - Bitfield of expected data types
150  *
151  * RETURN:      Formatted string in Buffer.
152  *
153  * DESCRIPTION: Format the expected object types into a printable string.
154  *
155  ******************************************************************************/
156 
157 void
158 AcpiUtGetExpectedReturnTypes (
159     char                    *Buffer,
160     UINT32                  ExpectedBtypes)
161 {
162     UINT32                  ThisRtype;
163     UINT32                  i;
164     UINT32                  j;
165 
166 
167     if (!ExpectedBtypes)
168     {
169         strcpy (Buffer, "NONE");
170         return;
171     }
172 
173     j = 1;
174     Buffer[0] = 0;
175     ThisRtype = ACPI_RTYPE_INTEGER;
176 
177     for (i = 0; i < ACPI_NUM_RTYPES; i++)
178     {
179         /* If one of the expected types, concatenate the name of this type */
180 
181         if (ExpectedBtypes & ThisRtype)
182         {
183             strcat (Buffer, &UtRtypeNames[i][j]);
184             j = 0;              /* Use name separator from now on */
185         }
186 
187         ThisRtype <<= 1;    /* Next Rtype */
188     }
189 }
190 
191 
192 /*******************************************************************************
193  *
194  * The remaining functions are used by iASL and AcpiHelp only
195  *
196  ******************************************************************************/
197 
198 #if (defined ACPI_ASL_COMPILER || defined ACPI_HELP_APP)
199 
200 /* Local prototypes */
201 
202 static UINT32
203 AcpiUtGetArgumentTypes (
204     char                    *Buffer,
205     UINT16                  ArgumentTypes);
206 
207 
208 /* Types that can be returned externally by a predefined name */
209 
210 static const char   *UtExternalTypeNames[] = /* Indexed by ACPI_TYPE_* */
211 {
212     ", UNSUPPORTED-TYPE",
213     ", Integer",
214     ", String",
215     ", Buffer",
216     ", Package"
217 };
218 
219 /* Bit widths for resource descriptor predefined names */
220 
221 static const char   *UtResourceTypeNames[] =
222 {
223     "/1",
224     "/2",
225     "/3",
226     "/8",
227     "/16",
228     "/32",
229     "/64",
230     "/variable",
231 };
232 
233 
234 /*******************************************************************************
235  *
236  * FUNCTION:    AcpiUtMatchResourceName
237  *
238  * PARAMETERS:  Name                - Name to find
239  *
240  * RETURN:      Pointer to entry in the resource table. NULL indicates not
241  *              found.
242  *
243  * DESCRIPTION: Check an object name against the predefined resource
244  *              descriptor object list.
245  *
246  ******************************************************************************/
247 
248 const ACPI_PREDEFINED_INFO *
249 AcpiUtMatchResourceName (
250     char                        *Name)
251 {
252     const ACPI_PREDEFINED_INFO  *ThisName;
253 
254 
255     /*
256      * Quick check for a predefined name, first character must
257      * be underscore
258      */
259     if (Name[0] != '_')
260     {
261         return (NULL);
262     }
263 
264     /* Search info table for a predefined method/object name */
265 
266     ThisName = AcpiGbl_ResourceNames;
267     while (ThisName->Info.Name[0])
268     {
269         if (ACPI_COMPARE_NAME (Name, ThisName->Info.Name))
270         {
271             return (ThisName);
272         }
273 
274         ThisName++;
275     }
276 
277     return (NULL); /* Not found */
278 }
279 
280 
281 /*******************************************************************************
282  *
283  * FUNCTION:    AcpiUtDisplayPredefinedMethod
284  *
285  * PARAMETERS:  Buffer              - Scratch buffer for this function
286  *              ThisName            - Entry in the predefined method/name table
287  *              MultiLine           - TRUE if output should be on >1 line
288  *
289  * RETURN:      None
290  *
291  * DESCRIPTION: Display information about a predefined method. Number and
292  *              type of the input arguments, and expected type(s) for the
293  *              return value, if any.
294  *
295  ******************************************************************************/
296 
297 void
298 AcpiUtDisplayPredefinedMethod (
299     char                        *Buffer,
300     const ACPI_PREDEFINED_INFO  *ThisName,
301     BOOLEAN                     MultiLine)
302 {
303     UINT32                      ArgCount;
304 
305     /*
306      * Get the argument count and the string buffer
307      * containing all argument types
308      */
309     ArgCount = AcpiUtGetArgumentTypes (Buffer,
310         ThisName->Info.ArgumentList);
311 
312     if (MultiLine)
313     {
314         printf ("      ");
315     }
316 
317     printf ("%4.4s    Requires %s%u argument%s",
318         ThisName->Info.Name,
319         (ThisName->Info.ArgumentList & ARG_COUNT_IS_MINIMUM) ?
320             "(at least) " : "",
321         ArgCount, ArgCount != 1 ? "s" : "");
322 
323     /* Display the types for any arguments */
324 
325     if (ArgCount > 0)
326     {
327         printf (" (%s)", Buffer);
328     }
329 
330     if (MultiLine)
331     {
332         printf ("\n    ");
333     }
334 
335     /* Get the return value type(s) allowed */
336 
337     if (ThisName->Info.ExpectedBtypes)
338     {
339         AcpiUtGetExpectedReturnTypes (Buffer, ThisName->Info.ExpectedBtypes);
340         printf ("  Return value types: %s\n", Buffer);
341     }
342     else
343     {
344         printf ("  No return value\n");
345     }
346 }
347 
348 
349 /*******************************************************************************
350  *
351  * FUNCTION:    AcpiUtGetArgumentTypes
352  *
353  * PARAMETERS:  Buffer              - Where to return the formatted types
354  *              ArgumentTypes       - Types field for this method
355  *
356  * RETURN:      Count - the number of arguments required for this method
357  *
358  * DESCRIPTION: Format the required data types for this method (Integer,
359  *              String, Buffer, or Package) and return the required argument
360  *              count.
361  *
362  ******************************************************************************/
363 
364 static UINT32
365 AcpiUtGetArgumentTypes (
366     char                    *Buffer,
367     UINT16                  ArgumentTypes)
368 {
369     UINT16                  ThisArgumentType;
370     UINT16                  SubIndex;
371     UINT16                  ArgCount;
372     UINT32                  i;
373 
374 
375     *Buffer = 0;
376     SubIndex = 2;
377 
378     /* First field in the types list is the count of args to follow */
379 
380     ArgCount = METHOD_GET_ARG_COUNT (ArgumentTypes);
381     if (ArgCount > METHOD_PREDEF_ARGS_MAX)
382     {
383         printf ("**** Invalid argument count (%u) "
384             "in predefined info structure\n", ArgCount);
385         return (ArgCount);
386     }
387 
388     /* Get each argument from the list, convert to ascii, store to buffer */
389 
390     for (i = 0; i < ArgCount; i++)
391     {
392         ThisArgumentType = METHOD_GET_NEXT_TYPE (ArgumentTypes);
393 
394         if (!ThisArgumentType || (ThisArgumentType > METHOD_MAX_ARG_TYPE))
395         {
396             printf ("**** Invalid argument type (%u) "
397                 "in predefined info structure\n", ThisArgumentType);
398             return (ArgCount);
399         }
400 
401         strcat (Buffer, UtExternalTypeNames[ThisArgumentType] + SubIndex);
402         SubIndex = 0;
403     }
404 
405     return (ArgCount);
406 }
407 
408 
409 /*******************************************************************************
410  *
411  * FUNCTION:    AcpiUtGetResourceBitWidth
412  *
413  * PARAMETERS:  Buffer              - Where the formatted string is returned
414  *              Types               - Bitfield of expected data types
415  *
416  * RETURN:      Count of return types. Formatted string in Buffer.
417  *
418  * DESCRIPTION: Format the resource bit widths into a printable string.
419  *
420  ******************************************************************************/
421 
422 UINT32
423 AcpiUtGetResourceBitWidth (
424     char                    *Buffer,
425     UINT16                  Types)
426 {
427     UINT32                  i;
428     UINT16                  SubIndex;
429     UINT32                  Found;
430 
431 
432     *Buffer = 0;
433     SubIndex = 1;
434     Found = 0;
435 
436     for (i = 0; i < NUM_RESOURCE_WIDTHS; i++)
437     {
438         if (Types & 1)
439         {
440             strcat (Buffer, &(UtResourceTypeNames[i][SubIndex]));
441             SubIndex = 0;
442             Found++;
443         }
444 
445         Types >>= 1;
446     }
447 
448     return (Found);
449 }
450 #endif
451