1 /******************************************************************************
2  *
3  * Module Name: utpredef - support functions for predefined names
4  *
5  *****************************************************************************/
6 
7 /*
8  * Copyright (C) 2000 - 2015, 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 #include <stdio.h>
200 #include <string.h>
201 
202 /* Local prototypes */
203 
204 static UINT32
205 AcpiUtGetArgumentTypes (
206     char                    *Buffer,
207     UINT16                  ArgumentTypes);
208 
209 
210 /* Types that can be returned externally by a predefined name */
211 
212 static const char   *UtExternalTypeNames[] = /* Indexed by ACPI_TYPE_* */
213 {
214     ", UNSUPPORTED-TYPE",
215     ", Integer",
216     ", String",
217     ", Buffer",
218     ", Package"
219 };
220 
221 /* Bit widths for resource descriptor predefined names */
222 
223 static const char   *UtResourceTypeNames[] =
224 {
225     "/1",
226     "/2",
227     "/3",
228     "/8",
229     "/16",
230     "/32",
231     "/64",
232     "/variable",
233 };
234 
235 
236 /*******************************************************************************
237  *
238  * FUNCTION:    AcpiUtMatchResourceName
239  *
240  * PARAMETERS:  Name                - Name to find
241  *
242  * RETURN:      Pointer to entry in the resource table. NULL indicates not
243  *              found.
244  *
245  * DESCRIPTION: Check an object name against the predefined resource
246  *              descriptor object list.
247  *
248  ******************************************************************************/
249 
250 const ACPI_PREDEFINED_INFO *
251 AcpiUtMatchResourceName (
252     char                        *Name)
253 {
254     const ACPI_PREDEFINED_INFO  *ThisName;
255 
256 
257     /*
258      * Quick check for a predefined name, first character must
259      * be underscore
260      */
261     if (Name[0] != '_')
262     {
263         return (NULL);
264     }
265 
266     /* Search info table for a predefined method/object name */
267 
268     ThisName = AcpiGbl_ResourceNames;
269     while (ThisName->Info.Name[0])
270     {
271         if (ACPI_COMPARE_NAME (Name, ThisName->Info.Name))
272         {
273             return (ThisName);
274         }
275 
276         ThisName++;
277     }
278 
279     return (NULL); /* Not found */
280 }
281 
282 
283 /*******************************************************************************
284  *
285  * FUNCTION:    AcpiUtDisplayPredefinedMethod
286  *
287  * PARAMETERS:  Buffer              - Scratch buffer for this function
288  *              ThisName            - Entry in the predefined method/name table
289  *              MultiLine           - TRUE if output should be on >1 line
290  *
291  * RETURN:      None
292  *
293  * DESCRIPTION: Display information about a predefined method. Number and
294  *              type of the input arguments, and expected type(s) for the
295  *              return value, if any.
296  *
297  ******************************************************************************/
298 
299 void
300 AcpiUtDisplayPredefinedMethod (
301     char                        *Buffer,
302     const ACPI_PREDEFINED_INFO  *ThisName,
303     BOOLEAN                     MultiLine)
304 {
305     UINT32                      ArgCount;
306 
307     /*
308      * Get the argument count and the string buffer
309      * containing all argument types
310      */
311     ArgCount = AcpiUtGetArgumentTypes (Buffer,
312         ThisName->Info.ArgumentList);
313 
314     if (MultiLine)
315     {
316         printf ("      ");
317     }
318 
319     printf ("%4.4s    Requires %s%u argument%s",
320         ThisName->Info.Name,
321         (ThisName->Info.ArgumentList & ARG_COUNT_IS_MINIMUM) ?
322             "(at least) " : "",
323         ArgCount, ArgCount != 1 ? "s" : "");
324 
325     /* Display the types for any arguments */
326 
327     if (ArgCount > 0)
328     {
329         printf (" (%s)", Buffer);
330     }
331 
332     if (MultiLine)
333     {
334         printf ("\n    ");
335     }
336 
337     /* Get the return value type(s) allowed */
338 
339     if (ThisName->Info.ExpectedBtypes)
340     {
341         AcpiUtGetExpectedReturnTypes (Buffer, ThisName->Info.ExpectedBtypes);
342         printf ("  Return value types: %s\n", Buffer);
343     }
344     else
345     {
346         printf ("  No return value\n");
347     }
348 }
349 
350 
351 /*******************************************************************************
352  *
353  * FUNCTION:    AcpiUtGetArgumentTypes
354  *
355  * PARAMETERS:  Buffer              - Where to return the formatted types
356  *              ArgumentTypes       - Types field for this method
357  *
358  * RETURN:      Count - the number of arguments required for this method
359  *
360  * DESCRIPTION: Format the required data types for this method (Integer,
361  *              String, Buffer, or Package) and return the required argument
362  *              count.
363  *
364  ******************************************************************************/
365 
366 static UINT32
367 AcpiUtGetArgumentTypes (
368     char                    *Buffer,
369     UINT16                  ArgumentTypes)
370 {
371     UINT16                  ThisArgumentType;
372     UINT16                  SubIndex;
373     UINT16                  ArgCount;
374     UINT32                  i;
375 
376 
377     *Buffer = 0;
378     SubIndex = 2;
379 
380     /* First field in the types list is the count of args to follow */
381 
382     ArgCount = METHOD_GET_ARG_COUNT (ArgumentTypes);
383     if (ArgCount > METHOD_PREDEF_ARGS_MAX)
384     {
385         printf ("**** Invalid argument count (%u) "
386             "in predefined info structure\n", ArgCount);
387         return (ArgCount);
388     }
389 
390     /* Get each argument from the list, convert to ascii, store to buffer */
391 
392     for (i = 0; i < ArgCount; i++)
393     {
394         ThisArgumentType = METHOD_GET_NEXT_TYPE (ArgumentTypes);
395 
396         if (!ThisArgumentType || (ThisArgumentType > METHOD_MAX_ARG_TYPE))
397         {
398             printf ("**** Invalid argument type (%u) "
399                 "in predefined info structure\n", ThisArgumentType);
400             return (ArgCount);
401         }
402 
403         strcat (Buffer, UtExternalTypeNames[ThisArgumentType] + SubIndex);
404         SubIndex = 0;
405     }
406 
407     return (ArgCount);
408 }
409 
410 
411 /*******************************************************************************
412  *
413  * FUNCTION:    AcpiUtGetResourceBitWidth
414  *
415  * PARAMETERS:  Buffer              - Where the formatted string is returned
416  *              Types               - Bitfield of expected data types
417  *
418  * RETURN:      Count of return types. Formatted string in Buffer.
419  *
420  * DESCRIPTION: Format the resource bit widths into a printable string.
421  *
422  ******************************************************************************/
423 
424 UINT32
425 AcpiUtGetResourceBitWidth (
426     char                    *Buffer,
427     UINT16                  Types)
428 {
429     UINT32                  i;
430     UINT16                  SubIndex;
431     UINT32                  Found;
432 
433 
434     *Buffer = 0;
435     SubIndex = 1;
436     Found = 0;
437 
438     for (i = 0; i < NUM_RESOURCE_WIDTHS; i++)
439     {
440         if (Types & 1)
441         {
442             strcat (Buffer, &(UtResourceTypeNames[i][SubIndex]));
443             SubIndex = 0;
444             Found++;
445         }
446 
447         Types >>= 1;
448     }
449 
450     return (Found);
451 }
452 #endif
453