drivers/staging/most/mostcore/mostcore.h

   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         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: notification that a certain channel isn't available anymore
 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 int 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 void most_put_mbo(struct mbo *mbo);
 312 int most_start_channel(struct most_interface *iface, int channel_idx);
 313 int most_stop_channel(struct most_interface *iface, int channel_idx);
 314
 315
 316 #endif /* MOST_CORE_H_ */