2 * mostcore.h - Interface between MostCore,
3 * Hardware Dependent Module (HDM) and Application Interface Module (AIM).
5 * Copyright (C) 2013-2015, Microchip Technology Germany II GmbH & Co. KG
7 * This program is distributed in the hope that it will be useful,
8 * but WITHOUT ANY WARRANTY; without even the implied warranty of
9 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10 * GNU General Public License for more details.
12 * This file is licensed under GPLv2.
17 * Andrey Shvetsov <andrey.shvetsov@k2l.de>
18 * Christian Gromm <christian.gromm@microchip.com>
22 #ifndef __MOST_CORE_H__
23 #define __MOST_CORE_H__
25 #include <linux/types.h>
33 enum most_interface_type {
48 enum most_channel_direction {
56 enum most_channel_data_type {
57 MOST_CH_CONTROL = 1 << 0,
58 MOST_CH_ASYNC = 1 << 1,
59 MOST_CH_ISOC = 1 << 2,
60 MOST_CH_SYNC = 1 << 5,
63 enum mbo_status_flags {
64 /* MBO was processed successfully (data was send or received )*/
66 /* The MBO contains wrong or missing information. */
68 /* MBO was completed as HDM Channel will be closed */
73 * struct most_channel_capability - Channel capability
74 * @direction: Supported channel directions.
75 * The value is bitwise OR-combination of the values from the
76 * enumeration most_channel_direction. Zero is allowed value and means
77 * "channel may not be used".
78 * @data_type: Supported channel data types.
79 * The value is bitwise OR-combination of the values from the
80 * enumeration most_channel_data_type. Zero is allowed value and means
81 * "channel may not be used".
82 * @num_buffer_packet: Maximum number of buffers supported by this channel
83 * for packet data types (Async,Control,QoS)
84 * @buffer_size_packet: Maximum buffer size supported by this channel
85 * for packet data types (Async,Control,QoS)
86 * @num_buffer_streaming: Maximum number of buffers supported by this channel
87 * for streaming data types (Sync,AV Packetized)
88 * @buffer_size_streaming: Maximum buffer size supported by this channel
89 * for streaming data types (Sync,AV Packetized)
90 * @name_suffix: Optional suffix providean by an HDM that is attached to the
91 * regular channel name.
93 * Describes the capabilities of a MostCore channel like supported Data Types
94 * and directions. This information is provided by an HDM for the MostCore.
96 * The Core creates read only sysfs attribute files in
97 * /sys/devices/virtual/most/mostcore/devices/mdev-#/mdev#-ch#/ with the
98 * following attributes:
99 * -available_directions
100 * -available_datatypes
101 * -number_of_packet_buffers
102 * -number_of_stream_buffers
103 * -size_of_packet_buffer
104 * -size_of_stream_buffer
105 * where content of each file is a string with all supported properties of this
106 * very channel attribute.
108 struct most_channel_capability {
111 u16 num_buffers_packet;
112 u16 buffer_size_packet;
113 u16 num_buffers_streaming;
114 u16 buffer_size_streaming;
115 const char *name_suffix;
119 * struct most_channel_config - stores channel configuration
120 * @direction: direction of the channel
121 * @data_type: data type travelling over this channel
122 * @num_buffers: number of buffers
123 * @buffer_size: size of a buffer for AIM.
124 * Buffer size may be cutted down by HDM in a configure callback
125 * to match to a given interface and channel type.
126 * @extra_len: additional buffer space for internal HDM purposes like padding.
127 * May be set by HDM in a configure callback if needed.
128 * @subbuffer_size: size of a subbuffer
129 * @packets_per_xact: number of MOST frames that are packet inside one USB
130 * packet. This is USB specific
132 * Describes the configuration for a MostCore channel. This information is
133 * provided from the MostCore to a HDM (like the Medusa PCIe Interface) as a
134 * parameter of the "configure" function call.
136 struct most_channel_config {
137 enum most_channel_direction direction;
138 enum most_channel_data_type data_type;
143 u16 packets_per_xact;
147 * struct mbo - MOST Buffer Object.
148 * @context: context for core completion handler
149 * @priv: private data for HDM
151 * public: documented fields that are used for the communications
152 * between MostCore and HDMs
154 * @list: list head for use by the mbo's current owner
155 * @ifp: (in) associated interface instance
156 * @hdm_channel_id: (in) HDM channel instance
157 * @virt_address: (in) kernel virtual address of the buffer
158 * @bus_address: (in) bus address of the buffer
159 * @buffer_length: (in) buffer payload length
160 * @processed_length: (out) processed length
161 * @status: (out) transfer status
162 * @complete: (in) completion routine
164 * The MostCore allocates and initializes the MBO.
166 * The HDM receives MBO for transfer from MostCore with the call to enqueue().
167 * The HDM copies the data to- or from the buffer depending on configured
168 * channel direction, set "processed_length" and "status" and completes
169 * the transfer procedure by calling the completion routine.
171 * At the end the MostCore deallocates the MBO or recycles it for further
172 * transfers for the same or different HDM.
174 * Directions of usage:
175 * The core driver should never access any MBO fields (even if marked
176 * as "public") while the MBO is owned by an HDM. The ownership starts with
177 * the call of enqueue() and ends with the call of its complete() routine.
180 * Every HDM attached to the core driver _must_ ensure that it returns any MBO
181 * it owns (due to a previous call to enqueue() by the core driver) before it
182 * de-registers an interface or gets unloaded from the kernel. If this direction
183 * is violated memory leaks will occur, since the core driver does _not_ track
184 * MBOs it is currently not in control of.
190 struct list_head list;
191 struct most_interface *ifp;
192 int *num_buffers_ptr;
195 dma_addr_t bus_address;
197 u16 processed_length;
198 enum mbo_status_flags status;
199 void (*complete)(struct mbo *);
203 * Interface instance description.
205 * Describes one instance of an interface like Medusa PCIe or Vantage USB.
206 * This structure is allocated and initialized in the HDM. MostCore may not
207 * modify this structure.
209 * @interface Interface type. \sa most_interface_type.
210 * @description PRELIMINARY.
211 * Unique description of the device instance from point of view of the
212 * interface in free text form (ASCII).
213 * It may be a hexadecimal presentation of the memory address for the MediaLB
214 * IP or USB device ID with USB properties for USB interface, etc.
215 * @num_channels Number of channels and size of the channel_vector.
216 * @channel_vector Properties of the channels.
217 * Array index represents channel ID by the driver.
218 * @configure Callback to change data type for the channel of the
219 * interface instance. May be zero if the instance of the interface is not
220 * configurable. Parameter channel_config describes direction and data
221 * type for the channel, configured by the higher level. The content of
222 * @enqueue Delivers MBO to the HDM for processing.
223 * After HDM completes Rx- or Tx- operation the processed MBO shall
224 * be returned back to the MostCore using completion routine.
225 * The reason to get the MBO delivered from the MostCore after the channel
226 * is poisoned is the re-opening of the channel by the application.
227 * In this case the HDM shall hold MBOs and service the channel as usual.
228 * The HDM must be able to hold at least one MBO for each channel.
229 * The callback returns a negative value on error, otherwise 0.
230 * @poison_channel Informs HDM about closing the channel. The HDM shall
231 * cancel all transfers and synchronously or asynchronously return
232 * all enqueued for this channel MBOs using the completion routine.
233 * The callback returns a negative value on error, otherwise 0.
234 * @request_netinfo: triggers retrieving of network info from the HDM by
235 * means of "Message exchange over MDP/MEP"
236 * The call of the function request_netinfo with the parameter on_netinfo as
237 * NULL prohibits use of the previously obtained function pointer.
238 * @priv Private field used by mostcore to store context information.
240 struct most_interface {
242 enum most_interface_type interface;
243 const char *description;
245 struct most_channel_capability *channel_vector;
246 int (*configure)(struct most_interface *iface, int channel_idx,
247 struct most_channel_config *channel_config);
248 int (*enqueue)(struct most_interface *iface, int channel_idx,
250 int (*poison_channel)(struct most_interface *iface, int channel_idx);
251 void (*request_netinfo)(struct most_interface *iface, int channel_idx,
252 void (*on_netinfo)(struct most_interface *iface,
253 unsigned char link_stat,
254 unsigned char *mac_addr));
259 * struct most_aim - identifies MOST device driver to mostcore
261 * @probe_channel: function for core to notify driver about channel connection
262 * @disconnect_channel: callback function to disconnect a certain channel
263 * @rx_completion: completion handler for received packets
264 * @tx_completion: completion handler for transmitted packets
265 * @context: context pointer to be used by mostcore
269 int (*probe_channel)(struct most_interface *iface, int channel_idx,
270 struct most_channel_config *cfg,
271 struct kobject *parent, char *name);
272 int (*disconnect_channel)(struct most_interface *iface,
274 int (*rx_completion)(struct mbo *mbo);
275 int (*tx_completion)(struct most_interface *iface, int channel_idx);
280 * most_register_interface - Registers instance of the interface.
281 * @iface: Pointer to the interface instance description.
283 * Returns a pointer to the kobject of the generated instance.
285 * Note: HDM has to ensure that any reference held on the kobj is
286 * released before deregistering the interface.
288 struct kobject *most_register_interface(struct most_interface *iface);
291 * Deregisters instance of the interface.
292 * @intf_instance Pointer to the interface instance description.
294 void most_deregister_interface(struct most_interface *iface);
295 void most_submit_mbo(struct mbo *mbo);
298 * most_stop_enqueue - prevents core from enqueing MBOs
299 * @iface: pointer to interface
300 * @channel_idx: channel index
302 void most_stop_enqueue(struct most_interface *iface, int channel_idx);
305 * most_resume_enqueue - allow core to enqueue MBOs again
306 * @iface: pointer to interface
307 * @channel_idx: channel index
309 * This clears the enqueue halt flag and enqueues all MBOs currently
312 void most_resume_enqueue(struct most_interface *iface, int channel_idx);
313 int most_register_aim(struct most_aim *aim);
314 int most_deregister_aim(struct most_aim *aim);
315 struct mbo *most_get_mbo(struct most_interface *iface, int channel_idx,
317 void most_put_mbo(struct mbo *mbo);
318 int channel_has_mbo(struct most_interface *iface, int channel_idx,
319 struct most_aim *aim);
320 int most_start_channel(struct most_interface *iface, int channel_idx,
322 int most_stop_channel(struct most_interface *iface, int channel_idx,
325 #endif /* MOST_CORE_H_ */