Commit | Line | Data |
---|---|---|
0988161a | 1 | /* SPDX-License-Identifier: GPL-2.0 */ |
57562a72 | 2 | /* |
b7937dc4 | 3 | * most.h - API for component and adapter drivers |
57562a72 CG |
4 | * |
5 | * Copyright (C) 2013-2015, Microchip Technology Germany II GmbH & Co. KG | |
57562a72 CG |
6 | */ |
7 | ||
57562a72 CG |
8 | #ifndef __MOST_CORE_H__ |
9 | #define __MOST_CORE_H__ | |
10 | ||
11 | #include <linux/types.h> | |
4d5f022f | 12 | #include <linux/device.h> |
57562a72 | 13 | |
57562a72 | 14 | struct module; |
9136fccf | 15 | struct interface_private; |
57562a72 CG |
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, | |
0540609f | 46 | MOST_CH_ISOC = 1 << 2, |
57562a72 CG |
47 | MOST_CH_SYNC = 1 << 5, |
48 | }; | |
49 | ||
b4e37a5e | 50 | enum most_status_flags { |
57562a72 CG |
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". | |
b7937dc4 | 69 | * @num_buffers_packet: Maximum number of buffers supported by this channel |
57562a72 CG |
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) | |
b7937dc4 | 73 | * @num_buffers_streaming: Maximum number of buffers supported by this channel |
57562a72 CG |
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 | * | |
b7937dc4 | 80 | * Describes the capabilities of a MOST channel like supported Data Types |
57562a72 CG |
81 | * and directions. This information is provided by an HDM for the MostCore. |
82 | * | |
83 | * The Core creates read only sysfs attribute files in | |
b7937dc4 | 84 | * /sys/devices/most/mdev#/<channel>/ with the |
57562a72 CG |
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; | |
602facfd | 102 | const char *name_suffix; |
57562a72 CG |
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 | * | |
b7937dc4 | 119 | * Describes the configuration for a MOST channel. This information is |
57562a72 CG |
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 extra_len; | |
129 | u16 subbuffer_size; | |
130 | u16 packets_per_xact; | |
dbd36d57 | 131 | u16 dbr_size; |
57562a72 CG |
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 | |
b7937dc4 | 144 | * @num_buffers_ptr: amount of pool buffers |
57562a72 CG |
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 | * | |
b7937dc4 | 153 | * The core allocates and initializes the MBO. |
57562a72 | 154 | * |
b7937dc4 | 155 | * The HDM receives MBO for transfer from the core with the call to enqueue(). |
57562a72 CG |
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 | * | |
b7937dc4 CG |
160 | * Finally, the MBO is being deallocated or recycled for further |
161 | * transfers of the same or a different HDM. | |
57562a72 CG |
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; | |
71457d48 | 181 | int *num_buffers_ptr; |
57562a72 CG |
182 | u16 hdm_channel_id; |
183 | void *virt_address; | |
184 | dma_addr_t bus_address; | |
185 | u16 buffer_length; | |
186 | u16 processed_length; | |
b4e37a5e | 187 | enum most_status_flags status; |
c8d4e2e1 | 188 | void (*complete)(struct mbo *mbo); |
57562a72 CG |
189 | }; |
190 | ||
191 | /** | |
192 | * Interface instance description. | |
193 | * | |
b7937dc4 | 194 | * Describes an interface of a MOST device the core driver is bound to. |
57562a72 CG |
195 | * This structure is allocated and initialized in the HDM. MostCore may not |
196 | * modify this structure. | |
197 | * | |
b7937dc4 CG |
198 | * @dev: the actual device |
199 | * @mod: module | |
57562a72 CG |
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" | |
d35bbfaa AS |
227 | * The call of the function request_netinfo with the parameter on_netinfo as |
228 | * NULL prohibits use of the previously obtained function pointer. | |
57562a72 CG |
229 | * @priv Private field used by mostcore to store context information. |
230 | */ | |
231 | struct most_interface { | |
723de0f9 | 232 | struct device *dev; |
69c90cf1 | 233 | struct device *driver_dev; |
57562a72 CG |
234 | struct module *mod; |
235 | enum most_interface_type interface; | |
236 | const char *description; | |
4e6d561d | 237 | unsigned int num_channels; |
57562a72 | 238 | struct most_channel_capability *channel_vector; |
3598cec5 CG |
239 | void *(*dma_alloc)(struct mbo *mbo, u32 size); |
240 | void (*dma_free)(struct mbo *mbo, u32 size); | |
57562a72 CG |
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); | |
d35bbfaa AS |
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)); | |
57562a72 | 250 | void *priv; |
9136fccf | 251 | struct interface_private *p; |
57562a72 CG |
252 | }; |
253 | ||
254 | /** | |
45917e79 | 255 | * struct most_component - identifies a loadable component for the mostcore |
b7937dc4 CG |
256 | * @list: list_head |
257 | * @name: component name | |
57562a72 | 258 | * @probe_channel: function for core to notify driver about channel connection |
b2db4b24 | 259 | * @disconnect_channel: callback function to disconnect a certain channel |
57562a72 CG |
260 | * @rx_completion: completion handler for received packets |
261 | * @tx_completion: completion handler for transmitted packets | |
57562a72 | 262 | */ |
45917e79 | 263 | struct most_component { |
a6404e6e | 264 | struct list_head list; |
57562a72 | 265 | const char *name; |
08283d30 | 266 | struct module *mod; |
57562a72 | 267 | int (*probe_channel)(struct most_interface *iface, int channel_idx, |
dfee92dd CG |
268 | struct most_channel_config *cfg, char *name, |
269 | char *param); | |
57562a72 CG |
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); | |
3d89b273 | 274 | int (*cfg_complete)(void); |
57562a72 CG |
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 | */ | |
4d5f022f | 286 | int most_register_interface(struct most_interface *iface); |
57562a72 CG |
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); | |
a6f9d846 | 293 | void most_submit_mbo(struct mbo *mbo); |
57562a72 CG |
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); | |
45917e79 CG |
311 | int most_register_component(struct most_component *comp); |
312 | int most_deregister_component(struct most_component *comp); | |
71457d48 | 313 | struct mbo *most_get_mbo(struct most_interface *iface, int channel_idx, |
45917e79 | 314 | struct most_component *comp); |
57562a72 | 315 | void most_put_mbo(struct mbo *mbo); |
cdc293d5 | 316 | int channel_has_mbo(struct most_interface *iface, int channel_idx, |
45917e79 | 317 | struct most_component *comp); |
f13f6981 | 318 | int most_start_channel(struct most_interface *iface, int channel_idx, |
45917e79 | 319 | struct most_component *comp); |
f13f6981 | 320 | int most_stop_channel(struct most_interface *iface, int channel_idx, |
45917e79 | 321 | struct most_component *comp); |
3d89b273 | 322 | int __init configfs_init(void); |
45917e79 CG |
323 | int most_register_configfs_subsys(struct most_component *comp); |
324 | void most_deregister_configfs_subsys(struct most_component *comp); | |
3d89b273 CG |
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); | |
acdbb897 | 336 | void most_interface_register_notify(const char *mdev_name); |
57562a72 | 337 | #endif /* MOST_CORE_H_ */ |