acpi/acpica/utpredef.c

0001 // SPDX-License-Identifier: BSD-3-Clause OR GPL-2.0
0002 /******************************************************************************
0003  *
0004  * Module Name: utpredef - support functions for predefined names
0005  *
0006  * Copyright (C) 2000 - 2022, Intel Corp.
0007  *
0008  *****************************************************************************/
0009
0010 #include <acpi/acpi.h>
0011 #include "accommon.h"
0012 #include "acpredef.h"
0013
0014 #define _COMPONENT          ACPI_UTILITIES
0015 ACPI_MODULE_NAME("utpredef")
0016
0017 /*
0018  * Names for the types that can be returned by the predefined objects.
0019  * Used for warning messages. Must be in the same order as the ACPI_RTYPEs
0020  */
0021 static const char *ut_rtype_names[] = {
0022     "/Integer",
0023     "/String",
0024     "/Buffer",
0025     "/Package",
0026     "/Reference",
0027 };
0028
0029 /*******************************************************************************
0030  *
0031  * FUNCTION:    acpi_ut_get_next_predefined_method
0032  *
0033  * PARAMETERS:  this_name           - Entry in the predefined method/name table
0034  *
0035  * RETURN:      Pointer to next entry in predefined table.
0036  *
0037  * DESCRIPTION: Get the next entry in the predefine method table. Handles the
0038  *              cases where a package info entry follows a method name that
0039  *              returns a package.
0040  *
0041  ******************************************************************************/
0042
0043 const union acpi_predefined_info *acpi_ut_get_next_predefined_method(const union
0044                                      acpi_predefined_info
0045                                      *this_name)
0046 {
0047
0048     /*
0049      * Skip next entry in the table if this name returns a Package
0050      * (next entry contains the package info)
0051      */
0052     if ((this_name->info.expected_btypes & ACPI_RTYPE_PACKAGE) &&
0053         (this_name->info.expected_btypes != ACPI_RTYPE_ALL)) {
0054         this_name++;
0055     }
0056
0057     this_name++;
0058     return (this_name);
0059 }
0060
0061 /*******************************************************************************
0062  *
0063  * FUNCTION:    acpi_ut_match_predefined_method
0064  *
0065  * PARAMETERS:  name                - Name to find
0066  *
0067  * RETURN:      Pointer to entry in predefined table. NULL indicates not found.
0068  *
0069  * DESCRIPTION: Check an object name against the predefined object list.
0070  *
0071  ******************************************************************************/
0072
0073 const union acpi_predefined_info *acpi_ut_match_predefined_method(char *name)
0074 {
0075     const union acpi_predefined_info *this_name;
0076
0077     /* Quick check for a predefined name, first character must be underscore */
0078
0079     if (name[0] != '_') {
0080         return (NULL);
0081     }
0082
0083     /* Search info table for a predefined method/object name */
0084
0085     this_name = acpi_gbl_predefined_methods;
0086     while (this_name->info.name[0]) {
0087         if (ACPI_COMPARE_NAMESEG(name, this_name->info.name)) {
0088             return (this_name);
0089         }
0090
0091         this_name = acpi_ut_get_next_predefined_method(this_name);
0092     }
0093
0094     return (NULL);      /* Not found */
0095 }
0096
0097 /*******************************************************************************
0098  *
0099  * FUNCTION:    acpi_ut_get_expected_return_types
0100  *
0101  * PARAMETERS:  buffer              - Where the formatted string is returned
0102  *              expected_Btypes     - Bitfield of expected data types
0103  *
0104  * RETURN:      Formatted string in Buffer.
0105  *
0106  * DESCRIPTION: Format the expected object types into a printable string.
0107  *
0108  ******************************************************************************/
0109
0110 void acpi_ut_get_expected_return_types(char *buffer, u32 expected_btypes)
0111 {
0112     u32 this_rtype;
0113     u32 i;
0114     u32 j;
0115
0116     if (!expected_btypes) {
0117         strcpy(buffer, "NONE");
0118         return;
0119     }
0120
0121     j = 1;
0122     buffer[0] = 0;
0123     this_rtype = ACPI_RTYPE_INTEGER;
0124
0125     for (i = 0; i < ACPI_NUM_RTYPES; i++) {
0126
0127         /* If one of the expected types, concatenate the name of this type */
0128
0129         if (expected_btypes & this_rtype) {
0130             strcat(buffer, &ut_rtype_names[i][j]);
0131             j = 0;  /* Use name separator from now on */
0132         }
0133
0134         this_rtype <<= 1;   /* Next Rtype */
0135     }
0136 }
0137
0138 /*******************************************************************************
0139  *
0140  * The remaining functions are used by iASL and acpi_help only
0141  *
0142  ******************************************************************************/
0143
0144 #if (defined ACPI_ASL_COMPILER || defined ACPI_HELP_APP)
0145
0146 /* Local prototypes */
0147
0148 static u32 acpi_ut_get_argument_types(char *buffer, u16 argument_types);
0149
0150 /* Types that can be returned externally by a predefined name */
0151
0152 static const char *ut_external_type_names[] =   /* Indexed by ACPI_TYPE_* */
0153 {
0154     ", Type_ANY",
0155     ", Integer",
0156     ", String",
0157     ", Buffer",
0158     ", Package"
0159 };
0160
0161 /* Bit widths for resource descriptor predefined names */
0162
0163 static const char *ut_resource_type_names[] = {
0164     "/1",
0165     "/2",
0166     "/3",
0167     "/8",
0168     "/16",
0169     "/32",
0170     "/64",
0171     "/variable",
0172 };
0173
0174 /*******************************************************************************
0175  *
0176  * FUNCTION:    acpi_ut_match_resource_name
0177  *
0178  * PARAMETERS:  name                - Name to find
0179  *
0180  * RETURN:      Pointer to entry in the resource table. NULL indicates not
0181  *              found.
0182  *
0183  * DESCRIPTION: Check an object name against the predefined resource
0184  *              descriptor object list.
0185  *
0186  ******************************************************************************/
0187
0188 const union acpi_predefined_info *acpi_ut_match_resource_name(char *name)
0189 {
0190     const union acpi_predefined_info *this_name;
0191
0192     /*
0193      * Quick check for a predefined name, first character must
0194      * be underscore
0195      */
0196     if (name[0] != '_') {
0197         return (NULL);
0198     }
0199
0200     /* Search info table for a predefined method/object name */
0201
0202     this_name = acpi_gbl_resource_names;
0203     while (this_name->info.name[0]) {
0204         if (ACPI_COMPARE_NAMESEG(name, this_name->info.name)) {
0205             return (this_name);
0206         }
0207
0208         this_name++;
0209     }
0210
0211     return (NULL);      /* Not found */
0212 }
0213
0214 /*******************************************************************************
0215  *
0216  * FUNCTION:    acpi_ut_display_predefined_method
0217  *
0218  * PARAMETERS:  buffer              - Scratch buffer for this function
0219  *              this_name           - Entry in the predefined method/name table
0220  *              multi_line          - TRUE if output should be on >1 line
0221  *
0222  * RETURN:      None
0223  *
0224  * DESCRIPTION: Display information about a predefined method. Number and
0225  *              type of the input arguments, and expected type(s) for the
0226  *              return value, if any.
0227  *
0228  ******************************************************************************/
0229
0230 void
0231 acpi_ut_display_predefined_method(char *buffer,
0232                   const union acpi_predefined_info *this_name,
0233                   u8 multi_line)
0234 {
0235     u32 arg_count;
0236
0237     /*
0238      * Get the argument count and the string buffer
0239      * containing all argument types
0240      */
0241     arg_count = acpi_ut_get_argument_types(buffer,
0242                            this_name->info.argument_list);
0243
0244     if (multi_line) {
0245         printf("      ");
0246     }
0247
0248     printf("%4.4s    Requires %s%u argument%s",
0249            this_name->info.name,
0250            (this_name->info.argument_list & ARG_COUNT_IS_MINIMUM) ?
0251            "(at least) " : "", arg_count, arg_count != 1 ? "s" : "");
0252
0253     /* Display the types for any arguments */
0254
0255     if (arg_count > 0) {
0256         printf(" (%s)", buffer);
0257     }
0258
0259     if (multi_line) {
0260         printf("\n    ");
0261     }
0262
0263     /* Get the return value type(s) allowed */
0264
0265     if (this_name->info.expected_btypes) {
0266         acpi_ut_get_expected_return_types(buffer,
0267                           this_name->info.
0268                           expected_btypes);
0269         printf("  Return value types: %s\n", buffer);
0270     } else {
0271         printf("  No return value\n");
0272     }
0273 }
0274
0275 /*******************************************************************************
0276  *
0277  * FUNCTION:    acpi_ut_get_argument_types
0278  *
0279  * PARAMETERS:  buffer              - Where to return the formatted types
0280  *              argument_types      - Types field for this method
0281  *
0282  * RETURN:      count - the number of arguments required for this method
0283  *
0284  * DESCRIPTION: Format the required data types for this method (Integer,
0285  *              String, Buffer, or Package) and return the required argument
0286  *              count.
0287  *
0288  ******************************************************************************/
0289
0290 static u32 acpi_ut_get_argument_types(char *buffer, u16 argument_types)
0291 {
0292     u16 this_argument_type;
0293     u16 sub_index;
0294     u16 arg_count;
0295     u32 i;
0296
0297     *buffer = 0;
0298     sub_index = 2;
0299
0300     /* First field in the types list is the count of args to follow */
0301
0302     arg_count = METHOD_GET_ARG_COUNT(argument_types);
0303     if (arg_count > METHOD_PREDEF_ARGS_MAX) {
0304         printf("**** Invalid argument count (%u) "
0305                "in predefined info structure\n", arg_count);
0306         return (arg_count);
0307     }
0308
0309     /* Get each argument from the list, convert to ascii, store to buffer */
0310
0311     for (i = 0; i < arg_count; i++) {
0312         this_argument_type = METHOD_GET_NEXT_TYPE(argument_types);
0313
0314         if (this_argument_type > METHOD_MAX_ARG_TYPE) {
0315             printf("**** Invalid argument type (%u) "
0316                    "in predefined info structure\n",
0317                    this_argument_type);
0318             return (arg_count);
0319         }
0320
0321         strcat(buffer,
0322                ut_external_type_names[this_argument_type] + sub_index);
0323         sub_index = 0;
0324     }
0325
0326     return (arg_count);
0327 }
0328
0329 /*******************************************************************************
0330  *
0331  * FUNCTION:    acpi_ut_get_resource_bit_width
0332  *
0333  * PARAMETERS:  buffer              - Where the formatted string is returned
0334  *              types               - Bitfield of expected data types
0335  *
0336  * RETURN:      Count of return types. Formatted string in Buffer.
0337  *
0338  * DESCRIPTION: Format the resource bit widths into a printable string.
0339  *
0340  ******************************************************************************/
0341
0342 u32 acpi_ut_get_resource_bit_width(char *buffer, u16 types)
0343 {
0344     u32 i;
0345     u16 sub_index;
0346     u32 found;
0347
0348     *buffer = 0;
0349     sub_index = 1;
0350     found = 0;
0351
0352     for (i = 0; i < NUM_RESOURCE_WIDTHS; i++) {
0353         if (types & 1) {
0354             strcat(buffer, &(ut_resource_type_names[i][sub_index]));
0355             sub_index = 0;
0356             found++;
0357         }
0358
0359         types >>= 1;
0360     }
0361
0362     return (found);
0363 }
0364 #endif