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