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 = 1 << 2, 60 MOST_CH_SYNC = 1 << 5, 61 }; 62 63 enum mbo_status_flags { 64 /* MBO was processed successfully (data was send or received )*/ 65 MBO_SUCCESS = 0, 66 /* The MBO contains wrong or missing information. */ 67 MBO_E_INVAL, 68 /* MBO was completed as HDM Channel will be closed */ 69 MBO_E_CLOSE, 70 }; 71 72 /** 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. 92 * 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. 95 * 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. 107 */ 108 struct most_channel_capability { 109 u16 direction; 110 u16 data_type; 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; 116 }; 117 118 /** 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 131 * 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. 135 */ 136 struct most_channel_config { 137 enum most_channel_direction direction; 138 enum most_channel_data_type data_type; 139 u16 num_buffers; 140 u16 buffer_size; 141 u16 extra_len; 142 u16 subbuffer_size; 143 u16 packets_per_xact; 144 }; 145 146 /* 147 * struct mbo - MOST Buffer Object. 148 * @context: context for core completion handler 149 * @priv: private data for HDM 150 * 151 * public: documented fields that are used for the communications 152 * between MostCore and HDMs 153 * 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 163 * 164 * The MostCore allocates and initializes the MBO. 165 * 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. 170 * 171 * At the end the MostCore deallocates the MBO or recycles it for further 172 * transfers for the same or different HDM. 173 * 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. 178 * 179 * II. 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. 185 * 186 */ 187 struct mbo { 188 void *context; 189 void *priv; 190 struct list_head list; 191 struct most_interface *ifp; 192 int *num_buffers_ptr; 193 u16 hdm_channel_id; 194 void *virt_address; 195 dma_addr_t bus_address; 196 u16 buffer_length; 197 u16 processed_length; 198 enum mbo_status_flags status; 199 void (*complete)(struct mbo *); 200 }; 201 202 /** 203 * Interface instance description. 204 * 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. 208 * 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 * @priv Private field used by mostcore to store context information. 237 */ 238 struct most_interface { 239 struct module *mod; 240 enum most_interface_type interface; 241 const char *description; 242 int num_channels; 243 struct most_channel_capability *channel_vector; 244 int (*configure)(struct most_interface *iface, int channel_idx, 245 struct most_channel_config *channel_config); 246 int (*enqueue)(struct most_interface *iface, int channel_idx, 247 struct mbo *mbo); 248 int (*poison_channel)(struct most_interface *iface, int channel_idx); 249 void (*request_netinfo)(struct most_interface *iface, int channel_idx); 250 void *priv; 251 }; 252 253 /** 254 * struct most_aim - identifies MOST device driver to mostcore 255 * @name: Driver name 256 * @probe_channel: function for core to notify driver about channel connection 257 * @disconnect_channel: callback function to disconnect a certain channel 258 * @rx_completion: completion handler for received packets 259 * @tx_completion: completion handler for transmitted packets 260 * @context: context pointer to be used by mostcore 261 */ 262 struct most_aim { 263 const char *name; 264 int (*probe_channel)(struct most_interface *iface, int channel_idx, 265 struct most_channel_config *cfg, 266 struct kobject *parent, char *name); 267 int (*disconnect_channel)(struct most_interface *iface, 268 int channel_idx); 269 int (*rx_completion)(struct mbo *mbo); 270 int (*tx_completion)(struct most_interface *iface, int channel_idx); 271 void *context; 272 }; 273 274 /** 275 * most_register_interface - Registers instance of the interface. 276 * @iface: Pointer to the interface instance description. 277 * 278 * Returns a pointer to the kobject of the generated instance. 279 * 280 * Note: HDM has to ensure that any reference held on the kobj is 281 * released before deregistering the interface. 282 */ 283 struct kobject *most_register_interface(struct most_interface *iface); 284 285 /** 286 * Deregisters instance of the interface. 287 * @intf_instance Pointer to the interface instance description. 288 */ 289 void most_deregister_interface(struct most_interface *iface); 290 void most_submit_mbo(struct mbo *mbo); 291 292 /** 293 * most_stop_enqueue - prevents core from enqueing MBOs 294 * @iface: pointer to interface 295 * @channel_idx: channel index 296 */ 297 void most_stop_enqueue(struct most_interface *iface, int channel_idx); 298 299 /** 300 * most_resume_enqueue - allow core to enqueue MBOs again 301 * @iface: pointer to interface 302 * @channel_idx: channel index 303 * 304 * This clears the enqueue halt flag and enqueues all MBOs currently 305 * in wait fifo. 306 */ 307 void most_resume_enqueue(struct most_interface *iface, int channel_idx); 308 int most_register_aim(struct most_aim *aim); 309 int most_deregister_aim(struct most_aim *aim); 310 struct mbo *most_get_mbo(struct most_interface *iface, int channel_idx, 311 struct most_aim *); 312 void most_put_mbo(struct mbo *mbo); 313 int channel_has_mbo(struct most_interface *iface, int channel_idx, 314 struct most_aim *aim); 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 #endif /* MOST_CORE_H_ */ 321