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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.