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