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) Driver-specific callbacks
^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) The ``pldmfw`` module relies on the device driver for implementing device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  8) specific behavior using the following operations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  9) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) ``.match_record``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) The ``.match_record`` operation is used to determine whether a given PLDM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) record matches the device being updated. This requires comparing the record
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) descriptors in the record with information from the device. Many record
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) descriptors are defined by the PLDM standard, but it is also allowed for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) devices to implement their own descriptors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) The ``.match_record`` operation should return true if a given record matches
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) ``.send_package_data``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) The ``.send_package_data`` operation is used to send the device-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) package data in a record to the device firmware. If the matching record
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) provides package data, ``pldmfw`` will call the ``.send_package_data``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) function with a pointer to the package data and with the package data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) length. The device driver should send this data to firmware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) ``.send_component_table``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) -------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) The ``.send_component_table`` operation is used to forward component
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) information to the device. It is called once for each applicable component,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) that is, for each component indicated by the matching record. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) device driver should send the component information to the device firmware,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) and wait for a response. The provided transfer flag indicates whether this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) is the first, last, or a middle component, and is expected to be forwarded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) to firmware as part of the component table information. The driver should an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) error in the case when the firmware indicates that the component cannot be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) updated, or return zero if the component can be updated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) ``.flash_component``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) The ``.flash_component`` operation is used to inform the device driver to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) flash a given component. The driver must perform any steps necessary to send
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) the component data to the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) ``.finalize_update``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) The ``.finalize_update`` operation is used by the ``pldmfw`` library in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) order to allow the device driver to perform any remaining device specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) logic needed to finish the update.