drivers/acpi/executer/exfldio.c

   1 /******************************************************************************
   2  *
   3  * Module Name: exfldio - Aml Field I/O
   4  *
   5  *****************************************************************************/
   6
   7 /*
   8  * Copyright (C) 2000 - 2004, R. Byron Moore
   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
  45 #include <acpi/acpi.h>
  46 #include <acpi/acinterp.h>
  47 #include <acpi/amlcode.h>
  48 #include <acpi/acevents.h>
  49 #include <acpi/acdispat.h>
  50
  51
  52 #define _COMPONENT          ACPI_EXECUTER
  53          ACPI_MODULE_NAME    ("exfldio")
  54
  55
  56 /*******************************************************************************
  57  *
  58  * FUNCTION:    acpi_ex_setup_region
  59  *
  60  * PARAMETERS:  *obj_desc               - Field to be read or written
  61  *              field_datum_byte_offset - Byte offset of this datum within the
  62  *                                        parent field
  63  *
  64  * RETURN:      Status
  65  *
  66  * DESCRIPTION: Common processing for acpi_ex_extract_from_field and
  67  *              acpi_ex_insert_into_field. Initialize the Region if necessary and
  68  *              validate the request.
  69  *
  70  ******************************************************************************/
  71
  72 acpi_status
  73 acpi_ex_setup_region (
  74         union acpi_operand_object       *obj_desc,
  75         u32                             field_datum_byte_offset)
  76 {
  77         acpi_status                     status = AE_OK;
  78         union acpi_operand_object       *rgn_desc;
  79
  80
  81         ACPI_FUNCTION_TRACE_U32 ("ex_setup_region", field_datum_byte_offset);
  82
  83
  84         rgn_desc = obj_desc->common_field.region_obj;
  85
  86         /* We must have a valid region */
  87
  88         if (ACPI_GET_OBJECT_TYPE (rgn_desc) != ACPI_TYPE_REGION) {
  89                 ACPI_DEBUG_PRINT ((ACPI_DB_ERROR, "Needed Region, found type %X (%s)\n",
  90                         ACPI_GET_OBJECT_TYPE (rgn_desc),
  91                         acpi_ut_get_object_type_name (rgn_desc)));
  92
  93                 return_ACPI_STATUS (AE_AML_OPERAND_TYPE);
  94         }
  95
  96         /*
  97          * If the Region Address and Length have not been previously evaluated,
  98          * evaluate them now and save the results.
  99          */
 100         if (!(rgn_desc->common.flags & AOPOBJ_DATA_VALID)) {
 101                 status = acpi_ds_get_region_arguments (rgn_desc);
 102                 if (ACPI_FAILURE (status)) {
 103                         return_ACPI_STATUS (status);
 104                 }
 105         }
 106
 107         if (rgn_desc->region.space_id == ACPI_ADR_SPACE_SMBUS) {
 108                 /* SMBus has a non-linear address space */
 109
 110                 return_ACPI_STATUS (AE_OK);
 111         }
 112
 113 #ifdef ACPI_UNDER_DEVELOPMENT
 114         /*
 115          * If the Field access is any_acc, we can now compute the optimal
 116          * access (because we know know the length of the parent region)
 117          */
 118         if (!(obj_desc->common.flags & AOPOBJ_DATA_VALID)) {
 119                 if (ACPI_FAILURE (status)) {
 120                         return_ACPI_STATUS (status);
 121                 }
 122         }
 123 #endif
 124
 125         /*
 126          * Validate the request.  The entire request from the byte offset for a
 127          * length of one field datum (access width) must fit within the region.
 128          * (Region length is specified in bytes)
 129          */
 130         if (rgn_desc->region.length < (obj_desc->common_field.base_byte_offset
 131                            + field_datum_byte_offset
 132                            + obj_desc->common_field.access_byte_width)) {
 133                 if (acpi_gbl_enable_interpreter_slack) {
 134                         /*
 135                          * Slack mode only:  We will go ahead and allow access to this
 136                          * field if it is within the region length rounded up to the next
 137                          * access width boundary.
 138                          */
 139                         if (ACPI_ROUND_UP (rgn_desc->region.length,
 140                                            obj_desc->common_field.access_byte_width) >=
 141                                 (obj_desc->common_field.base_byte_offset +
 142                                  obj_desc->common_field.access_byte_width +
 143                                  field_datum_byte_offset)) {
 144                                 return_ACPI_STATUS (AE_OK);
 145                         }
 146                 }
 147
 148                 if (rgn_desc->region.length < obj_desc->common_field.access_byte_width) {
 149                         /*
 150                          * This is the case where the access_type (acc_word, etc.) is wider
 151                          * than the region itself.  For example, a region of length one
 152                          * byte, and a field with Dword access specified.
 153                          */
 154                         ACPI_DEBUG_PRINT ((ACPI_DB_ERROR,
 155                                 "Field [%4.4s] access width (%d bytes) too large for region [%4.4s] (length %X)\n",
 156                                 acpi_ut_get_node_name (obj_desc->common_field.node),
 157                                 obj_desc->common_field.access_byte_width,
 158                                 acpi_ut_get_node_name (rgn_desc->region.node), rgn_desc->region.length));
 159                 }
 160
 161                 /*
 162                  * Offset rounded up to next multiple of field width
 163                  * exceeds region length, indicate an error
 164                  */
 165                 ACPI_DEBUG_PRINT ((ACPI_DB_ERROR,
 166                         "Field [%4.4s] Base+Offset+Width %X+%X+%X is beyond end of region [%4.4s] (length %X)\n",
 167                         acpi_ut_get_node_name (obj_desc->common_field.node),
 168                         obj_desc->common_field.base_byte_offset,
 169                         field_datum_byte_offset, obj_desc->common_field.access_byte_width,
 170                         acpi_ut_get_node_name (rgn_desc->region.node), rgn_desc->region.length));
 171
 172                 return_ACPI_STATUS (AE_AML_REGION_LIMIT);
 173         }
 174
 175         return_ACPI_STATUS (AE_OK);
 176 }
 177
 178
 179 /*******************************************************************************
 180  *
 181  * FUNCTION:    acpi_ex_access_region
 182  *
 183  * PARAMETERS:  *obj_desc               - Field to be read
 184  *              field_datum_byte_offset - Byte offset of this datum within the
 185  *                                        parent field
 186  *              *Value                  - Where to store value (must at least
 187  *                                        the size of acpi_integer)
 188  *              Function                - Read or Write flag plus other region-
 189  *                                        dependent flags
 190  *
 191  * RETURN:      Status
 192  *
 193  * DESCRIPTION: Read or Write a single field datum to an Operation Region.
 194  *
 195  ******************************************************************************/
 196
 197 acpi_status
 198 acpi_ex_access_region (
 199         union acpi_operand_object       *obj_desc,
 200         u32                             field_datum_byte_offset,
 201         acpi_integer                    *value,
 202         u32                             function)
 203 {
 204         acpi_status                     status;
 205         union acpi_operand_object       *rgn_desc;
 206         acpi_physical_address           address;
 207
 208
 209         ACPI_FUNCTION_TRACE ("ex_access_region");
 210
 211
 212         /*
 213          * Ensure that the region operands are fully evaluated and verify
 214          * the validity of the request
 215          */
 216         status = acpi_ex_setup_region (obj_desc, field_datum_byte_offset);
 217         if (ACPI_FAILURE (status)) {
 218                 return_ACPI_STATUS (status);
 219         }
 220
 221         /*
 222          * The physical address of this field datum is:
 223          *
 224          * 1) The base of the region, plus
 225          * 2) The base offset of the field, plus
 226          * 3) The current offset into the field
 227          */
 228         rgn_desc = obj_desc->common_field.region_obj;
 229         address = rgn_desc->region.address
 230                          + obj_desc->common_field.base_byte_offset
 231                          + field_datum_byte_offset;
 232
 233         if ((function & ACPI_IO_MASK) == ACPI_READ) {
 234                 ACPI_DEBUG_PRINT ((ACPI_DB_BFIELD, "[READ]"));
 235         }
 236         else {
 237                 ACPI_DEBUG_PRINT ((ACPI_DB_BFIELD, "[WRITE]"));
 238         }
 239
 240         ACPI_DEBUG_PRINT_RAW ((ACPI_DB_BFIELD,
 241                 " Region [%s:%X], Width %X, byte_base %X, Offset %X at %8.8X%8.8X\n",
 242                 acpi_ut_get_region_name (rgn_desc->region.space_id),
 243                 rgn_desc->region.space_id,
 244                 obj_desc->common_field.access_byte_width,
 245                 obj_desc->common_field.base_byte_offset,
 246                 field_datum_byte_offset,
 247                 ACPI_FORMAT_UINT64 (address)));
 248
 249         /* Invoke the appropriate address_space/op_region handler */
 250
 251         status = acpi_ev_address_space_dispatch (rgn_desc, function,
 252                           address, ACPI_MUL_8 (obj_desc->common_field.access_byte_width), value);
 253
 254         if (ACPI_FAILURE (status)) {
 255                 if (status == AE_NOT_IMPLEMENTED) {
 256                         ACPI_DEBUG_PRINT ((ACPI_DB_ERROR,
 257                                 "Region %s(%X) not implemented\n",
 258                                 acpi_ut_get_region_name (rgn_desc->region.space_id),
 259                                 rgn_desc->region.space_id));
 260                 }
 261                 else if (status == AE_NOT_EXIST) {
 262                         ACPI_REPORT_ERROR ((
 263                                 "Region %s(%X) has no handler\n",
 264                                 acpi_ut_get_region_name (rgn_desc->region.space_id),
 265                                 rgn_desc->region.space_id));
 266                 }
 267         }
 268
 269         return_ACPI_STATUS (status);
 270 }
 271
 272
 273 /*******************************************************************************
 274  *
 275  * FUNCTION:    acpi_ex_register_overflow
 276  *
 277  * PARAMETERS:  *obj_desc               - Register(Field) to be written
 278  *              Value                   - Value to be stored
 279  *
 280  * RETURN:      TRUE if value overflows the field, FALSE otherwise
 281  *
 282  * DESCRIPTION: Check if a value is out of range of the field being written.
 283  *              Used to check if the values written to Index and Bank registers
 284  *              are out of range.  Normally, the value is simply truncated
 285  *              to fit the field, but this case is most likely a serious
 286  *              coding error in the ASL.
 287  *
 288  ******************************************************************************/
 289
 290 u8
 291 acpi_ex_register_overflow (
 292         union acpi_operand_object       *obj_desc,
 293         acpi_integer                    value)
 294 {
 295
 296         if (obj_desc->common_field.bit_length >= ACPI_INTEGER_BIT_SIZE) {
 297                 /*
 298                  * The field is large enough to hold the maximum integer, so we can
 299                  * never overflow it.
 300                  */
 301                 return (FALSE);
 302         }
 303
 304         if (value >= ((acpi_integer) 1 << obj_desc->common_field.bit_length)) {
 305                 /*
 306                  * The Value is larger than the maximum value that can fit into
 307                  * the register.
 308                  */
 309                 return (TRUE);
 310         }
 311
 312         /* The Value will fit into the field with no truncation */
 313
 314         return (FALSE);
 315 }
 316
 317
 318 /*******************************************************************************
 319  *
 320  * FUNCTION:    acpi_ex_field_datum_io
 321  *
 322  * PARAMETERS:  *obj_desc               - Field to be read
 323  *              field_datum_byte_offset - Byte offset of this datum within the
 324  *                                        parent field
 325  *              *Value                  - Where to store value (must be 64 bits)
 326  *              read_write              - Read or Write flag
 327  *
 328  * RETURN:      Status
 329  *
 330  * DESCRIPTION: Read or Write a single datum of a field.  The field_type is
 331  *              demultiplexed here to handle the different types of fields
 332  *              (buffer_field, region_field, index_field, bank_field)
 333  *
 334  ******************************************************************************/
 335
 336 acpi_status
 337 acpi_ex_field_datum_io (
 338         union acpi_operand_object       *obj_desc,
 339         u32                             field_datum_byte_offset,
 340         acpi_integer                    *value,
 341         u32                             read_write)
 342 {
 343         acpi_status                     status;
 344         acpi_integer                    local_value;
 345
 346
 347         ACPI_FUNCTION_TRACE_U32 ("ex_field_datum_io", field_datum_byte_offset);
 348
 349
 350         if (read_write == ACPI_READ) {
 351                 if (!value) {
 352                         local_value = 0;
 353                         value = &local_value; /* To support reads without saving return value */
 354                 }
 355
 356                 /* Clear the entire return buffer first, [Very Important!] */
 357
 358                 *value = 0;
 359         }
 360
 361         /*
 362          * The four types of fields are:
 363          *
 364          * buffer_field - Read/write from/to a Buffer
 365          * region_field - Read/write from/to a Operation Region.
 366          * bank_field  - Write to a Bank Register, then read/write from/to an op_region
 367          * index_field - Write to an Index Register, then read/write from/to a Data Register
 368          */
 369         switch (ACPI_GET_OBJECT_TYPE (obj_desc)) {
 370         case ACPI_TYPE_BUFFER_FIELD:
 371                 /*
 372                  * If the buffer_field arguments have not been previously evaluated,
 373                  * evaluate them now and save the results.
 374                  */
 375                 if (!(obj_desc->common.flags & AOPOBJ_DATA_VALID)) {
 376                         status = acpi_ds_get_buffer_field_arguments (obj_desc);
 377                         if (ACPI_FAILURE (status)) {
 378                                 return_ACPI_STATUS (status);
 379                         }
 380                 }
 381
 382                 if (read_write == ACPI_READ) {
 383                         /*
 384                          * Copy the data from the source buffer.
 385                          * Length is the field width in bytes.
 386                          */
 387                         ACPI_MEMCPY (value, (obj_desc->buffer_field.buffer_obj)->buffer.pointer
 388                                           + obj_desc->buffer_field.base_byte_offset
 389                                           + field_datum_byte_offset,
 390                                           obj_desc->common_field.access_byte_width);
 391                 }
 392                 else {
 393                         /*
 394                          * Copy the data to the target buffer.
 395                          * Length is the field width in bytes.
 396                          */
 397                         ACPI_MEMCPY ((obj_desc->buffer_field.buffer_obj)->buffer.pointer
 398                                         + obj_desc->buffer_field.base_byte_offset
 399                                         + field_datum_byte_offset,
 400                                         value, obj_desc->common_field.access_byte_width);
 401                 }
 402
 403                 status = AE_OK;
 404                 break;
 405
 406
 407         case ACPI_TYPE_LOCAL_BANK_FIELD:
 408
 409                 /* Ensure that the bank_value is not beyond the capacity of the register */
 410
 411                 if (acpi_ex_register_overflow (obj_desc->bank_field.bank_obj,
 412                                   (acpi_integer) obj_desc->bank_field.value)) {
 413                         return_ACPI_STATUS (AE_AML_REGISTER_LIMIT);
 414                 }
 415
 416                 /*
 417                  * For bank_fields, we must write the bank_value to the bank_register
 418                  * (itself a region_field) before we can access the data.
 419                  */
 420                 status = acpi_ex_insert_into_field (obj_desc->bank_field.bank_obj,
 421                                  &obj_desc->bank_field.value,
 422                                  sizeof (obj_desc->bank_field.value));
 423                 if (ACPI_FAILURE (status)) {
 424                         return_ACPI_STATUS (status);
 425                 }
 426
 427                 /*
 428                  * Now that the Bank has been selected, fall through to the
 429                  * region_field case and write the datum to the Operation Region
 430                  */
 431
 432                 /*lint -fallthrough */
 433
 434
 435         case ACPI_TYPE_LOCAL_REGION_FIELD:
 436                 /*
 437                  * For simple region_fields, we just directly access the owning
 438                  * Operation Region.
 439                  */
 440                 status = acpi_ex_access_region (obj_desc, field_datum_byte_offset, value,
 441                                   read_write);
 442                 break;
 443
 444
 445         case ACPI_TYPE_LOCAL_INDEX_FIELD:
 446
 447
 448                 /* Ensure that the index_value is not beyond the capacity of the register */
 449
 450                 if (acpi_ex_register_overflow (obj_desc->index_field.index_obj,
 451                                   (acpi_integer) obj_desc->index_field.value)) {
 452                         return_ACPI_STATUS (AE_AML_REGISTER_LIMIT);
 453                 }
 454
 455                 /* Write the index value to the index_register (itself a region_field) */
 456
 457                 field_datum_byte_offset += obj_desc->index_field.value;
 458
 459                 ACPI_DEBUG_PRINT ((ACPI_DB_BFIELD,
 460                                 "Write to Index Register: Value %8.8X\n",
 461                                 field_datum_byte_offset));
 462
 463                 status = acpi_ex_insert_into_field (obj_desc->index_field.index_obj,
 464                                  &field_datum_byte_offset,
 465                                  sizeof (field_datum_byte_offset));
 466                 if (ACPI_FAILURE (status)) {
 467                         return_ACPI_STATUS (status);
 468                 }
 469
 470                 ACPI_DEBUG_PRINT ((ACPI_DB_BFIELD,
 471                                 "I/O to Data Register: value_ptr %p\n",
 472                                 value));
 473
 474                 if (read_write == ACPI_READ) {
 475                         /* Read the datum from the data_register */
 476
 477                         status = acpi_ex_extract_from_field (obj_desc->index_field.data_obj,
 478                                           value, sizeof (acpi_integer));
 479                 }
 480                 else {
 481                         /* Write the datum to the data_register */
 482
 483                         status = acpi_ex_insert_into_field (obj_desc->index_field.data_obj,
 484                                           value, sizeof (acpi_integer));
 485                 }
 486                 break;
 487
 488
 489         default:
 490
 491                 ACPI_REPORT_ERROR (("Wrong object type in field I/O %X\n",
 492                         ACPI_GET_OBJECT_TYPE (obj_desc)));
 493                 status = AE_AML_INTERNAL;
 494                 break;
 495         }
 496
 497         if (ACPI_SUCCESS (status)) {
 498                 if (read_write == ACPI_READ) {
 499                         ACPI_DEBUG_PRINT ((ACPI_DB_BFIELD, "Value Read %8.8X%8.8X, Width %d\n",
 500                                            ACPI_FORMAT_UINT64 (*value),
 501                                            obj_desc->common_field.access_byte_width));
 502                 }
 503                 else {
 504                         ACPI_DEBUG_PRINT ((ACPI_DB_BFIELD, "Value Written %8.8X%8.8X, Width %d\n",
 505                                            ACPI_FORMAT_UINT64 (*value),
 506                                            obj_desc->common_field.access_byte_width));
 507                 }
 508         }
 509
 510         return_ACPI_STATUS (status);
 511 }
 512
 513
 514 /*******************************************************************************
 515  *
 516  * FUNCTION:    acpi_ex_write_with_update_rule
 517  *
 518  * PARAMETERS:  *obj_desc           - Field to be set
 519  *              Value               - Value to store
 520  *
 521  * RETURN:      Status
 522  *
 523  * DESCRIPTION: Apply the field update rule to a field write
 524  *
 525  ******************************************************************************/
 526
 527 acpi_status
 528 acpi_ex_write_with_update_rule (
 529         union acpi_operand_object       *obj_desc,
 530         acpi_integer                    mask,
 531         acpi_integer                    field_value,
 532         u32                             field_datum_byte_offset)
 533 {
 534         acpi_status                     status = AE_OK;
 535         acpi_integer                    merged_value;
 536         acpi_integer                    current_value;
 537
 538
 539         ACPI_FUNCTION_TRACE_U32 ("ex_write_with_update_rule", mask);
 540
 541
 542         /* Start with the new bits  */
 543
 544         merged_value = field_value;
 545
 546         /* If the mask is all ones, we don't need to worry about the update rule */
 547
 548         if (mask != ACPI_INTEGER_MAX) {
 549                 /* Decode the update rule */
 550
 551                 switch (obj_desc->common_field.field_flags & AML_FIELD_UPDATE_RULE_MASK) {
 552                 case AML_FIELD_UPDATE_PRESERVE:
 553                         /*
 554                          * Check if update rule needs to be applied (not if mask is all
 555                          * ones)  The left shift drops the bits we want to ignore.
 556                          */
 557                         if ((~mask << (ACPI_MUL_8 (sizeof (mask)) -
 558                                          ACPI_MUL_8 (obj_desc->common_field.access_byte_width))) != 0) {
 559                                 /*
 560                                  * Read the current contents of the byte/word/dword containing
 561                                  * the field, and merge with the new field value.
 562                                  */
 563                                 status = acpi_ex_field_datum_io (obj_desc, field_datum_byte_offset,
 564                                                   &current_value, ACPI_READ);
 565                                 if (ACPI_FAILURE (status)) {
 566                                         return_ACPI_STATUS (status);
 567                                 }
 568
 569                                 merged_value |= (current_value & ~mask);
 570                         }
 571                         break;
 572
 573                 case AML_FIELD_UPDATE_WRITE_AS_ONES:
 574
 575                         /* Set positions outside the field to all ones */
 576
 577                         merged_value |= ~mask;
 578                         break;
 579
 580                 case AML_FIELD_UPDATE_WRITE_AS_ZEROS:
 581
 582                         /* Set positions outside the field to all zeros */
 583
 584                         merged_value &= mask;
 585                         break;
 586
 587                 default:
 588
 589                         ACPI_DEBUG_PRINT ((ACPI_DB_ERROR,
 590                                 "write_with_update_rule: Unknown update_rule setting: %X\n",
 591                                 (obj_desc->common_field.field_flags & AML_FIELD_UPDATE_RULE_MASK)));
 592                         return_ACPI_STATUS (AE_AML_OPERAND_VALUE);
 593                 }
 594         }
 595
 596         ACPI_DEBUG_PRINT ((ACPI_DB_BFIELD,
 597                 "Mask %8.8X%8.8X, datum_offset %X, Width %X, Value %8.8X%8.8X, merged_value %8.8X%8.8X\n",
 598                 ACPI_FORMAT_UINT64 (mask),
 599                 field_datum_byte_offset,
 600                 obj_desc->common_field.access_byte_width,
 601                 ACPI_FORMAT_UINT64 (field_value),
 602                 ACPI_FORMAT_UINT64 (merged_value)));
 603
 604         /* Write the merged value */
 605
 606         status = acpi_ex_field_datum_io (obj_desc, field_datum_byte_offset,
 607                           &merged_value, ACPI_WRITE);
 608
 609         return_ACPI_STATUS (status);
 610 }
 611
 612
 613 /*******************************************************************************
 614  *
 615  * FUNCTION:    acpi_ex_get_buffer_datum
 616  *
 617  * PARAMETERS:  Datum               - Where the Datum is returned
 618  *              Buffer              - Raw field buffer
 619  *              buffer_length       - Entire length (used for big-endian only)
 620  *              byte_granularity    - 1/2/4/8 Granularity of the field
 621  *                                    (aka Datum Size)
 622  *              buffer_offset       - Datum offset into the buffer
 623  *
 624  * RETURN:      none
 625  *
 626  * DESCRIPTION: Get a datum from the buffer according to the buffer field
 627  *              byte granularity
 628  *
 629  ******************************************************************************/
 630
 631 void
 632 acpi_ex_get_buffer_datum (
 633         acpi_integer                    *datum,
 634         void                            *buffer,
 635         u32                             buffer_length,
 636         u32                             byte_granularity,
 637         u32                             buffer_offset)
 638 {
 639         u32                             index;
 640
 641
 642         ACPI_FUNCTION_TRACE_U32 ("ex_get_buffer_datum", byte_granularity);
 643
 644
 645         /* Get proper index into buffer (handles big/little endian) */
 646
 647         index = ACPI_BUFFER_INDEX (buffer_length, buffer_offset, byte_granularity);
 648
 649         /* Move the requested number of bytes */
 650
 651         switch (byte_granularity) {
 652         case ACPI_FIELD_BYTE_GRANULARITY:
 653
 654                 *datum = ((u8 *) buffer) [index];
 655                 break;
 656
 657         case ACPI_FIELD_WORD_GRANULARITY:
 658
 659                 ACPI_MOVE_16_TO_64 (datum, &(((u16 *) buffer) [index]));
 660                 break;
 661
 662         case ACPI_FIELD_DWORD_GRANULARITY:
 663
 664                 ACPI_MOVE_32_TO_64 (datum, &(((u32 *) buffer) [index]));
 665                 break;
 666
 667         case ACPI_FIELD_QWORD_GRANULARITY:
 668
 669                 ACPI_MOVE_64_TO_64 (datum, &(((u64 *) buffer) [index]));
 670                 break;
 671
 672         default:
 673                 /* Should not get here */
 674                 break;
 675         }
 676
 677         return_VOID;
 678 }
 679
 680
 681 /*******************************************************************************
 682  *
 683  * FUNCTION:    acpi_ex_set_buffer_datum
 684  *
 685  * PARAMETERS:  merged_datum        - Value to store
 686  *              Buffer              - Receiving buffer
 687  *              buffer_length       - Entire length (used for big-endian only)
 688  *              byte_granularity    - 1/2/4/8 Granularity of the field
 689  *                                    (aka Datum Size)
 690  *              buffer_offset       - Datum offset into the buffer
 691  *
 692  * RETURN:      none
 693  *
 694  * DESCRIPTION: Store the merged datum to the buffer according to the
 695  *              byte granularity
 696  *
 697  ******************************************************************************/
 698
 699 void
 700 acpi_ex_set_buffer_datum (
 701         acpi_integer                    merged_datum,
 702         void                            *buffer,
 703         u32                             buffer_length,
 704         u32                             byte_granularity,
 705         u32                             buffer_offset)
 706 {
 707         u32                             index;
 708
 709
 710         ACPI_FUNCTION_TRACE_U32 ("ex_set_buffer_datum", byte_granularity);
 711
 712
 713         /* Get proper index into buffer (handles big/little endian) */
 714
 715         index = ACPI_BUFFER_INDEX (buffer_length, buffer_offset, byte_granularity);
 716
 717         /* Move the requested number of bytes */
 718
 719         switch (byte_granularity) {
 720         case ACPI_FIELD_BYTE_GRANULARITY:
 721
 722                 ((u8 *) buffer) [index] = (u8) merged_datum;
 723                 break;
 724
 725         case ACPI_FIELD_WORD_GRANULARITY:
 726
 727                 ACPI_MOVE_64_TO_16 (&(((u16 *) buffer)[index]), &merged_datum);
 728                 break;
 729
 730         case ACPI_FIELD_DWORD_GRANULARITY:
 731
 732                 ACPI_MOVE_64_TO_32 (&(((u32 *) buffer)[index]), &merged_datum);
 733                 break;
 734
 735         case ACPI_FIELD_QWORD_GRANULARITY:
 736
 737                 ACPI_MOVE_64_TO_64 (&(((u64 *) buffer)[index]), &merged_datum);
 738                 break;
 739
 740         default:
 741                 /* Should not get here */
 742                 break;
 743         }
 744
 745         return_VOID;
 746 }
 747
 748
 749 /*******************************************************************************
 750  *
 751  * FUNCTION:    acpi_ex_common_buffer_setup
 752  *
 753  * PARAMETERS:  obj_desc            - Field object
 754  *              buffer_length       - Length of caller's buffer
 755  *              datum_count         - Where the datum_count is returned
 756  *
 757  * RETURN:      Status, datum_count
 758  *
 759  * DESCRIPTION: Common code to validate the incoming buffer size and compute
 760  *              the number of field "datums" that must be read or written.
 761  *              A "datum" is the smallest unit that can be read or written
 762  *              to the field, it is either 1,2,4, or 8 bytes.
 763  *
 764  ******************************************************************************/
 765
 766 acpi_status
 767 acpi_ex_common_buffer_setup (
 768         union acpi_operand_object       *obj_desc,
 769         u32                             buffer_length,
 770         u32                             *datum_count)
 771 {
 772         u32                             byte_field_length;
 773         u32                             actual_byte_field_length;
 774
 775
 776         ACPI_FUNCTION_TRACE ("ex_common_buffer_setup");
 777
 778
 779         /*
 780          * Incoming buffer must be at least as long as the field, we do not
 781          * allow "partial" field reads/writes.  We do not care if the buffer is
 782          * larger than the field, this typically happens when an integer is
 783          * read/written to a field that is actually smaller than an integer.
 784          */
 785         byte_field_length = ACPI_ROUND_BITS_UP_TO_BYTES (
 786                          obj_desc->common_field.bit_length);
 787         if (byte_field_length > buffer_length) {
 788                 ACPI_DEBUG_PRINT ((ACPI_DB_BFIELD,
 789                         "Field size %X (bytes) is too large for buffer (%X)\n",
 790                         byte_field_length, buffer_length));
 791
 792                 return_ACPI_STATUS (AE_BUFFER_OVERFLOW);
 793         }
 794
 795         /*
 796          * Create "actual" field byte count (minimum number of bytes that
 797          * must be read), then convert to datum count (minimum number
 798          * of datum-sized units that must be read)
 799          */
 800         actual_byte_field_length = ACPI_ROUND_BITS_UP_TO_BYTES (
 801                           obj_desc->common_field.start_field_bit_offset +
 802                           obj_desc->common_field.bit_length);
 803
 804
 805         *datum_count = ACPI_ROUND_UP_TO (actual_byte_field_length,
 806                            obj_desc->common_field.access_byte_width);
 807
 808         ACPI_DEBUG_PRINT ((ACPI_DB_BFIELD,
 809                 "buffer_bytes %X, actual_bytes %X, Datums %X, byte_gran %X\n",
 810                 byte_field_length, actual_byte_field_length,
 811                 *datum_count, obj_desc->common_field.access_byte_width));
 812
 813         return_ACPI_STATUS (AE_OK);
 814 }
 815
 816
 817 /*******************************************************************************
 818  *
 819  * FUNCTION:    acpi_ex_extract_from_field
 820  *
 821  * PARAMETERS:  obj_desc            - Field to be read
 822  *              Buffer              - Where to store the field data
 823  *              buffer_length       - Length of Buffer
 824  *
 825  * RETURN:      Status
 826  *
 827  * DESCRIPTION: Retrieve the current value of the given field
 828  *
 829  ******************************************************************************/
 830
 831 acpi_status
 832 acpi_ex_extract_from_field (
 833         union acpi_operand_object       *obj_desc,
 834         void                            *buffer,
 835         u32                             buffer_length)
 836 {
 837         acpi_status                     status;
 838         u32                             field_datum_byte_offset;
 839         u32                             buffer_datum_offset;
 840         acpi_integer                    previous_raw_datum = 0;
 841         acpi_integer                    this_raw_datum = 0;
 842         acpi_integer                    merged_datum = 0;
 843         u32                             datum_count;
 844         u32                             i;
 845
 846
 847         ACPI_FUNCTION_TRACE ("ex_extract_from_field");
 848
 849
 850         /* Validate buffer, compute number of datums */
 851
 852         status = acpi_ex_common_buffer_setup (obj_desc, buffer_length, &datum_count);
 853         if (ACPI_FAILURE (status)) {
 854                 return_ACPI_STATUS (status);
 855         }
 856
 857         /*
 858          * Clear the caller's buffer (the whole buffer length as given)
 859          * This is very important, especially in the cases where the buffer
 860          * is longer than the size of the field.
 861          */
 862         ACPI_MEMSET (buffer, 0, buffer_length);
 863
 864         field_datum_byte_offset = 0;
 865         buffer_datum_offset= 0;
 866
 867         /* Read the entire field */
 868
 869         for (i = 0; i < datum_count; i++) {
 870                 status = acpi_ex_field_datum_io (obj_desc, field_datum_byte_offset,
 871                                   &this_raw_datum, ACPI_READ);
 872                 if (ACPI_FAILURE (status)) {
 873                         return_ACPI_STATUS (status);
 874                 }
 875
 876                 /* We might actually be done if the request fits in one datum */
 877
 878                 if ((datum_count == 1) &&
 879                         (obj_desc->common_field.flags & AOPOBJ_SINGLE_DATUM)) {
 880                         /* 1) Shift the valid data bits down to start at bit 0 */
 881
 882                         merged_datum = (this_raw_datum >> obj_desc->common_field.start_field_bit_offset);
 883
 884                         /* 2) Mask off any upper unused bits (bits not part of the field) */
 885
 886                         if (obj_desc->common_field.end_buffer_valid_bits) {
 887                                 merged_datum &= ACPI_MASK_BITS_ABOVE (obj_desc->common_field.end_buffer_valid_bits);
 888                         }
 889
 890                         /* Store the datum to the caller buffer */
 891
 892                         acpi_ex_set_buffer_datum (merged_datum, buffer, buffer_length,
 893                                         obj_desc->common_field.access_byte_width, buffer_datum_offset);
 894
 895                         return_ACPI_STATUS (AE_OK);
 896                 }
 897
 898                 /* Special handling for the last datum to ignore extra bits */
 899
 900                 if ((i >= (datum_count -1))          &&
 901                         (obj_desc->common_field.end_field_valid_bits)) {
 902                         /*
 903                          * This is the last iteration of the loop.  We need to clear
 904                          * any unused bits (bits that are not part of this field) before
 905                          * we store the final merged datum into the caller buffer.
 906                          */
 907                         this_raw_datum &=
 908                                 ACPI_MASK_BITS_ABOVE (obj_desc->common_field.end_field_valid_bits);
 909                 }
 910
 911                 /*
 912                  * Create the (possibly) merged datum to be stored to the caller buffer
 913                  */
 914                 if (obj_desc->common_field.start_field_bit_offset == 0) {
 915                         /* Field is not skewed and we can just copy the datum */
 916
 917                         acpi_ex_set_buffer_datum (this_raw_datum, buffer, buffer_length,
 918                                         obj_desc->common_field.access_byte_width, buffer_datum_offset);
 919                         buffer_datum_offset++;
 920                 }
 921                 else {
 922                         /* Not aligned -- on the first iteration, just save the datum */
 923
 924                         if (i != 0) {
 925                                 /*
 926                                  * Put together the appropriate bits of the two raw data to make a
 927                                  * single complete field datum
 928                                  *
 929                                  * 1) Normalize the first datum down to bit 0
 930                                  */
 931                                 merged_datum = (previous_raw_datum >> obj_desc->common_field.start_field_bit_offset);
 932
 933                                 /* 2) Insert the second datum "above" the first datum */
 934
 935                                 merged_datum |= (this_raw_datum << obj_desc->common_field.datum_valid_bits);
 936
 937                                 acpi_ex_set_buffer_datum (merged_datum, buffer, buffer_length,
 938                                                 obj_desc->common_field.access_byte_width, buffer_datum_offset);
 939                                 buffer_datum_offset++;
 940                         }
 941
 942                         /*
 943                          * Save the raw datum that was just acquired since it may contain bits
 944                          * of the *next* field datum
 945                          */
 946                         previous_raw_datum = this_raw_datum;
 947                 }
 948
 949                 field_datum_byte_offset += obj_desc->common_field.access_byte_width;
 950         }
 951
 952         /* For non-aligned case, there is one last datum to insert */
 953
 954         if (obj_desc->common_field.start_field_bit_offset != 0) {
 955                 merged_datum = (this_raw_datum >> obj_desc->common_field.start_field_bit_offset);
 956
 957                 acpi_ex_set_buffer_datum (merged_datum, buffer, buffer_length,
 958                                 obj_desc->common_field.access_byte_width, buffer_datum_offset);
 959         }
 960
 961         return_ACPI_STATUS (AE_OK);
 962 }
 963
 964
 965 /*******************************************************************************
 966  *
 967  * FUNCTION:    acpi_ex_insert_into_field
 968  *
 969  * PARAMETERS:  obj_desc            - Field to be written
 970  *              Buffer              - Data to be written
 971  *              buffer_length       - Length of Buffer
 972  *
 973  * RETURN:      Status
 974  *
 975  * DESCRIPTION: Store the Buffer contents into the given field
 976  *
 977  ******************************************************************************/
 978
 979 acpi_status
 980 acpi_ex_insert_into_field (
 981         union acpi_operand_object       *obj_desc,
 982         void                            *buffer,
 983         u32                             buffer_length)
 984 {
 985         acpi_status                     status;
 986         u32                             field_datum_byte_offset;
 987         u32                             datum_offset;
 988         acpi_integer                    mask;
 989         acpi_integer                    merged_datum;
 990         acpi_integer                    previous_raw_datum;
 991         acpi_integer                    this_raw_datum;
 992         u32                             datum_count;
 993
 994
 995         ACPI_FUNCTION_TRACE ("ex_insert_into_field");
 996
 997
 998         /* Validate buffer, compute number of datums */
 999
1000         status = acpi_ex_common_buffer_setup (obj_desc, buffer_length, &datum_count);
1001         if (ACPI_FAILURE (status)) {
1002                 return_ACPI_STATUS (status);
1003         }
1004
1005         /*
1006          * Break the request into up to three parts (similar to an I/O request):
1007          * 1) non-aligned part at start
1008          * 2) aligned part in middle
1009          * 3) non-aligned part at the end
1010          */
1011         field_datum_byte_offset = 0;
1012         datum_offset= 0;
1013
1014         /* Get a single datum from the caller's buffer */
1015
1016         acpi_ex_get_buffer_datum (&previous_raw_datum, buffer, buffer_length,
1017                         obj_desc->common_field.access_byte_width, datum_offset);
1018
1019         /*
1020          * Part1:
1021          * Write a partial field datum if field does not begin on a datum boundary
1022          * Note: The code in this section also handles the aligned case
1023          *
1024          * Construct Mask with 1 bits where the field is, 0 bits elsewhere
1025          * (Only the bottom 5 bits of bit_length are valid for a shift operation)
1026          *
1027          * Mask off bits that are "below" the field (if any)
1028          */
1029         mask = ACPI_MASK_BITS_BELOW (obj_desc->common_field.start_field_bit_offset);
1030
1031         /* If the field fits in one datum, may need to mask upper bits */
1032
1033         if ((obj_desc->common_field.flags & AOPOBJ_SINGLE_DATUM) &&
1034                  obj_desc->common_field.end_field_valid_bits) {
1035                 /* There are bits above the field, mask them off also */
1036
1037                 mask &= ACPI_MASK_BITS_ABOVE (obj_desc->common_field.end_field_valid_bits);
1038         }
1039
1040         /* Shift and mask the value into the field position */
1041
1042         merged_datum = (previous_raw_datum << obj_desc->common_field.start_field_bit_offset);
1043         merged_datum &= mask;
1044
1045         /* Apply the update rule (if necessary) and write the datum to the field */
1046
1047         status = acpi_ex_write_with_update_rule (obj_desc, mask, merged_datum,
1048                            field_datum_byte_offset);
1049         if (ACPI_FAILURE (status)) {
1050                 return_ACPI_STATUS (status);
1051         }
1052
1053         /* We just wrote the first datum */
1054
1055         datum_offset++;
1056
1057         /* If the entire field fits within one datum, we are done. */
1058
1059         if ((datum_count == 1) &&
1060            (obj_desc->common_field.flags & AOPOBJ_SINGLE_DATUM)) {
1061                 return_ACPI_STATUS (AE_OK);
1062         }
1063
1064         /*
1065          * Part2:
1066          * Write the aligned data.
1067          *
1068          * We don't need to worry about the update rule for these data, because
1069          * all of the bits in each datum are part of the field.
1070          *
1071          * The last datum must be special cased because it might contain bits
1072          * that are not part of the field -- therefore the "update rule" must be
1073          * applied in Part3 below.
1074          */
1075         while (datum_offset < datum_count) {
1076                 field_datum_byte_offset += obj_desc->common_field.access_byte_width;
1077
1078                 /*
1079                  * Get the next raw buffer datum.  It may contain bits of the previous
1080                  * field datum
1081                  */
1082                 acpi_ex_get_buffer_datum (&this_raw_datum, buffer, buffer_length,
1083                                 obj_desc->common_field.access_byte_width, datum_offset);
1084
1085                 /* Create the field datum based on the field alignment */
1086
1087                 if (obj_desc->common_field.start_field_bit_offset != 0) {
1088                         /*
1089                          * Put together appropriate bits of the two raw buffer data to make
1090                          * a single complete field datum
1091                          */
1092                         merged_datum =
1093                                 (previous_raw_datum >> obj_desc->common_field.datum_valid_bits) |
1094                                 (this_raw_datum << obj_desc->common_field.start_field_bit_offset);
1095                 }
1096                 else {
1097                         /* Field began aligned on datum boundary */
1098
1099                         merged_datum = this_raw_datum;
1100                 }
1101
1102                 /*
1103                  * Special handling for the last datum if the field does NOT end on
1104                  * a datum boundary.  Update Rule must be applied to the bits outside
1105                  * the field.
1106                  */
1107                 datum_offset++;
1108                 if ((datum_offset == datum_count) &&
1109                         (obj_desc->common_field.end_field_valid_bits)) {
1110                         /*
1111                          * If there are dangling non-aligned bits, perform one more merged write
1112                          * Else - field is aligned at the end, no need for any more writes
1113                          */
1114
1115                         /*
1116                          * Part3:
1117                          * This is the last datum and the field does not end on a datum boundary.
1118                          * Build the partial datum and write with the update rule.
1119                          *
1120                          * Mask off the unused bits above (after) the end-of-field
1121                          */
1122                         mask = ACPI_MASK_BITS_ABOVE (obj_desc->common_field.end_field_valid_bits);
1123                         merged_datum &= mask;
1124
1125                         /* Write the last datum with the update rule */
1126
1127                         status = acpi_ex_write_with_update_rule (obj_desc, mask, merged_datum,
1128                                            field_datum_byte_offset);
1129                         if (ACPI_FAILURE (status)) {
1130                                 return_ACPI_STATUS (status);
1131                         }
1132                 }
1133                 else {
1134                         /* Normal (aligned) case -- write the completed datum */
1135
1136                         status = acpi_ex_field_datum_io (obj_desc, field_datum_byte_offset,
1137                                           &merged_datum, ACPI_WRITE);
1138                         if (ACPI_FAILURE (status)) {
1139                                 return_ACPI_STATUS (status);
1140                         }
1141                 }
1142
1143                 /*
1144                  * Save the most recent datum since it may contain bits of the *next*
1145                  * field datum.  Update current byte offset.
1146                  */
1147                 previous_raw_datum = this_raw_datum;
1148         }
1149
1150         return_ACPI_STATUS (status);
1151 }
1152
1153