1 /* 2 * mostcore.h - Interface between MostCore, 3 * Hardware Dependent Module (HDM) and Application Interface Module (AIM). 4 * 5 * Copyright (C) 2013-2015, Microchip Technology Germany II GmbH & Co. KG 6 * 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. 11 * 12 * This file is licensed under GPLv2. 13 */ 14 15 /* 16 * Authors: 17 * Andrey Shvetsov <andrey.shvetsov@k2l.de> 18 * Christian Gromm <christian.gromm@microchip.com> 19 * Sebastian Graf 20 */ 21 22 #ifndef __MOST_CORE_H__ 23 #define __MOST_CORE_H__ 24 25 #include <linux/types.h> 26 27 struct kobject; 28 struct module; 29 30 /** 31 * Interface type 32 */ 33 enum most_interface_type { 34 ITYPE_LOOPBACK = 1, 35 ITYPE_I2C, 36 ITYPE_I2S, 37 ITYPE_TSI, 38 ITYPE_HBI, 39 ITYPE_MEDIALB_DIM, 40 ITYPE_MEDIALB_DIM2, 41 ITYPE_USB, 42 ITYPE_PCIE 43 }; 44 45 /** 46 * Channel direction. 47 */ 48 enum most_channel_direction { 49 MOST_CH_RX = 1 << 0, 50 MOST_CH_TX = 1 << 1, 51 }; 52 53 /** 54 * Channel data type. 55 */ 56 enum most_channel_data_type { 57 MOST_CH_CONTROL = 1 << 0, 58 MOST_CH_ASYNC = 1 << 1, 59 MOST_CH_ISOC_AVP = 1 << 2, 60 MOST_CH_SYNC = 1 << 5, 61 }; 62 63 64 enum mbo_status_flags { 65 /* MBO was processed successfully (data was send or received )*/ 66 MBO_SUCCESS = 0, 67 /* The MBO contains wrong or missing information. */ 68 MBO_E_INVAL, 69 /* MBO was completed as HDM Channel will be closed */ 70 MBO_E_CLOSE, 71 }; 72 73 /** 74 * struct most_channel_capability - Channel capability 75 * @direction: Supported channel directions. 76 * The value is bitwise OR-combination of the values from the 77 * enumeration most_channel_direction. Zero is allowed value and means 78 * "channel may not be used". 79 * @data_type: Supported channel data types. 80 * The value is bitwise OR-combination of the values from the 81 * enumeration most_channel_data_type. Zero is allowed value and means 82 * "channel may not be used". 83 * @num_buffer_packet: Maximum number of buffers supported by this channel 84 * for packet data types (Async,Control,QoS) 85 * @buffer_size_packet: Maximum buffer size supported by this channel 86 * for packet data types (Async,Control,QoS) 87 * @num_buffer_streaming: Maximum number of buffers supported by this channel 88 * for streaming data types (Sync,AV Packetized) 89 * @buffer_size_streaming: Maximum buffer size supported by this channel 90 * for streaming data types (Sync,AV Packetized) 91 * @name_suffix: Optional suffix providean by an HDM that is attached to the 92 * regular channel name. 93 * 94 * Describes the capabilities of a MostCore channel like supported Data Types 95 * and directions. This information is provided by an HDM for the MostCore. 96 * 97 * The Core creates read only sysfs attribute files in 98 * /sys/devices/virtual/most/mostcore/devices/mdev-#/mdev#-ch#/ with the 99 * following attributes: 100 * -available_directions 101 * -available_datatypes 102 * -number_of_packet_buffers 103 * -number_of_stream_buffers 104 * -size_of_packet_buffer 105 * -size_of_stream_buffer 106 * where content of each file is a string with all supported properties of this 107 * very channel attribute. 108 */ 109 struct most_channel_capability { 110 u16 direction; 111 u16 data_type; 112 u16 num_buffers_packet; 113 u16 buffer_size_packet; 114 u16 num_buffers_streaming; 115 u16 buffer_size_streaming; 116 char *name_suffix; 117 }; 118 119 /** 120 * struct most_channel_config - stores channel configuration 121 * @direction: direction of the channel 122 * @data_type: data type travelling over this channel 123 * @num_buffers: number of buffers 124 * @buffer_size: size of a buffer for AIM. 125 * Buffer size may be cutted down by HDM in a configure callback 126 * to match to a given interface and channel type. 127 * @extra_len: additional buffer space for internal HDM purposes like padding. 128 * May be set by HDM in a configure callback if needed. 129 * @subbuffer_size: size of a subbuffer 130 * @packets_per_xact: number of MOST frames that are packet inside one USB 131 * packet. This is USB specific 132 * 133 * Describes the configuration for a MostCore channel. This information is 134 * provided from the MostCore to a HDM (like the Medusa PCIe Interface) as a 135 * parameter of the "configure" function call. 136 */ 137 struct most_channel_config { 138 enum most_channel_direction direction; 139 enum most_channel_data_type data_type; 140 u16 num_buffers; 141 u16 buffer_size; 142 u16 extra_len; 143 u16 subbuffer_size; 144 u16 packets_per_xact; 145 }; 146 147 /* 148 * struct mbo - MOST Buffer Object. 149 * @context: context for core completion handler 150 * @priv: private data for HDM 151 * 152 * public: documented fields that are used for the communications 153 * between MostCore and HDMs 154 * 155 * @list: list head for use by the mbo's current owner 156 * @ifp: (in) associated interface instance 157 * @hdm_channel_id: (in) HDM channel instance 158 * @virt_address: (in) kernel virtual address of the buffer 159 * @bus_address: (in) bus address of the buffer 160 * @buffer_length: (in) buffer payload length 161 * @processed_length: (out) processed length 162 * @status: (out) transfer status 163 * @complete: (in) completion routine 164 * 165 * The MostCore allocates and initializes the MBO. 166 * 167 * The HDM receives MBO for transfer from MostCore with the call to enqueue(). 168 * The HDM copies the data to- or from the buffer depending on configured 169 * channel direction, set "processed_length" and "status" and completes 170 * the transfer procedure by calling the completion routine. 171 * 172 * At the end the MostCore deallocates the MBO or recycles it for further 173 * transfers for the same or different HDM. 174 * 175 * Directions of usage: 176 * The core driver should never access any MBO fields (even if marked 177 * as "public") while the MBO is owned by an HDM. The ownership starts with 178 * the call of enqueue() and ends with the call of its complete() routine. 179 * 180 * II. 181 * Every HDM attached to the core driver _must_ ensure that it returns any MBO 182 * it owns (due to a previous call to enqueue() by the core driver) before it 183 * de-registers an interface or gets unloaded from the kernel. If this direction 184 * is violated memory leaks will occur, since the core driver does _not_ track 185 * MBOs it is currently not in control of. 186 * 187 */ 188 struct mbo { 189 void *context; 190 void *priv; 191 struct list_head list; 192 struct most_interface *ifp; 193 int *num_buffers_ptr; 194 u16 hdm_channel_id; 195 void *virt_address; 196 dma_addr_t bus_address; 197 u16 buffer_length; 198 u16 processed_length; 199 enum mbo_status_flags status; 200 void (*complete)(struct mbo *); 201 }; 202 203 /** 204 * Interface instance description. 205 * 206 * Describes one instance of an interface like Medusa PCIe or Vantage USB. 207 * This structure is allocated and initialized in the HDM. MostCore may not 208 * modify this structure. 209 * 210 * @interface Interface type. \sa most_interface_type. 211 * @description PRELIMINARY. 212 * Unique description of the device instance from point of view of the 213 * interface in free text form (ASCII). 214 * It may be a hexadecimal presentation of the memory address for the MediaLB 215 * IP or USB device ID with USB properties for USB interface, etc. 216 * @num_channels Number of channels and size of the channel_vector. 217 * @channel_vector Properties of the channels. 218 * Array index represents channel ID by the driver. 219 * @configure Callback to change data type for the channel of the 220 * interface instance. May be zero if the instance of the interface is not 221 * configurable. Parameter channel_config describes direction and data 222 * type for the channel, configured by the higher level. The content of 223 * @enqueue Delivers MBO to the HDM for processing. 224 * After HDM completes Rx- or Tx- operation the processed MBO shall 225 * be returned back to the MostCore using completion routine. 226 * The reason to get the MBO delivered from the MostCore after the channel 227 * is poisoned is the re-opening of the channel by the application. 228 * In this case the HDM shall hold MBOs and service the channel as usual. 229 * The HDM must be able to hold at least one MBO for each channel. 230 * The callback returns a negative value on error, otherwise 0. 231 * @poison_channel Informs HDM about closing the channel. The HDM shall 232 * cancel all transfers and synchronously or asynchronously return 233 * all enqueued for this channel MBOs using the completion routine. 234 * The callback returns a negative value on error, otherwise 0. 235 * @request_netinfo: triggers retrieving of network info from the HDM by 236 * means of "Message exchange over MDP/MEP" 237 * @priv Private field used by mostcore to store context information. 238 */ 239 struct most_interface { 240 struct module *mod; 241 enum most_interface_type interface; 242 const char *description; 243 int num_channels; 244 struct most_channel_capability *channel_vector; 245 int (*configure)(struct most_interface *iface, int channel_idx, 246 struct most_channel_config *channel_config); 247 int (*enqueue)(struct most_interface *iface, int channel_idx, 248 struct mbo *mbo); 249 int (*poison_channel)(struct most_interface *iface, int channel_idx); 250 void (*request_netinfo)(struct most_interface *iface, int channel_idx); 251 void *priv; 252 }; 253 254 /** 255 * struct most_aim - identifies MOST device driver to mostcore 256 * @name: Driver name 257 * @probe_channel: function for core to notify driver about channel connection 258 * @disconnect_channel: callback function to disconnect a certain channel 259 * @rx_completion: completion handler for received packets 260 * @tx_completion: completion handler for transmitted packets 261 * @context: context pointer to be used by mostcore 262 */ 263 struct most_aim { 264 const char *name; 265 int (*probe_channel)(struct most_interface *iface, int channel_idx, 266 struct most_channel_config *cfg, 267 struct kobject *parent, char *name); 268 int (*disconnect_channel)(struct most_interface *iface, 269 int channel_idx); 270 int (*rx_completion)(struct mbo *mbo); 271 int (*tx_completion)(struct most_interface *iface, int channel_idx); 272 void *context; 273 }; 274 275 /** 276 * most_register_interface - Registers instance of the interface. 277 * @iface: Pointer to the interface instance description. 278 * 279 * Returns a pointer to the kobject of the generated instance. 280 * 281 * Note: HDM has to ensure that any reference held on the kobj is 282 * released before deregistering the interface. 283 */ 284 struct kobject *most_register_interface(struct most_interface *iface); 285 286 /** 287 * Deregisters instance of the interface. 288 * @intf_instance Pointer to the interface instance description. 289 */ 290 void most_deregister_interface(struct most_interface *iface); 291 int most_submit_mbo(struct mbo *mbo); 292 293 /** 294 * most_stop_enqueue - prevents core from enqueing MBOs 295 * @iface: pointer to interface 296 * @channel_idx: channel index 297 */ 298 void most_stop_enqueue(struct most_interface *iface, int channel_idx); 299 300 /** 301 * most_resume_enqueue - allow core to enqueue MBOs again 302 * @iface: pointer to interface 303 * @channel_idx: channel index 304 * 305 * This clears the enqueue halt flag and enqueues all MBOs currently 306 * in wait fifo. 307 */ 308 void most_resume_enqueue(struct most_interface *iface, int channel_idx); 309 int most_register_aim(struct most_aim *aim); 310 int most_deregister_aim(struct most_aim *aim); 311 struct mbo *most_get_mbo(struct most_interface *iface, int channel_idx, 312 struct most_aim *); 313 void most_put_mbo(struct mbo *mbo); 314 int channel_has_mbo(struct most_interface *iface, int channel_idx); 315 int most_start_channel(struct most_interface *iface, int channel_idx, 316 struct most_aim *); 317 int most_stop_channel(struct most_interface *iface, int channel_idx, 318 struct most_aim *); 319 320 321 #endif /* MOST_CORE_H_ */ 322