LXR linux/include/linux/fpga/fpga-mgr.h

   1/* SPDX-License-Identifier: GPL-2.0 */
   2/*
   3 * FPGA Framework
   4 *
   5 *  Copyright (C) 2013-2016 Altera Corporation
   6 *  Copyright (C) 2017 Intel Corporation
   7 */
   8#ifndef _LINUX_FPGA_MGR_H
   9#define _LINUX_FPGA_MGR_H
  10
  11#include <linux/mutex.h>
  12#include <linux/miscdevice.h>
  13#include <linux/platform_device.h>
  14
  15#define ENCRYPTED_KEY_LEN       64 /* Bytes */
  16
  17struct fpga_manager;
  18struct sg_table;
  19
  20/**
  21 * enum fpga_mgr_states - fpga framework states
  22 * @FPGA_MGR_STATE_UNKNOWN: can't determine state
  23 * @FPGA_MGR_STATE_POWER_OFF: FPGA power is off
  24 * @FPGA_MGR_STATE_POWER_UP: FPGA reports power is up
  25 * @FPGA_MGR_STATE_RESET: FPGA in reset state
  26 * @FPGA_MGR_STATE_FIRMWARE_REQ: firmware request in progress
  27 * @FPGA_MGR_STATE_FIRMWARE_REQ_ERR: firmware request failed
  28 * @FPGA_MGR_STATE_WRITE_INIT: preparing FPGA for programming
  29 * @FPGA_MGR_STATE_WRITE_INIT_ERR: Error during WRITE_INIT stage
  30 * @FPGA_MGR_STATE_WRITE: writing image to FPGA
  31 * @FPGA_MGR_STATE_WRITE_ERR: Error while writing FPGA
  32 * @FPGA_MGR_STATE_WRITE_COMPLETE: Doing post programming steps
  33 * @FPGA_MGR_STATE_WRITE_COMPLETE_ERR: Error during WRITE_COMPLETE
  34 * @FPGA_MGR_STATE_OPERATING: FPGA is programmed and operating
  35 */
  36enum fpga_mgr_states {
  37        /* default FPGA states */
  38        FPGA_MGR_STATE_UNKNOWN,
  39        FPGA_MGR_STATE_POWER_OFF,
  40        FPGA_MGR_STATE_POWER_UP,
  41        FPGA_MGR_STATE_RESET,
  42
  43        /* getting an image for loading */
  44        FPGA_MGR_STATE_FIRMWARE_REQ,
  45        FPGA_MGR_STATE_FIRMWARE_REQ_ERR,
  46
  47        /* write sequence: init, write, complete */
  48        FPGA_MGR_STATE_WRITE_INIT,
  49        FPGA_MGR_STATE_WRITE_INIT_ERR,
  50        FPGA_MGR_STATE_WRITE,
  51        FPGA_MGR_STATE_WRITE_ERR,
  52        FPGA_MGR_STATE_WRITE_COMPLETE,
  53        FPGA_MGR_STATE_WRITE_COMPLETE_ERR,
  54
  55        /* fpga is programmed and operating */
  56        FPGA_MGR_STATE_OPERATING,
  57};
  58
  59/**
  60 * DOC: FPGA Manager flags
  61 *
  62 * Flags used in the &fpga_image_info->flags field
  63 *
  64 * %FPGA_MGR_PARTIAL_RECONFIG: do partial reconfiguration if supported
  65 *
  66 * %FPGA_MGR_EXTERNAL_CONFIG: FPGA has been configured prior to Linux booting
  67 *
  68 * %FPGA_MGR_ENCRYPTED_BITSTREAM: indicates bitstream is encrypted with
  69 *                                device key
  70 *
  71 * %FPGA_MGR_BITSTREAM_LSB_FIRST: SPI bitstream bit order is LSB first
  72 *
  73 * %FPGA_MGR_COMPRESSED_BITSTREAM: FPGA bitstream is compressed
  74 *
  75 * %FPGA_MGR_USERKEY_ENCRYPTED_BITSTREAM: indicates bitstream is encrypted with
  76 *                                        user key
  77 * %FPGA_MGR_DDR_MEM_AUTH_BITSTREAM: do bitstream authentication using DDR
  78 *                                   memory if supported
  79 * %FPGA_MGR_SECURE_MEM_AUTH_BITSTREAM: do bitstream authentication using secure
  80 *                                      memory if supported
  81 */
  82#define FPGA_MGR_PARTIAL_RECONFIG       BIT(0)
  83#define FPGA_MGR_EXTERNAL_CONFIG        BIT(1)
  84#define FPGA_MGR_ENCRYPTED_BITSTREAM    BIT(2)
  85#define FPGA_MGR_BITSTREAM_LSB_FIRST    BIT(3)
  86#define FPGA_MGR_COMPRESSED_BITSTREAM   BIT(4)
  87#define FPGA_MGR_USERKEY_ENCRYPTED_BITSTREAM    BIT(5)
  88#define FPGA_MGR_DDR_MEM_AUTH_BITSTREAM         BIT(6)
  89#define FPGA_MGR_SECURE_MEM_AUTH_BITSTREAM      BIT(7)
  90#define FPGA_MGR_CONFIG_DMA_BUF                 BIT(8)
  91
  92/**
  93 * struct fpga_image_info - information specific to a FPGA image
  94 * @flags: boolean flags as defined above
  95 * @enable_timeout_us: maximum time to enable traffic through bridge (uSec)
  96 * @disable_timeout_us: maximum time to disable traffic through bridge (uSec)
  97 * @config_complete_timeout_us: maximum time for FPGA to switch to operating
  98 *         status in the write_complete op.
  99 * @firmware_name: name of FPGA image firmware file
 100 * @key: key value useful for Encrypted Bitstream loading to read the userkey
 101 * @sgt: scatter/gather table containing FPGA image
 102 * @buf: contiguous buffer containing FPGA image
 103 * @count: size of buf
 104 * @region_id: id of target region
 105 * @dev: device that owns this
 106 * @overlay: Device Tree overlay
 107 */
 108struct fpga_image_info {
 109        u32 flags;
 110        u32 enable_timeout_us;
 111        u32 disable_timeout_us;
 112        u32 config_complete_timeout_us;
 113        char *firmware_name;
 114        char key[ENCRYPTED_KEY_LEN];
 115        struct sg_table *sgt;
 116        const char *buf;
 117        size_t count;
 118        int region_id;
 119        struct device *dev;
 120#ifdef CONFIG_OF
 121        struct device_node *overlay;
 122#endif
 123};
 124
 125/**
 126 * struct fpga_manager_ops - ops for low level fpga manager drivers
 127 * @initial_header_size: Maximum number of bytes that should be passed into write_init
 128 * @state: returns an enum value of the FPGA's state
 129 * @status: returns status of the FPGA, including reconfiguration error code
 130 * @write_init: prepare the FPGA to receive confuration data
 131 * @write: write count bytes of configuration data to the FPGA
 132 * @write_sg: write the scatter list of configuration data to the FPGA
 133 * @write_complete: set FPGA to operating state after writing is done
 134 * @read: optional: read FPGA configuration information
 135 * @fpga_remove: optional: Set FPGA into a specific state during driver remove
 136 * @groups: optional attribute groups.
 137 *
 138 * fpga_manager_ops are the low level functions implemented by a specific
 139 * fpga manager driver.  The optional ones are tested for NULL before being
 140 * called, so leaving them out is fine.
 141 */
 142struct fpga_manager_ops {
 143        size_t initial_header_size;
 144        enum fpga_mgr_states (*state)(struct fpga_manager *mgr);
 145        u64 (*status)(struct fpga_manager *mgr);
 146        int (*write_init)(struct fpga_manager *mgr,
 147                          struct fpga_image_info *info,
 148                          const char *buf, size_t count);
 149        int (*write)(struct fpga_manager *mgr, const char *buf, size_t count);
 150        int (*write_sg)(struct fpga_manager *mgr, struct sg_table *sgt);
 151        int (*write_complete)(struct fpga_manager *mgr,
 152                              struct fpga_image_info *info);
 153        int (*read)(struct fpga_manager *mgr, struct seq_file *s);
 154        void (*fpga_remove)(struct fpga_manager *mgr);
 155        const struct attribute_group **groups;
 156};
 157
 158/* FPGA manager status: Partial/Full Reconfiguration errors */
 159#define FPGA_MGR_STATUS_OPERATION_ERR           BIT(0)
 160#define FPGA_MGR_STATUS_CRC_ERR                 BIT(1)
 161#define FPGA_MGR_STATUS_INCOMPATIBLE_IMAGE_ERR  BIT(2)
 162#define FPGA_MGR_STATUS_IP_PROTOCOL_ERR         BIT(3)
 163#define FPGA_MGR_STATUS_FIFO_OVERFLOW_ERR       BIT(4)
 164#define FPGA_MGR_STATUS_SECURITY_ERR            BIT(5)
 165#define FPGA_MGR_STATUS_DEVICE_INIT_ERR         BIT(6)
 166#define FPGA_MGR_STATUS_SIGNAL_ERR              BIT(7)
 167#define FPGA_MGR_STATUS_HIGH_Z_STATE_ERR        BIT(8)
 168#define FPGA_MGR_STATUS_EOS_ERR                 BIT(9)
 169#define FPGA_MGR_STATUS_FIRMWARE_REQ_ERR        BIT(10)
 170
 171/**
 172 * struct fpga_compat_id - id for compatibility check
 173 *
 174 * @id_h: high 64bit of the compat_id
 175 * @id_l: low 64bit of the compat_id
 176 */
 177struct fpga_compat_id {
 178        u64 id_h;
 179        u64 id_l;
 180};
 181
 182/**
 183 * struct fpga_manager - fpga manager structure
 184 * @name: name of low level fpga manager
 185 * @flags: flags determines the type of Bitstream
 186 * @key: key value useful for Encrypted Bitstream loading to read the userkey
 187 * @dev: fpga manager device
 188 * @ref_mutex: only allows one reference to fpga manager
 189 * @state: state of fpga manager
 190 * @compat_id: FPGA manager id for compatibility check.
 191 * @mops: pointer to struct of fpga manager ops
 192 * @priv: low level driver private date
 193 * @dir: debugfs image directory
 194 */
 195struct fpga_manager {
 196        const char *name;
 197        unsigned long flags;
 198        char key[ENCRYPTED_KEY_LEN + 1];
 199        struct device dev;
 200        struct miscdevice miscdev;
 201        struct dma_buf *dmabuf;
 202        struct mutex ref_mutex;
 203        enum fpga_mgr_states state;
 204        struct fpga_compat_id *compat_id;
 205        const struct fpga_manager_ops *mops;
 206        void *priv;
 207#ifdef CONFIG_FPGA_MGR_DEBUG_FS
 208        struct dentry *dir;
 209#endif
 210};
 211
 212#define to_fpga_manager(d) container_of(d, struct fpga_manager, dev)
 213
 214struct fpga_image_info *fpga_image_info_alloc(struct device *dev);
 215
 216void fpga_image_info_free(struct fpga_image_info *info);
 217
 218int fpga_mgr_load(struct fpga_manager *mgr, struct fpga_image_info *info);
 219
 220int fpga_mgr_lock(struct fpga_manager *mgr);
 221void fpga_mgr_unlock(struct fpga_manager *mgr);
 222
 223struct fpga_manager *of_fpga_mgr_get(struct device_node *node);
 224
 225struct fpga_manager *fpga_mgr_get(struct device *dev);
 226
 227void fpga_mgr_put(struct fpga_manager *mgr);
 228
 229struct fpga_manager *fpga_mgr_create(struct device *dev, const char *name,
 230                                     const struct fpga_manager_ops *mops,
 231                                     void *priv);
 232void fpga_mgr_free(struct fpga_manager *mgr);
 233int fpga_mgr_register(struct fpga_manager *mgr);
 234void fpga_mgr_unregister(struct fpga_manager *mgr);
 235
 236struct fpga_manager *devm_fpga_mgr_create(struct device *dev, const char *name,
 237                                          const struct fpga_manager_ops *mops,
 238                                          void *priv);
 239
 240#define FPGA_IOCTL_LOAD_DMA_BUFF        _IOWR('R', 1, __u32)
 241
 242#endif /*_LINUX_FPGA_MGR_H */
 243