most.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337
  1. /* SPDX-License-Identifier: GPL-2.0 */
  2. /*
  3. * most.h - API for component and adapter drivers
  4. *
  5. * Copyright (C) 2013-2015, Microchip Technology Germany II GmbH & Co. KG
  6. */
  7. #ifndef __MOST_CORE_H__
  8. #define __MOST_CORE_H__
  9. #include <linux/types.h>
  10. #include <linux/device.h>
  11. struct module;
  12. struct interface_private;
  13. /**
  14. * Interface type
  15. */
  16. enum most_interface_type {
  17. ITYPE_LOOPBACK = 1,
  18. ITYPE_I2C,
  19. ITYPE_I2S,
  20. ITYPE_TSI,
  21. ITYPE_HBI,
  22. ITYPE_MEDIALB_DIM,
  23. ITYPE_MEDIALB_DIM2,
  24. ITYPE_USB,
  25. ITYPE_PCIE
  26. };
  27. /**
  28. * Channel direction.
  29. */
  30. enum most_channel_direction {
  31. MOST_CH_RX = 1 << 0,
  32. MOST_CH_TX = 1 << 1,
  33. };
  34. /**
  35. * Channel data type.
  36. */
  37. enum most_channel_data_type {
  38. MOST_CH_CONTROL = 1 << 0,
  39. MOST_CH_ASYNC = 1 << 1,
  40. MOST_CH_ISOC = 1 << 2,
  41. MOST_CH_SYNC = 1 << 5,
  42. };
  43. enum most_status_flags {
  44. /* MBO was processed successfully (data was send or received )*/
  45. MBO_SUCCESS = 0,
  46. /* The MBO contains wrong or missing information. */
  47. MBO_E_INVAL,
  48. /* MBO was completed as HDM Channel will be closed */
  49. MBO_E_CLOSE,
  50. };
  51. /**
  52. * struct most_channel_capability - Channel capability
  53. * @direction: Supported channel directions.
  54. * The value is bitwise OR-combination of the values from the
  55. * enumeration most_channel_direction. Zero is allowed value and means
  56. * "channel may not be used".
  57. * @data_type: Supported channel data types.
  58. * The value is bitwise OR-combination of the values from the
  59. * enumeration most_channel_data_type. Zero is allowed value and means
  60. * "channel may not be used".
  61. * @num_buffers_packet: Maximum number of buffers supported by this channel
  62. * for packet data types (Async,Control,QoS)
  63. * @buffer_size_packet: Maximum buffer size supported by this channel
  64. * for packet data types (Async,Control,QoS)
  65. * @num_buffers_streaming: Maximum number of buffers supported by this channel
  66. * for streaming data types (Sync,AV Packetized)
  67. * @buffer_size_streaming: Maximum buffer size supported by this channel
  68. * for streaming data types (Sync,AV Packetized)
  69. * @name_suffix: Optional suffix providean by an HDM that is attached to the
  70. * regular channel name.
  71. *
  72. * Describes the capabilities of a MOST channel like supported Data Types
  73. * and directions. This information is provided by an HDM for the MostCore.
  74. *
  75. * The Core creates read only sysfs attribute files in
  76. * /sys/devices/most/mdev#/<channel>/ with the
  77. * following attributes:
  78. * -available_directions
  79. * -available_datatypes
  80. * -number_of_packet_buffers
  81. * -number_of_stream_buffers
  82. * -size_of_packet_buffer
  83. * -size_of_stream_buffer
  84. * where content of each file is a string with all supported properties of this
  85. * very channel attribute.
  86. */
  87. struct most_channel_capability {
  88. u16 direction;
  89. u16 data_type;
  90. u16 num_buffers_packet;
  91. u16 buffer_size_packet;
  92. u16 num_buffers_streaming;
  93. u16 buffer_size_streaming;
  94. const char *name_suffix;
  95. };
  96. /**
  97. * struct most_channel_config - stores channel configuration
  98. * @direction: direction of the channel
  99. * @data_type: data type travelling over this channel
  100. * @num_buffers: number of buffers
  101. * @buffer_size: size of a buffer for AIM.
  102. * Buffer size may be cutted down by HDM in a configure callback
  103. * to match to a given interface and channel type.
  104. * @extra_len: additional buffer space for internal HDM purposes like padding.
  105. * May be set by HDM in a configure callback if needed.
  106. * @subbuffer_size: size of a subbuffer
  107. * @packets_per_xact: number of MOST frames that are packet inside one USB
  108. * packet. This is USB specific
  109. *
  110. * Describes the configuration for a MOST channel. This information is
  111. * provided from the MostCore to a HDM (like the Medusa PCIe Interface) as a
  112. * parameter of the "configure" function call.
  113. */
  114. struct most_channel_config {
  115. enum most_channel_direction direction;
  116. enum most_channel_data_type data_type;
  117. u16 num_buffers;
  118. u16 buffer_size;
  119. u16 extra_len;
  120. u16 subbuffer_size;
  121. u16 packets_per_xact;
  122. u16 dbr_size;
  123. };
  124. /*
  125. * struct mbo - MOST Buffer Object.
  126. * @context: context for core completion handler
  127. * @priv: private data for HDM
  128. *
  129. * public: documented fields that are used for the communications
  130. * between MostCore and HDMs
  131. *
  132. * @list: list head for use by the mbo's current owner
  133. * @ifp: (in) associated interface instance
  134. * @num_buffers_ptr: amount of pool buffers
  135. * @hdm_channel_id: (in) HDM channel instance
  136. * @virt_address: (in) kernel virtual address of the buffer
  137. * @bus_address: (in) bus address of the buffer
  138. * @buffer_length: (in) buffer payload length
  139. * @processed_length: (out) processed length
  140. * @status: (out) transfer status
  141. * @complete: (in) completion routine
  142. *
  143. * The core allocates and initializes the MBO.
  144. *
  145. * The HDM receives MBO for transfer from the core with the call to enqueue().
  146. * The HDM copies the data to- or from the buffer depending on configured
  147. * channel direction, set "processed_length" and "status" and completes
  148. * the transfer procedure by calling the completion routine.
  149. *
  150. * Finally, the MBO is being deallocated or recycled for further
  151. * transfers of the same or a different HDM.
  152. *
  153. * Directions of usage:
  154. * The core driver should never access any MBO fields (even if marked
  155. * as "public") while the MBO is owned by an HDM. The ownership starts with
  156. * the call of enqueue() and ends with the call of its complete() routine.
  157. *
  158. * II.
  159. * Every HDM attached to the core driver _must_ ensure that it returns any MBO
  160. * it owns (due to a previous call to enqueue() by the core driver) before it
  161. * de-registers an interface or gets unloaded from the kernel. If this direction
  162. * is violated memory leaks will occur, since the core driver does _not_ track
  163. * MBOs it is currently not in control of.
  164. *
  165. */
  166. struct mbo {
  167. void *context;
  168. void *priv;
  169. struct list_head list;
  170. struct most_interface *ifp;
  171. int *num_buffers_ptr;
  172. u16 hdm_channel_id;
  173. void *virt_address;
  174. dma_addr_t bus_address;
  175. u16 buffer_length;
  176. u16 processed_length;
  177. enum most_status_flags status;
  178. void (*complete)(struct mbo *mbo);
  179. };
  180. /**
  181. * Interface instance description.
  182. *
  183. * Describes an interface of a MOST device the core driver is bound to.
  184. * This structure is allocated and initialized in the HDM. MostCore may not
  185. * modify this structure.
  186. *
  187. * @dev: the actual device
  188. * @mod: module
  189. * @interface Interface type. \sa most_interface_type.
  190. * @description PRELIMINARY.
  191. * Unique description of the device instance from point of view of the
  192. * interface in free text form (ASCII).
  193. * It may be a hexadecimal presentation of the memory address for the MediaLB
  194. * IP or USB device ID with USB properties for USB interface, etc.
  195. * @num_channels Number of channels and size of the channel_vector.
  196. * @channel_vector Properties of the channels.
  197. * Array index represents channel ID by the driver.
  198. * @configure Callback to change data type for the channel of the
  199. * interface instance. May be zero if the instance of the interface is not
  200. * configurable. Parameter channel_config describes direction and data
  201. * type for the channel, configured by the higher level. The content of
  202. * @enqueue Delivers MBO to the HDM for processing.
  203. * After HDM completes Rx- or Tx- operation the processed MBO shall
  204. * be returned back to the MostCore using completion routine.
  205. * The reason to get the MBO delivered from the MostCore after the channel
  206. * is poisoned is the re-opening of the channel by the application.
  207. * In this case the HDM shall hold MBOs and service the channel as usual.
  208. * The HDM must be able to hold at least one MBO for each channel.
  209. * The callback returns a negative value on error, otherwise 0.
  210. * @poison_channel Informs HDM about closing the channel. The HDM shall
  211. * cancel all transfers and synchronously or asynchronously return
  212. * all enqueued for this channel MBOs using the completion routine.
  213. * The callback returns a negative value on error, otherwise 0.
  214. * @request_netinfo: triggers retrieving of network info from the HDM by
  215. * means of "Message exchange over MDP/MEP"
  216. * The call of the function request_netinfo with the parameter on_netinfo as
  217. * NULL prohibits use of the previously obtained function pointer.
  218. * @priv Private field used by mostcore to store context information.
  219. */
  220. struct most_interface {
  221. struct device *dev;
  222. struct device *driver_dev;
  223. struct module *mod;
  224. enum most_interface_type interface;
  225. const char *description;
  226. unsigned int num_channels;
  227. struct most_channel_capability *channel_vector;
  228. void *(*dma_alloc)(struct mbo *mbo, u32 size);
  229. void (*dma_free)(struct mbo *mbo, u32 size);
  230. int (*configure)(struct most_interface *iface, int channel_idx,
  231. struct most_channel_config *channel_config);
  232. int (*enqueue)(struct most_interface *iface, int channel_idx,
  233. struct mbo *mbo);
  234. int (*poison_channel)(struct most_interface *iface, int channel_idx);
  235. void (*request_netinfo)(struct most_interface *iface, int channel_idx,
  236. void (*on_netinfo)(struct most_interface *iface,
  237. unsigned char link_stat,
  238. unsigned char *mac_addr));
  239. void *priv;
  240. struct interface_private *p;
  241. };
  242. /**
  243. * struct most_component - identifies a loadable component for the mostcore
  244. * @list: list_head
  245. * @name: component name
  246. * @probe_channel: function for core to notify driver about channel connection
  247. * @disconnect_channel: callback function to disconnect a certain channel
  248. * @rx_completion: completion handler for received packets
  249. * @tx_completion: completion handler for transmitted packets
  250. */
  251. struct most_component {
  252. struct list_head list;
  253. const char *name;
  254. struct module *mod;
  255. int (*probe_channel)(struct most_interface *iface, int channel_idx,
  256. struct most_channel_config *cfg, char *name,
  257. char *param);
  258. int (*disconnect_channel)(struct most_interface *iface,
  259. int channel_idx);
  260. int (*rx_completion)(struct mbo *mbo);
  261. int (*tx_completion)(struct most_interface *iface, int channel_idx);
  262. int (*cfg_complete)(void);
  263. };
  264. /**
  265. * most_register_interface - Registers instance of the interface.
  266. * @iface: Pointer to the interface instance description.
  267. *
  268. * Returns a pointer to the kobject of the generated instance.
  269. *
  270. * Note: HDM has to ensure that any reference held on the kobj is
  271. * released before deregistering the interface.
  272. */
  273. int most_register_interface(struct most_interface *iface);
  274. /**
  275. * Deregisters instance of the interface.
  276. * @intf_instance Pointer to the interface instance description.
  277. */
  278. void most_deregister_interface(struct most_interface *iface);
  279. void most_submit_mbo(struct mbo *mbo);
  280. /**
  281. * most_stop_enqueue - prevents core from enqueing MBOs
  282. * @iface: pointer to interface
  283. * @channel_idx: channel index
  284. */
  285. void most_stop_enqueue(struct most_interface *iface, int channel_idx);
  286. /**
  287. * most_resume_enqueue - allow core to enqueue MBOs again
  288. * @iface: pointer to interface
  289. * @channel_idx: channel index
  290. *
  291. * This clears the enqueue halt flag and enqueues all MBOs currently
  292. * in wait fifo.
  293. */
  294. void most_resume_enqueue(struct most_interface *iface, int channel_idx);
  295. int most_register_component(struct most_component *comp);
  296. int most_deregister_component(struct most_component *comp);
  297. struct mbo *most_get_mbo(struct most_interface *iface, int channel_idx,
  298. struct most_component *comp);
  299. void most_put_mbo(struct mbo *mbo);
  300. int channel_has_mbo(struct most_interface *iface, int channel_idx,
  301. struct most_component *comp);
  302. int most_start_channel(struct most_interface *iface, int channel_idx,
  303. struct most_component *comp);
  304. int most_stop_channel(struct most_interface *iface, int channel_idx,
  305. struct most_component *comp);
  306. int __init configfs_init(void);
  307. int most_register_configfs_subsys(struct most_component *comp);
  308. void most_deregister_configfs_subsys(struct most_component *comp);
  309. int most_add_link(char *mdev, char *mdev_ch, char *comp_name, char *link_name,
  310. char *comp_param);
  311. int most_remove_link(char *mdev, char *mdev_ch, char *comp_name);
  312. int most_set_cfg_buffer_size(char *mdev, char *mdev_ch, u16 val);
  313. int most_set_cfg_subbuffer_size(char *mdev, char *mdev_ch, u16 val);
  314. int most_set_cfg_dbr_size(char *mdev, char *mdev_ch, u16 val);
  315. int most_set_cfg_num_buffers(char *mdev, char *mdev_ch, u16 val);
  316. int most_set_cfg_datatype(char *mdev, char *mdev_ch, char *buf);
  317. int most_set_cfg_direction(char *mdev, char *mdev_ch, char *buf);
  318. int most_set_cfg_packets_xact(char *mdev, char *mdev_ch, u16 val);
  319. int most_cfg_complete(char *comp_name);
  320. void most_interface_register_notify(const char *mdev_name);
  321. #endif /* MOST_CORE_H_ */