Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  1) .. SPDX-License-Identifier: GPL-2.0-only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  3) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  4) PLDM Firmware Flash Update Library
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  5) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  6) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  7) ``pldmfw`` implements functionality for updating the flash on a device using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  8) the PLDM for Firmware Update standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  9) <https://www.dmtf.org/documents/pmci/pldm-firmware-update-specification-100>.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) .. toctree::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)    :maxdepth: 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)    file-format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)    driver-ops
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) Overview of the ``pldmfw`` library
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) The ``pldmfw`` library is intended to be used by device drivers for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) implementing device flash update based on firmware files following the PLDM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) firwmare file format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) It is implemented using an ops table that allows device drivers to provide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) the underlying device specific functionality.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) ``pldmfw`` implements logic to parse the packed binary format of the PLDM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) firmware file into data structures, and then uses the provided function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) operations to determine if the firmware file is a match for the device. If
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) so, it sends the record and component data to the firmware using the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) specific implementations provided by device drivers. Once the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) firmware indicates that the update may be performed, the firmware data is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) sent to the device for programming.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) Parsing the PLDM file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) The PLDM file format uses packed binary data, with most multi-byte fields
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) stored in the Little Endian format. Several pieces of data are variable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) length, including version strings and the number of records and components.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) Due to this, it is not straight forward to index the record, record
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) descriptors, or components.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) To avoid proliferating access to the packed binary data, the ``pldmfw``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) library parses and extracts this data into simpler structures for ease of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) access.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) In order to safely process the firmware file, care is taken to avoid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) unaligned access of multi-byte fields, and to properly convert from Little
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) Endian to CPU host format. Additionally the records, descriptors, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) components are stored in linked lists.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) Performing a flash update
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) To perform a flash update, the ``pldmfw`` module performs the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) steps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) 1. Parse the firmware file for record and component information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) 2. Scan through the records and determine if the device matches any record
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)    in the file. The first matched record will be used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) 3. If the matching record provides package data, send this package data to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)    the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) 4. For each component that the record indicates, send the component data to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)    the device. For each component, the firmware may respond with an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)    indication of whether the update is suitable or not. If any component is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)    not suitable, the update is canceled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) 5. For each component, send the binary data to the device firmware for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)    updating.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) 6. After all components are programmed, perform any final device-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)    actions to finalize the update.