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