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