include/linux/most.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 /*
0003  * most.h - API for component and adapter drivers
0004  *
0005  * Copyright (C) 2013-2015, Microchip Technology Germany II GmbH & Co. KG
0006  */
0007
0008 #ifndef __MOST_CORE_H__
0009 #define __MOST_CORE_H__
0010
0011 #include <linux/types.h>
0012 #include <linux/device.h>
0013
0014 struct module;
0015 struct interface_private;
0016
0017 /**
0018  * Interface type
0019  */
0020 enum most_interface_type {
0021     ITYPE_LOOPBACK = 1,
0022     ITYPE_I2C,
0023     ITYPE_I2S,
0024     ITYPE_TSI,
0025     ITYPE_HBI,
0026     ITYPE_MEDIALB_DIM,
0027     ITYPE_MEDIALB_DIM2,
0028     ITYPE_USB,
0029     ITYPE_PCIE
0030 };
0031
0032 /**
0033  * Channel direction.
0034  */
0035 enum most_channel_direction {
0036     MOST_CH_RX = 1 << 0,
0037     MOST_CH_TX = 1 << 1,
0038 };
0039
0040 /**
0041  * Channel data type.
0042  */
0043 enum most_channel_data_type {
0044     MOST_CH_CONTROL = 1 << 0,
0045     MOST_CH_ASYNC = 1 << 1,
0046     MOST_CH_ISOC = 1 << 2,
0047     MOST_CH_SYNC = 1 << 5,
0048 };
0049
0050 enum most_status_flags {
0051     /* MBO was processed successfully (data was send or received )*/
0052     MBO_SUCCESS = 0,
0053     /* The MBO contains wrong or missing information.  */
0054     MBO_E_INVAL,
0055     /* MBO was completed as HDM Channel will be closed */
0056     MBO_E_CLOSE,
0057 };
0058
0059 /**
0060  * struct most_channel_capability - Channel capability
0061  * @direction: Supported channel directions.
0062  * The value is bitwise OR-combination of the values from the
0063  * enumeration most_channel_direction. Zero is allowed value and means
0064  * "channel may not be used".
0065  * @data_type: Supported channel data types.
0066  * The value is bitwise OR-combination of the values from the
0067  * enumeration most_channel_data_type. Zero is allowed value and means
0068  * "channel may not be used".
0069  * @num_buffers_packet: Maximum number of buffers supported by this channel
0070  * for packet data types (Async,Control,QoS)
0071  * @buffer_size_packet: Maximum buffer size supported by this channel
0072  * for packet data types (Async,Control,QoS)
0073  * @num_buffers_streaming: Maximum number of buffers supported by this channel
0074  * for streaming data types (Sync,AV Packetized)
0075  * @buffer_size_streaming: Maximum buffer size supported by this channel
0076  * for streaming data types (Sync,AV Packetized)
0077  * @name_suffix: Optional suffix providean by an HDM that is attached to the
0078  * regular channel name.
0079  *
0080  * Describes the capabilities of a MOST channel like supported Data Types
0081  * and directions. This information is provided by an HDM for the MostCore.
0082  *
0083  * The Core creates read only sysfs attribute files in
0084  * /sys/devices/most/mdev#/<channel>/ with the
0085  * following attributes:
0086  *  -available_directions
0087  *  -available_datatypes
0088  *  -number_of_packet_buffers
0089  *  -number_of_stream_buffers
0090  *  -size_of_packet_buffer
0091  *  -size_of_stream_buffer
0092  * where content of each file is a string with all supported properties of this
0093  * very channel attribute.
0094  */
0095 struct most_channel_capability {
0096     u16 direction;
0097     u16 data_type;
0098     u16 num_buffers_packet;
0099     u16 buffer_size_packet;
0100     u16 num_buffers_streaming;
0101     u16 buffer_size_streaming;
0102     const char *name_suffix;
0103 };
0104
0105 /**
0106  * struct most_channel_config - stores channel configuration
0107  * @direction: direction of the channel
0108  * @data_type: data type travelling over this channel
0109  * @num_buffers: number of buffers
0110  * @buffer_size: size of a buffer for AIM.
0111  * Buffer size may be cutted down by HDM in a configure callback
0112  * to match to a given interface and channel type.
0113  * @extra_len: additional buffer space for internal HDM purposes like padding.
0114  * May be set by HDM in a configure callback if needed.
0115  * @subbuffer_size: size of a subbuffer
0116  * @packets_per_xact: number of MOST frames that are packet inside one USB
0117  *            packet. This is USB specific
0118  *
0119  * Describes the configuration for a MOST channel. This information is
0120  * provided from the MostCore to a HDM (like the Medusa PCIe Interface) as a
0121  * parameter of the "configure" function call.
0122  */
0123 struct most_channel_config {
0124     enum most_channel_direction direction;
0125     enum most_channel_data_type data_type;
0126     u16 num_buffers;
0127     u16 buffer_size;
0128     u16 extra_len;
0129     u16 subbuffer_size;
0130     u16 packets_per_xact;
0131     u16 dbr_size;
0132 };
0133
0134 /*
0135  * struct mbo - MOST Buffer Object.
0136  * @context: context for core completion handler
0137  * @priv: private data for HDM
0138  *
0139  *  public: documented fields that are used for the communications
0140  *  between MostCore and HDMs
0141  *
0142  * @list: list head for use by the mbo's current owner
0143  * @ifp: (in) associated interface instance
0144  * @num_buffers_ptr: amount of pool buffers
0145  * @hdm_channel_id: (in) HDM channel instance
0146  * @virt_address: (in) kernel virtual address of the buffer
0147  * @bus_address: (in) bus address of the buffer
0148  * @buffer_length: (in) buffer payload length
0149  * @processed_length: (out) processed length
0150  * @status: (out) transfer status
0151  * @complete: (in) completion routine
0152  *
0153  * The core allocates and initializes the MBO.
0154  *
0155  * The HDM receives MBO for transfer from the core with the call to enqueue().
0156  * The HDM copies the data to- or from the buffer depending on configured
0157  * channel direction, set "processed_length" and "status" and completes
0158  * the transfer procedure by calling the completion routine.
0159  *
0160  * Finally, the MBO is being deallocated or recycled for further
0161  * transfers of the same or a different HDM.
0162  *
0163  * Directions of usage:
0164  * The core driver should never access any MBO fields (even if marked
0165  * as "public") while the MBO is owned by an HDM. The ownership starts with
0166  * the call of enqueue() and ends with the call of its complete() routine.
0167  *
0168  *                  II.
0169  * Every HDM attached to the core driver _must_ ensure that it returns any MBO
0170  * it owns (due to a previous call to enqueue() by the core driver) before it
0171  * de-registers an interface or gets unloaded from the kernel. If this direction
0172  * is violated memory leaks will occur, since the core driver does _not_ track
0173  * MBOs it is currently not in control of.
0174  *
0175  */
0176 struct mbo {
0177     void *context;
0178     void *priv;
0179     struct list_head list;
0180     struct most_interface *ifp;
0181     int *num_buffers_ptr;
0182     u16 hdm_channel_id;
0183     void *virt_address;
0184     dma_addr_t bus_address;
0185     u16 buffer_length;
0186     u16 processed_length;
0187     enum most_status_flags status;
0188     void (*complete)(struct mbo *mbo);
0189 };
0190
0191 /**
0192  * Interface instance description.
0193  *
0194  * Describes an interface of a MOST device the core driver is bound to.
0195  * This structure is allocated and initialized in the HDM. MostCore may not
0196  * modify this structure.
0197  *
0198  * @dev: the actual device
0199  * @mod: module
0200  * @interface Interface type. \sa most_interface_type.
0201  * @description PRELIMINARY.
0202  *   Unique description of the device instance from point of view of the
0203  *   interface in free text form (ASCII).
0204  *   It may be a hexadecimal presentation of the memory address for the MediaLB
0205  *   IP or USB device ID with USB properties for USB interface, etc.
0206  * @num_channels Number of channels and size of the channel_vector.
0207  * @channel_vector Properties of the channels.
0208  *   Array index represents channel ID by the driver.
0209  * @configure Callback to change data type for the channel of the
0210  *   interface instance. May be zero if the instance of the interface is not
0211  *   configurable. Parameter channel_config describes direction and data
0212  *   type for the channel, configured by the higher level. The content of
0213  * @enqueue Delivers MBO to the HDM for processing.
0214  *   After HDM completes Rx- or Tx- operation the processed MBO shall
0215  *   be returned back to the MostCore using completion routine.
0216  *   The reason to get the MBO delivered from the MostCore after the channel
0217  *   is poisoned is the re-opening of the channel by the application.
0218  *   In this case the HDM shall hold MBOs and service the channel as usual.
0219  *   The HDM must be able to hold at least one MBO for each channel.
0220  *   The callback returns a negative value on error, otherwise 0.
0221  * @poison_channel Informs HDM about closing the channel. The HDM shall
0222  *   cancel all transfers and synchronously or asynchronously return
0223  *   all enqueued for this channel MBOs using the completion routine.
0224  *   The callback returns a negative value on error, otherwise 0.
0225  * @request_netinfo: triggers retrieving of network info from the HDM by
0226  *   means of "Message exchange over MDP/MEP"
0227  *   The call of the function request_netinfo with the parameter on_netinfo as
0228  *   NULL prohibits use of the previously obtained function pointer.
0229  * @priv Private field used by mostcore to store context information.
0230  */
0231 struct most_interface {
0232     struct device *dev;
0233     struct device *driver_dev;
0234     struct module *mod;
0235     enum most_interface_type interface;
0236     const char *description;
0237     unsigned int num_channels;
0238     struct most_channel_capability *channel_vector;
0239     void *(*dma_alloc)(struct mbo *mbo, u32 size);
0240     void (*dma_free)(struct mbo *mbo, u32 size);
0241     int (*configure)(struct most_interface *iface, int channel_idx,
0242              struct most_channel_config *channel_config);
0243     int (*enqueue)(struct most_interface *iface, int channel_idx,
0244                struct mbo *mbo);
0245     int (*poison_channel)(struct most_interface *iface, int channel_idx);
0246     void (*request_netinfo)(struct most_interface *iface, int channel_idx,
0247                 void (*on_netinfo)(struct most_interface *iface,
0248                            unsigned char link_stat,
0249                            unsigned char *mac_addr));
0250     void *priv;
0251     struct interface_private *p;
0252 };
0253
0254 /**
0255  * struct most_component - identifies a loadable component for the mostcore
0256  * @list: list_head
0257  * @name: component name
0258  * @probe_channel: function for core to notify driver about channel connection
0259  * @disconnect_channel: callback function to disconnect a certain channel
0260  * @rx_completion: completion handler for received packets
0261  * @tx_completion: completion handler for transmitted packets
0262  */
0263 struct most_component {
0264     struct list_head list;
0265     const char *name;
0266     struct module *mod;
0267     int (*probe_channel)(struct most_interface *iface, int channel_idx,
0268                  struct most_channel_config *cfg, char *name,
0269                  char *param);
0270     int (*disconnect_channel)(struct most_interface *iface,
0271                   int channel_idx);
0272     int (*rx_completion)(struct mbo *mbo);
0273     int (*tx_completion)(struct most_interface *iface, int channel_idx);
0274     int (*cfg_complete)(void);
0275 };
0276
0277 /**
0278  * most_register_interface - Registers instance of the interface.
0279  * @iface: Pointer to the interface instance description.
0280  *
0281  * Returns a pointer to the kobject of the generated instance.
0282  *
0283  * Note: HDM has to ensure that any reference held on the kobj is
0284  * released before deregistering the interface.
0285  */
0286 int most_register_interface(struct most_interface *iface);
0287
0288 /**
0289  * Deregisters instance of the interface.
0290  * @intf_instance Pointer to the interface instance description.
0291  */
0292 void most_deregister_interface(struct most_interface *iface);
0293 void most_submit_mbo(struct mbo *mbo);
0294
0295 /**
0296  * most_stop_enqueue - prevents core from enqueing MBOs
0297  * @iface: pointer to interface
0298  * @channel_idx: channel index
0299  */
0300 void most_stop_enqueue(struct most_interface *iface, int channel_idx);
0301
0302 /**
0303  * most_resume_enqueue - allow core to enqueue MBOs again
0304  * @iface: pointer to interface
0305  * @channel_idx: channel index
0306  *
0307  * This clears the enqueue halt flag and enqueues all MBOs currently
0308  * in wait fifo.
0309  */
0310 void most_resume_enqueue(struct most_interface *iface, int channel_idx);
0311 int most_register_component(struct most_component *comp);
0312 int most_deregister_component(struct most_component *comp);
0313 struct mbo *most_get_mbo(struct most_interface *iface, int channel_idx,
0314              struct most_component *comp);
0315 void most_put_mbo(struct mbo *mbo);
0316 int channel_has_mbo(struct most_interface *iface, int channel_idx,
0317             struct most_component *comp);
0318 int most_start_channel(struct most_interface *iface, int channel_idx,
0319                struct most_component *comp);
0320 int most_stop_channel(struct most_interface *iface, int channel_idx,
0321               struct most_component *comp);
0322 int __init configfs_init(void);
0323 int most_register_configfs_subsys(struct most_component *comp);
0324 void most_deregister_configfs_subsys(struct most_component *comp);
0325 int most_add_link(char *mdev, char *mdev_ch, char *comp_name, char *link_name,
0326           char *comp_param);
0327 int most_remove_link(char *mdev, char *mdev_ch, char *comp_name);
0328 int most_set_cfg_buffer_size(char *mdev, char *mdev_ch, u16 val);
0329 int most_set_cfg_subbuffer_size(char *mdev, char *mdev_ch, u16 val);
0330 int most_set_cfg_dbr_size(char *mdev, char *mdev_ch, u16 val);
0331 int most_set_cfg_num_buffers(char *mdev, char *mdev_ch, u16 val);
0332 int most_set_cfg_datatype(char *mdev, char *mdev_ch, char *buf);
0333 int most_set_cfg_direction(char *mdev, char *mdev_ch, char *buf);
0334 int most_set_cfg_packets_xact(char *mdev, char *mdev_ch, u16 val);
0335 int most_cfg_complete(char *comp_name);
0336 void most_interface_register_notify(const char *mdev_name);
0337 #endif /* MOST_CORE_H_ */