include/linux/firmware.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 #ifndef _LINUX_FIRMWARE_H
   3 #define _LINUX_FIRMWARE_H
   4
   5 #include <linux/types.h>
   6 #include <linux/compiler.h>
   7 #include <linux/gfp.h>
   8
   9 #define FW_ACTION_NOUEVENT 0
  10 #define FW_ACTION_UEVENT 1
  11
  12 struct firmware {
  13         size_t size;
  14         const u8 *data;
  15
  16         /* firmware loader private fields */
  17         void *priv;
  18 };
  19
  20 /**
  21  * enum fw_upload_err - firmware upload error codes
  22  * @FW_UPLOAD_ERR_NONE: returned to indicate success
  23  * @FW_UPLOAD_ERR_HW_ERROR: error signalled by hardware, see kernel log
  24  * @FW_UPLOAD_ERR_TIMEOUT: SW timed out on handshake with HW/firmware
  25  * @FW_UPLOAD_ERR_CANCELED: upload was cancelled by the user
  26  * @FW_UPLOAD_ERR_BUSY: there is an upload operation already in progress
  27  * @FW_UPLOAD_ERR_INVALID_SIZE: invalid firmware image size
  28  * @FW_UPLOAD_ERR_RW_ERROR: read or write to HW failed, see kernel log
  29  * @FW_UPLOAD_ERR_WEAROUT: FLASH device is approaching wear-out, wait & retry
  30  * @FW_UPLOAD_ERR_FW_INVALID: invalid firmware file
  31  * @FW_UPLOAD_ERR_MAX: Maximum error code marker
  32  */
  33 enum fw_upload_err {
  34         FW_UPLOAD_ERR_NONE,
  35         FW_UPLOAD_ERR_HW_ERROR,
  36         FW_UPLOAD_ERR_TIMEOUT,
  37         FW_UPLOAD_ERR_CANCELED,
  38         FW_UPLOAD_ERR_BUSY,
  39         FW_UPLOAD_ERR_INVALID_SIZE,
  40         FW_UPLOAD_ERR_RW_ERROR,
  41         FW_UPLOAD_ERR_WEAROUT,
  42         FW_UPLOAD_ERR_FW_INVALID,
  43         FW_UPLOAD_ERR_MAX
  44 };
  45
  46 struct fw_upload {
  47         void *dd_handle; /* reference to parent driver */
  48         void *priv;      /* firmware loader private fields */
  49 };
  50
  51 /**
  52  * struct fw_upload_ops - device specific operations to support firmware upload
  53  * @prepare:              Required: Prepare secure update
  54  * @write:                Required: The write() op receives the remaining
  55  *                        size to be written and must return the actual
  56  *                        size written or a negative error code. The write()
  57  *                        op will be called repeatedly until all data is
  58  *                        written.
  59  * @poll_complete:        Required: Check for the completion of the
  60  *                        HW authentication/programming process.
  61  * @cancel:               Required: Request cancellation of update. This op
  62  *                        is called from the context of a different kernel
  63  *                        thread, so race conditions need to be considered.
  64  * @cleanup:              Optional: Complements the prepare()
  65  *                        function and is called at the completion
  66  *                        of the update, on success or failure, if the
  67  *                        prepare function succeeded.
  68  */
  69 struct fw_upload_ops {
  70         enum fw_upload_err (*prepare)(struct fw_upload *fw_upload,
  71                                       const u8 *data, u32 size);
  72         enum fw_upload_err (*write)(struct fw_upload *fw_upload,
  73                                     const u8 *data, u32 offset,
  74                                     u32 size, u32 *written);
  75         enum fw_upload_err (*poll_complete)(struct fw_upload *fw_upload);
  76         void (*cancel)(struct fw_upload *fw_upload);
  77         void (*cleanup)(struct fw_upload *fw_upload);
  78 };
  79
  80 struct module;
  81 struct device;
  82
  83 /*
  84  * Built-in firmware functionality is only available if FW_LOADER=y, but not
  85  * FW_LOADER=m
  86  */
  87 #ifdef CONFIG_FW_LOADER
  88 bool firmware_request_builtin(struct firmware *fw, const char *name);
  89 #else
  90 static inline bool firmware_request_builtin(struct firmware *fw,
  91                                             const char *name)
  92 {
  93         return false;
  94 }
  95 #endif
  96
  97 #if IS_REACHABLE(CONFIG_FW_LOADER)
  98 int request_firmware(const struct firmware **fw, const char *name,
  99                      struct device *device);
 100 int firmware_request_nowarn(const struct firmware **fw, const char *name,
 101                             struct device *device);
 102 int firmware_request_platform(const struct firmware **fw, const char *name,
 103                               struct device *device);
 104 int request_firmware_nowait(
 105         struct module *module, bool uevent,
 106         const char *name, struct device *device, gfp_t gfp, void *context,
 107         void (*cont)(const struct firmware *fw, void *context));
 108 int request_firmware_direct(const struct firmware **fw, const char *name,
 109                             struct device *device);
 110 int request_firmware_into_buf(const struct firmware **firmware_p,
 111         const char *name, struct device *device, void *buf, size_t size);
 112 int request_partial_firmware_into_buf(const struct firmware **firmware_p,
 113                                       const char *name, struct device *device,
 114                                       void *buf, size_t size, size_t offset);
 115
 116 void release_firmware(const struct firmware *fw);
 117 #else
 118 static inline int request_firmware(const struct firmware **fw,
 119                                    const char *name,
 120                                    struct device *device)
 121 {
 122         return -EINVAL;
 123 }
 124
 125 static inline int firmware_request_nowarn(const struct firmware **fw,
 126                                           const char *name,
 127                                           struct device *device)
 128 {
 129         return -EINVAL;
 130 }
 131
 132 static inline int firmware_request_platform(const struct firmware **fw,
 133                                             const char *name,
 134                                             struct device *device)
 135 {
 136         return -EINVAL;
 137 }
 138
 139 static inline int request_firmware_nowait(
 140         struct module *module, bool uevent,
 141         const char *name, struct device *device, gfp_t gfp, void *context,
 142         void (*cont)(const struct firmware *fw, void *context))
 143 {
 144         return -EINVAL;
 145 }
 146
 147 static inline void release_firmware(const struct firmware *fw)
 148 {
 149 }
 150
 151 static inline int request_firmware_direct(const struct firmware **fw,
 152                                           const char *name,
 153                                           struct device *device)
 154 {
 155         return -EINVAL;
 156 }
 157
 158 static inline int request_firmware_into_buf(const struct firmware **firmware_p,
 159         const char *name, struct device *device, void *buf, size_t size)
 160 {
 161         return -EINVAL;
 162 }
 163
 164 static inline int request_partial_firmware_into_buf
 165                                         (const struct firmware **firmware_p,
 166                                          const char *name,
 167                                          struct device *device,
 168                                          void *buf, size_t size, size_t offset)
 169 {
 170         return -EINVAL;
 171 }
 172
 173 #endif
 174
 175 #ifdef CONFIG_FW_UPLOAD
 176
 177 struct fw_upload *
 178 firmware_upload_register(struct module *module, struct device *parent,
 179                          const char *name, const struct fw_upload_ops *ops,
 180                          void *dd_handle);
 181 void firmware_upload_unregister(struct fw_upload *fw_upload);
 182
 183 #else
 184
 185 static inline struct fw_upload *
 186 firmware_upload_register(struct module *module, struct device *parent,
 187                          const char *name, const struct fw_upload_ops *ops,
 188                          void *dd_handle)
 189 {
 190                 return ERR_PTR(-EINVAL);
 191 }
 192
 193 static inline void firmware_upload_unregister(struct fw_upload *fw_upload)
 194 {
 195 }
 196
 197 #endif
 198
 199 int firmware_request_cache(struct device *device, const char *name);
 200
 201 #endif