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