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 mbo_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 extra_len;
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 mbo_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 #define to_most_interface(d) container_of(d, struct most_interface, dev)
255
256 /**
257 * struct core_component - identifies a loadable component for the mostcore
258 * @list: list_head
259 * @name: component name
260 * @probe_channel: function for core to notify driver about channel connection
261 * @disconnect_channel: callback function to disconnect a certain channel
262 * @rx_completion: completion handler for received packets
263 * @tx_completion: completion handler for transmitted packets
264 */
265 struct core_component {
266 struct list_head list;
267 const char *name;
268 int (*probe_channel)(struct most_interface *iface, int channel_idx,
269 struct most_channel_config *cfg, char *name,
270 char *param);
271 int (*disconnect_channel)(struct most_interface *iface,
272 int channel_idx);
273 int (*rx_completion)(struct mbo *mbo);
274 int (*tx_completion)(struct most_interface *iface, int channel_idx);
275 int (*cfg_complete)(void);
276 };
277
278 /**
279 * most_register_interface - Registers instance of the interface.
280 * @iface: Pointer to the interface instance description.
281 *
282 * Returns a pointer to the kobject of the generated instance.
283 *
284 * Note: HDM has to ensure that any reference held on the kobj is
285 * released before deregistering the interface.
286 */
287 int most_register_interface(struct most_interface *iface);
288
289 /**
290 * Deregisters instance of the interface.
291 * @intf_instance Pointer to the interface instance description.
292 */
293 void most_deregister_interface(struct most_interface *iface);
294 void most_submit_mbo(struct mbo *mbo);
295
296 /**
297 * most_stop_enqueue - prevents core from enqueing MBOs
298 * @iface: pointer to interface
299 * @channel_idx: channel index
300 */
301 void most_stop_enqueue(struct most_interface *iface, int channel_idx);
302
303 /**
304 * most_resume_enqueue - allow core to enqueue MBOs again
305 * @iface: pointer to interface
306 * @channel_idx: channel index
307 *
308 * This clears the enqueue halt flag and enqueues all MBOs currently
309 * in wait fifo.
310 */
311 void most_resume_enqueue(struct most_interface *iface, int channel_idx);
312 int most_register_component(struct core_component *comp);
313 int most_deregister_component(struct core_component *comp);
314 struct mbo *most_get_mbo(struct most_interface *iface, int channel_idx,
315 struct core_component *comp);
316 void most_put_mbo(struct mbo *mbo);
317 int channel_has_mbo(struct most_interface *iface, int channel_idx,
318 struct core_component *comp);
319 int most_start_channel(struct most_interface *iface, int channel_idx,
320 struct core_component *comp);
321 int most_stop_channel(struct most_interface *iface, int channel_idx,
322 struct core_component *comp);
323 int __init configfs_init(void);
324 int most_register_configfs_subsys(struct core_component *comp);
325 void most_deregister_configfs_subsys(struct core_component *comp);
326 int most_add_link(char *mdev, char *mdev_ch, char *comp_name, char *link_name,
327 char *comp_param);
328 int most_remove_link(char *mdev, char *mdev_ch, char *comp_name);
329 int most_set_cfg_buffer_size(char *mdev, char *mdev_ch, u16 val);
330 int most_set_cfg_subbuffer_size(char *mdev, char *mdev_ch, u16 val);
331 int most_set_cfg_dbr_size(char *mdev, char *mdev_ch, u16 val);
332 int most_set_cfg_num_buffers(char *mdev, char *mdev_ch, u16 val);
333 int most_set_cfg_datatype(char *mdev, char *mdev_ch, char *buf);
334 int most_set_cfg_direction(char *mdev, char *mdev_ch, char *buf);
335 int most_set_cfg_packets_xact(char *mdev, char *mdev_ch, u16 val);
336 int most_cfg_complete(char *comp_name);
337 void most_interface_register_notify(const char *mdev_name);
338 #endif /* MOST_CORE_H_ */