include/linux/most.h

   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_ */