338 lines · c
1/* SPDX-License-Identifier: GPL-2.0 */2/*3 * most.h - API for component and adapter drivers4 *5 * Copyright (C) 2013-2015, Microchip Technology Germany II GmbH & Co. KG6 */7 8#ifndef __MOST_CORE_H__9#define __MOST_CORE_H__10 11#include <linux/types.h>12#include <linux/device.h>13 14struct module;15struct interface_private;16 17/**18 * Interface type19 */20enum 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_PCIE30};31 32/**33 * Channel direction.34 */35enum most_channel_direction {36 MOST_CH_RX = 1 << 0,37 MOST_CH_TX = 1 << 1,38};39 40/**41 * Channel data type.42 */43enum 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 50enum 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 capability61 * @direction: Supported channel directions.62 * The value is bitwise OR-combination of the values from the63 * enumeration most_channel_direction. Zero is allowed value and means64 * "channel may not be used".65 * @data_type: Supported channel data types.66 * The value is bitwise OR-combination of the values from the67 * enumeration most_channel_data_type. Zero is allowed value and means68 * "channel may not be used".69 * @num_buffers_packet: Maximum number of buffers supported by this channel70 * for packet data types (Async,Control,QoS)71 * @buffer_size_packet: Maximum buffer size supported by this channel72 * for packet data types (Async,Control,QoS)73 * @num_buffers_streaming: Maximum number of buffers supported by this channel74 * for streaming data types (Sync,AV Packetized)75 * @buffer_size_streaming: Maximum buffer size supported by this channel76 * for streaming data types (Sync,AV Packetized)77 * @name_suffix: Optional suffix providean by an HDM that is attached to the78 * regular channel name.79 *80 * Describes the capabilities of a MOST channel like supported Data Types81 * and directions. This information is provided by an HDM for the MostCore.82 *83 * The Core creates read only sysfs attribute files in84 * /sys/devices/most/mdev#/<channel>/ with the85 * following attributes:86 * -available_directions87 * -available_datatypes88 * -number_of_packet_buffers89 * -number_of_stream_buffers90 * -size_of_packet_buffer91 * -size_of_stream_buffer92 * where content of each file is a string with all supported properties of this93 * very channel attribute.94 */95struct 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 configuration107 * @direction: direction of the channel108 * @data_type: data type travelling over this channel109 * @num_buffers: number of buffers110 * @buffer_size: size of a buffer for AIM.111 * Buffer size may be cutted down by HDM in a configure callback112 * 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 subbuffer116 * @packets_per_xact: number of MOST frames that are packet inside one USB117 * packet. This is USB specific118 *119 * Describes the configuration for a MOST channel. This information is120 * provided from the MostCore to a HDM (like the Medusa PCIe Interface) as a121 * parameter of the "configure" function call.122 */123struct 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 handler137 * @priv: private data for HDM138 *139 * public: documented fields that are used for the communications140 * between MostCore and HDMs141 *142 * @list: list head for use by the mbo's current owner143 * @ifp: (in) associated interface instance144 * @num_buffers_ptr: amount of pool buffers145 * @hdm_channel_id: (in) HDM channel instance146 * @virt_address: (in) kernel virtual address of the buffer147 * @bus_address: (in) bus address of the buffer148 * @buffer_length: (in) buffer payload length149 * @processed_length: (out) processed length150 * @status: (out) transfer status151 * @complete: (in) completion routine152 *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 configured157 * channel direction, set "processed_length" and "status" and completes158 * the transfer procedure by calling the completion routine.159 *160 * Finally, the MBO is being deallocated or recycled for further161 * 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 marked165 * as "public") while the MBO is owned by an HDM. The ownership starts with166 * 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 MBO170 * it owns (due to a previous call to enqueue() by the core driver) before it171 * de-registers an interface or gets unloaded from the kernel. If this direction172 * is violated memory leaks will occur, since the core driver does _not_ track173 * MBOs it is currently not in control of.174 *175 */176struct 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 not196 * modify this structure.197 *198 * @dev: the actual device199 * @mod: module200 * @interface Interface type. \sa most_interface_type.201 * @description PRELIMINARY.202 * Unique description of the device instance from point of view of the203 * interface in free text form (ASCII).204 * It may be a hexadecimal presentation of the memory address for the MediaLB205 * 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 the210 * interface instance. May be zero if the instance of the interface is not211 * configurable. Parameter channel_config describes direction and data212 * type for the channel, configured by the higher level. The content of213 * @enqueue Delivers MBO to the HDM for processing.214 * After HDM completes Rx- or Tx- operation the processed MBO shall215 * be returned back to the MostCore using completion routine.216 * The reason to get the MBO delivered from the MostCore after the channel217 * 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 shall222 * cancel all transfers and synchronously or asynchronously return223 * 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 by226 * means of "Message exchange over MDP/MEP"227 * The call of the function request_netinfo with the parameter on_netinfo as228 * NULL prohibits use of the previously obtained function pointer.229 * @priv Private field used by mostcore to store context information.230 */231struct 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 mostcore256 * @list: list_head257 * @name: component name258 * @probe_channel: function for core to notify driver about channel connection259 * @disconnect_channel: callback function to disconnect a certain channel260 * @rx_completion: completion handler for received packets261 * @tx_completion: completion handler for transmitted packets262 */263struct 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 is284 * released before deregistering the interface.285 */286int 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 */292void most_deregister_interface(struct most_interface *iface);293void most_submit_mbo(struct mbo *mbo);294 295/**296 * most_stop_enqueue - prevents core from enqueing MBOs297 * @iface: pointer to interface298 * @channel_idx: channel index299 */300void most_stop_enqueue(struct most_interface *iface, int channel_idx);301 302/**303 * most_resume_enqueue - allow core to enqueue MBOs again304 * @iface: pointer to interface305 * @channel_idx: channel index306 *307 * This clears the enqueue halt flag and enqueues all MBOs currently308 * in wait fifo.309 */310void most_resume_enqueue(struct most_interface *iface, int channel_idx);311int most_register_component(struct most_component *comp);312int most_deregister_component(struct most_component *comp);313struct mbo *most_get_mbo(struct most_interface *iface, int channel_idx,314 struct most_component *comp);315void most_put_mbo(struct mbo *mbo);316int channel_has_mbo(struct most_interface *iface, int channel_idx,317 struct most_component *comp);318int most_start_channel(struct most_interface *iface, int channel_idx,319 struct most_component *comp);320int most_stop_channel(struct most_interface *iface, int channel_idx,321 struct most_component *comp);322int __init configfs_init(void);323int most_register_configfs_subsys(struct most_component *comp);324void most_deregister_configfs_subsys(struct most_component *comp);325int most_add_link(char *mdev, char *mdev_ch, char *comp_name, char *link_name,326 char *comp_param);327int most_remove_link(char *mdev, char *mdev_ch, char *comp_name);328int most_set_cfg_buffer_size(char *mdev, char *mdev_ch, u16 val);329int most_set_cfg_subbuffer_size(char *mdev, char *mdev_ch, u16 val);330int most_set_cfg_dbr_size(char *mdev, char *mdev_ch, u16 val);331int most_set_cfg_num_buffers(char *mdev, char *mdev_ch, u16 val);332int most_set_cfg_datatype(char *mdev, char *mdev_ch, char *buf);333int most_set_cfg_direction(char *mdev, char *mdev_ch, char *buf);334int most_set_cfg_packets_xact(char *mdev, char *mdev_ch, u16 val);335int most_cfg_complete(char *comp_name);336void most_interface_register_notify(const char *mdev_name);337#endif /* MOST_CORE_H_ */338