include/linux/firmware.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 #ifndef _LINUX_FIRMWARE_H
0003 #define _LINUX_FIRMWARE_H
0004
0005 #include <linux/types.h>
0006 #include <linux/compiler.h>
0007 #include <linux/gfp.h>
0008
0009 #define FW_ACTION_NOUEVENT 0
0010 #define FW_ACTION_UEVENT 1
0011
0012 struct firmware {
0013     size_t size;
0014     const u8 *data;
0015
0016     /* firmware loader private fields */
0017     void *priv;
0018 };
0019
0020 /**
0021  * enum fw_upload_err - firmware upload error codes
0022  * @FW_UPLOAD_ERR_NONE: returned to indicate success
0023  * @FW_UPLOAD_ERR_HW_ERROR: error signalled by hardware, see kernel log
0024  * @FW_UPLOAD_ERR_TIMEOUT: SW timed out on handshake with HW/firmware
0025  * @FW_UPLOAD_ERR_CANCELED: upload was cancelled by the user
0026  * @FW_UPLOAD_ERR_BUSY: there is an upload operation already in progress
0027  * @FW_UPLOAD_ERR_INVALID_SIZE: invalid firmware image size
0028  * @FW_UPLOAD_ERR_RW_ERROR: read or write to HW failed, see kernel log
0029  * @FW_UPLOAD_ERR_WEAROUT: FLASH device is approaching wear-out, wait & retry
0030  * @FW_UPLOAD_ERR_MAX: Maximum error code marker
0031  */
0032 enum fw_upload_err {
0033     FW_UPLOAD_ERR_NONE,
0034     FW_UPLOAD_ERR_HW_ERROR,
0035     FW_UPLOAD_ERR_TIMEOUT,
0036     FW_UPLOAD_ERR_CANCELED,
0037     FW_UPLOAD_ERR_BUSY,
0038     FW_UPLOAD_ERR_INVALID_SIZE,
0039     FW_UPLOAD_ERR_RW_ERROR,
0040     FW_UPLOAD_ERR_WEAROUT,
0041     FW_UPLOAD_ERR_MAX
0042 };
0043
0044 struct fw_upload {
0045     void *dd_handle; /* reference to parent driver */
0046     void *priv;  /* firmware loader private fields */
0047 };
0048
0049 /**
0050  * struct fw_upload_ops - device specific operations to support firmware upload
0051  * @prepare:          Required: Prepare secure update
0052  * @write:        Required: The write() op receives the remaining
0053  *            size to be written and must return the actual
0054  *            size written or a negative error code. The write()
0055  *            op will be called repeatedly until all data is
0056  *            written.
0057  * @poll_complete:    Required: Check for the completion of the
0058  *            HW authentication/programming process.
0059  * @cancel:       Required: Request cancellation of update. This op
0060  *            is called from the context of a different kernel
0061  *            thread, so race conditions need to be considered.
0062  * @cleanup:          Optional: Complements the prepare()
0063  *            function and is called at the completion
0064  *            of the update, on success or failure, if the
0065  *            prepare function succeeded.
0066  */
0067 struct fw_upload_ops {
0068     enum fw_upload_err (*prepare)(struct fw_upload *fw_upload,
0069                       const u8 *data, u32 size);
0070     enum fw_upload_err (*write)(struct fw_upload *fw_upload,
0071                     const u8 *data, u32 offset,
0072                     u32 size, u32 *written);
0073     enum fw_upload_err (*poll_complete)(struct fw_upload *fw_upload);
0074     void (*cancel)(struct fw_upload *fw_upload);
0075     void (*cleanup)(struct fw_upload *fw_upload);
0076 };
0077
0078 struct module;
0079 struct device;
0080
0081 /*
0082  * Built-in firmware functionality is only available if FW_LOADER=y, but not
0083  * FW_LOADER=m
0084  */
0085 #ifdef CONFIG_FW_LOADER
0086 bool firmware_request_builtin(struct firmware *fw, const char *name);
0087 #else
0088 static inline bool firmware_request_builtin(struct firmware *fw,
0089                         const char *name)
0090 {
0091     return false;
0092 }
0093 #endif
0094
0095 #if IS_REACHABLE(CONFIG_FW_LOADER)
0096 int request_firmware(const struct firmware **fw, const char *name,
0097              struct device *device);
0098 int firmware_request_nowarn(const struct firmware **fw, const char *name,
0099                 struct device *device);
0100 int firmware_request_platform(const struct firmware **fw, const char *name,
0101                   struct device *device);
0102 int request_firmware_nowait(
0103     struct module *module, bool uevent,
0104     const char *name, struct device *device, gfp_t gfp, void *context,
0105     void (*cont)(const struct firmware *fw, void *context));
0106 int request_firmware_direct(const struct firmware **fw, const char *name,
0107                 struct device *device);
0108 int request_firmware_into_buf(const struct firmware **firmware_p,
0109     const char *name, struct device *device, void *buf, size_t size);
0110 int request_partial_firmware_into_buf(const struct firmware **firmware_p,
0111                       const char *name, struct device *device,
0112                       void *buf, size_t size, size_t offset);
0113
0114 void release_firmware(const struct firmware *fw);
0115 #else
0116 static inline int request_firmware(const struct firmware **fw,
0117                    const char *name,
0118                    struct device *device)
0119 {
0120     return -EINVAL;
0121 }
0122
0123 static inline int firmware_request_nowarn(const struct firmware **fw,
0124                       const char *name,
0125                       struct device *device)
0126 {
0127     return -EINVAL;
0128 }
0129
0130 static inline int firmware_request_platform(const struct firmware **fw,
0131                         const char *name,
0132                         struct device *device)
0133 {
0134     return -EINVAL;
0135 }
0136
0137 static inline int request_firmware_nowait(
0138     struct module *module, bool uevent,
0139     const char *name, struct device *device, gfp_t gfp, void *context,
0140     void (*cont)(const struct firmware *fw, void *context))
0141 {
0142     return -EINVAL;
0143 }
0144
0145 static inline void release_firmware(const struct firmware *fw)
0146 {
0147 }
0148
0149 static inline int request_firmware_direct(const struct firmware **fw,
0150                       const char *name,
0151                       struct device *device)
0152 {
0153     return -EINVAL;
0154 }
0155
0156 static inline int request_firmware_into_buf(const struct firmware **firmware_p,
0157     const char *name, struct device *device, void *buf, size_t size)
0158 {
0159     return -EINVAL;
0160 }
0161
0162 static inline int request_partial_firmware_into_buf
0163                     (const struct firmware **firmware_p,
0164                      const char *name,
0165                      struct device *device,
0166                      void *buf, size_t size, size_t offset)
0167 {
0168     return -EINVAL;
0169 }
0170
0171 #endif
0172
0173 #ifdef CONFIG_FW_UPLOAD
0174
0175 struct fw_upload *
0176 firmware_upload_register(struct module *module, struct device *parent,
0177              const char *name, const struct fw_upload_ops *ops,
0178              void *dd_handle);
0179 void firmware_upload_unregister(struct fw_upload *fw_upload);
0180
0181 #else
0182
0183 static inline struct fw_upload *
0184 firmware_upload_register(struct module *module, struct device *parent,
0185              const char *name, const struct fw_upload_ops *ops,
0186              void *dd_handle)
0187 {
0188         return ERR_PTR(-EINVAL);
0189 }
0190
0191 static inline void firmware_upload_unregister(struct fw_upload *fw_upload)
0192 {
0193 }
0194
0195 #endif
0196
0197 int firmware_request_cache(struct device *device, const char *name);
0198
0199 #endif