fpga-mgr.h 6.6 KB

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