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 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 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