include/linux/ipa_usb.h

   1 /* Copyright (c) 2012-2016, The Linux Foundation. All rights reserved.
   2  *
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License version 2 and
   5  * only version 2 as published by the Free Software Foundation.
   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
  13 #ifndef _IPA_USB_H_
  14 #define _IPA_USB_H_
  15
  16 enum ipa_usb_teth_prot {
  17         IPA_USB_RNDIS = 0,
  18         IPA_USB_ECM = 1,
  19         IPA_USB_RMNET = 2,
  20         IPA_USB_MBIM = 3,
  21         IPA_USB_DIAG = 4,
  22         IPA_USB_MAX_TETH_PROT_SIZE
  23 };
  24
  25 /**
  26  * ipa_usb_teth_params - parameters for RDNIS/ECM initialization API
  27  *
  28  * @host_ethaddr:        host Ethernet address in network order
  29  * @device_ethaddr:      device Ethernet address in network order
  30  */
  31 struct ipa_usb_teth_params {
  32         u8 host_ethaddr[ETH_ALEN];
  33         u8 device_ethaddr[ETH_ALEN];
  34 };
  35
  36 enum ipa_usb_notify_event {
  37         IPA_USB_DEVICE_READY,
  38         IPA_USB_REMOTE_WAKEUP,
  39         IPA_USB_SUSPEND_COMPLETED
  40 };
  41
  42 enum ipa_usb_max_usb_packet_size {
  43         IPA_USB_HIGH_SPEED_512B = 512,
  44         IPA_USB_SUPER_SPEED_1024B = 1024
  45 };
  46
  47 /**
  48  * ipa_usb_teth_prot_params - parameters for connecting RNDIS
  49  *
  50  * @max_xfer_size_bytes_to_dev:   max size of UL packets in bytes
  51  * @max_packet_number_to_dev:     max number of UL aggregated packets
  52  * @max_xfer_size_bytes_to_host:  max size of DL packets in bytes
  53  *
  54  */
  55 struct ipa_usb_teth_prot_params {
  56         u32 max_xfer_size_bytes_to_dev;
  57         u32 max_packet_number_to_dev;
  58         u32 max_xfer_size_bytes_to_host;
  59 };
  60
  61 /**
  62  * ipa_usb_xdci_connect_params - parameters required to start IN, OUT
  63  * channels, and connect RNDIS/ECM/teth_bridge
  64  *
  65  * @max_pkt_size:          high speed or full speed
  66  * @ipa_to_usb_xferrscidx: Transfer Resource Index (XferRscIdx) for IN channel.
  67  *                         The hardware-assigned transfer resource index for the
  68  *                         transfer, which was returned in response to the
  69  *                         Start Transfer command. This field is used for
  70  *                         "Update Transfer" command.
  71  *                         Should be 0 =< ipa_to_usb_xferrscidx <= 127.
  72  * @ipa_to_usb_xferrscidx_valid: true if xferRscIdx should be updated for IN
  73  *                         channel
  74  * @usb_to_ipa_xferrscidx: Transfer Resource Index (XferRscIdx) for OUT channel
  75  *                         Should be 0 =< usb_to_ipa_xferrscidx <= 127.
  76  * @usb_to_ipa_xferrscidx_valid: true if xferRscIdx should be updated for OUT
  77  *                         channel
  78  * @teth_prot:             tethering protocol
  79  * @teth_prot_params:      parameters for connecting the tethering protocol.
  80  * @max_supported_bandwidth_mbps: maximum bandwidth need of the client in Mbps
  81  */
  82 struct ipa_usb_xdci_connect_params {
  83         enum ipa_usb_max_usb_packet_size max_pkt_size;
  84         u8 ipa_to_usb_xferrscidx;
  85         bool ipa_to_usb_xferrscidx_valid;
  86         u8 usb_to_ipa_xferrscidx;
  87         bool usb_to_ipa_xferrscidx_valid;
  88         enum ipa_usb_teth_prot teth_prot;
  89         struct ipa_usb_teth_prot_params teth_prot_params;
  90         u32 max_supported_bandwidth_mbps;
  91 };
  92
  93 /**
  94  * ipa_usb_xdci_chan_scratch - xDCI protocol SW config area of
  95  * channel scratch
  96  *
  97  * @last_trb_addr_iova:  Address (iova LSB - based on alignment restrictions) of
  98  *                       last TRB in queue. Used to identify roll over case
  99  * @const_buffer_size:   TRB buffer size in KB (similar to IPA aggregation
 100  *                       configuration). Must be aligned to max USB Packet Size.
 101  *                       Should be 1 <= const_buffer_size <= 31.
 102  * @depcmd_low_addr:     Used to generate "Update Transfer" command
 103  * @depcmd_hi_addr:      Used to generate "Update Transfer" command.
 104  */
 105 struct ipa_usb_xdci_chan_scratch {
 106         u16 last_trb_addr_iova;
 107         u8 const_buffer_size;
 108         u32 depcmd_low_addr;
 109         u8 depcmd_hi_addr;
 110 };
 111
 112 /**
 113  * ipa_usb_xdci_chan_params - xDCI channel related properties
 114  *
 115  * @client:              type of "client"
 116  * @ipa_ep_cfg:          IPA EP configuration
 117  * @keep_ipa_awake:      when true, IPA will not be clock gated
 118  * @teth_prot:           tethering protocol for which the channel is created
 119  * @gevntcount_low_addr: GEVNCOUNT low address for event scratch
 120  * @gevntcount_hi_addr:  GEVNCOUNT high address for event scratch
 121  * @dir:                 channel direction
 122  * @xfer_ring_len:       length of transfer ring in bytes (must be integral
 123  *                       multiple of transfer element size - 16B for xDCI)
 124  * @xfer_ring_base_addr: physical base address of transfer ring. Address must be
 125  *                       aligned to xfer_ring_len rounded to power of two
 126  * @xfer_scratch:        parameters for xDCI channel scratch
 127  * @xfer_ring_base_addr_iova: IO virtual address mapped to xfer_ring_base_addr
 128  * @data_buff_base_len:  length of data buffer allocated by USB driver
 129  * @data_buff_base_addr: physical base address for the data buffer (where TRBs
 130  *                       points)
 131  * @data_buff_base_addr_iova:  IO virtual address mapped to data_buff_base_addr
 132  *
 133  */
 134 struct ipa_usb_xdci_chan_params {
 135         /* IPA EP params */
 136         enum ipa_client_type client;
 137         struct ipa_ep_cfg ipa_ep_cfg;
 138         bool keep_ipa_awake;
 139         enum ipa_usb_teth_prot teth_prot;
 140         /* event ring params */
 141         u32 gevntcount_low_addr;
 142         u8 gevntcount_hi_addr;
 143         /* transfer ring params */
 144         enum gsi_chan_dir dir;
 145         u16 xfer_ring_len;
 146         u64 xfer_ring_base_addr;
 147         struct ipa_usb_xdci_chan_scratch xfer_scratch;
 148         u64 xfer_ring_base_addr_iova;
 149         u32 data_buff_base_len;
 150         u64 data_buff_base_addr;
 151         u64 data_buff_base_addr_iova;
 152 };
 153
 154 /**
 155  * ipa_usb_chan_out_params - out parameters for channel request
 156  *
 157  * @clnt_hdl:            opaque client handle assigned by IPA to client
 158  * @db_reg_phs_addr_lsb: Physical address of doorbell register where the 32
 159  *                       LSBs of the doorbell value should be written
 160  * @db_reg_phs_addr_msb: Physical address of doorbell register where the 32
 161  *                       MSBs of the doorbell value should be written
 162  *
 163  */
 164 struct ipa_req_chan_out_params {
 165         u32 clnt_hdl;
 166         u32 db_reg_phs_addr_lsb;
 167         u32 db_reg_phs_addr_msb;
 168 };
 169
 170 #ifdef CONFIG_IPA3
 171
 172 /**
 173  * ipa_usb_init_teth_prot - Peripheral should call this function to initialize
 174  * RNDIS/ECM/teth_bridge/DPL, prior to calling ipa_usb_xdci_connect()
 175  *
 176  * @usb_teth_type: tethering protocol type
 177  * @teth_params:   pointer to tethering protocol parameters.
 178  *                 Should be struct ipa_usb_teth_params for RNDIS/ECM,
 179  *                 or NULL for teth_bridge
 180  * @ipa_usb_notify_cb: will be called to notify USB driver on certain events
 181  * @user_data:     cookie used for ipa_usb_notify_cb
 182  *
 183  * @Return 0 on success, negative on failure
 184  */
 185 int ipa_usb_init_teth_prot(enum ipa_usb_teth_prot teth_prot,
 186                            struct ipa_usb_teth_params *teth_params,
 187                            int (*ipa_usb_notify_cb)(enum ipa_usb_notify_event,
 188                            void *),
 189                            void *user_data);
 190
 191 /**
 192  * ipa_usb_xdci_connect - Peripheral should call this function to start IN &
 193  * OUT xDCI channels, and connect RNDIS/ECM/MBIM/RMNET.
 194  * For DPL, only starts IN channel.
 195  *
 196  * @ul_chan_params: parameters for allocating UL xDCI channel. containing
 197  *              required info on event and transfer rings, and IPA EP
 198  *              configuration
 199  * @ul_out_params: [out] opaque client handle assigned by IPA to client & DB
 200  *              registers physical address for UL channel
 201  * @dl_chan_params: parameters for allocating DL xDCI channel. containing
 202  *              required info on event and transfer rings, and IPA EP
 203  *              configuration
 204  * @dl_out_params: [out] opaque client handle assigned by IPA to client & DB
 205  *              registers physical address for DL channel
 206  * @connect_params: handles and scratch params of the required channels,
 207  *              tethering protocol and the tethering protocol parameters.
 208  *
 209  * Note: Should not be called from atomic context
 210  *
 211  * @Return 0 on success, negative on failure
 212  */
 213 int ipa_usb_xdci_connect(struct ipa_usb_xdci_chan_params *ul_chan_params,
 214                          struct ipa_usb_xdci_chan_params *dl_chan_params,
 215                          struct ipa_req_chan_out_params *ul_out_params,
 216                          struct ipa_req_chan_out_params *dl_out_params,
 217                          struct ipa_usb_xdci_connect_params *connect_params);
 218
 219 /**
 220  * ipa_usb_xdci_disconnect - Peripheral should call this function to stop
 221  * IN & OUT xDCI channels
 222  * For DPL, only stops IN channel.
 223  *
 224  * @ul_clnt_hdl:    client handle received from ipa_usb_xdci_connect()
 225  *                  for OUT channel
 226  * @dl_clnt_hdl:    client handle received from ipa_usb_xdci_connect()
 227  *                  for IN channel
 228  * @teth_prot:      tethering protocol
 229  *
 230  * Note: Should not be called from atomic context
 231  *
 232  * @Return 0 on success, negative on failure
 233  */
 234 int ipa_usb_xdci_disconnect(u32 ul_clnt_hdl, u32 dl_clnt_hdl,
 235                             enum ipa_usb_teth_prot teth_prot);
 236
 237 /**
 238  * ipa_usb_deinit_teth_prot - Peripheral should call this function to deinit
 239  * RNDIS/ECM/MBIM/RMNET
 240  *
 241  * @teth_prot: tethering protocol
 242  *
 243  * @Return 0 on success, negative on failure
 244  */
 245 int ipa_usb_deinit_teth_prot(enum ipa_usb_teth_prot teth_prot);
 246
 247 /**
 248  * ipa_usb_xdci_suspend - Peripheral should call this function to suspend
 249  * IN & OUT or DPL xDCI channels
 250  *
 251  * @ul_clnt_hdl: client handle previously obtained from
 252  *               ipa_usb_xdci_connect() for OUT channel
 253  * @dl_clnt_hdl: client handle previously obtained from
 254  *               ipa_usb_xdci_connect() for IN channel
 255  * @teth_prot:   tethering protocol
 256  * @with_remote_wakeup: Does host support remote wakeup?
 257  *
 258  * Note: Should not be called from atomic context
 259  * Note: for DPL, the ul will be ignored as irrelevant
 260  *
 261  * @Return 0 on success, negative on failure
 262  */
 263 int ipa_usb_xdci_suspend(u32 ul_clnt_hdl, u32 dl_clnt_hdl,
 264                          enum ipa_usb_teth_prot teth_prot,
 265                          bool with_remote_wakeup);
 266
 267 /**
 268  * ipa_usb_xdci_resume - Peripheral should call this function to resume
 269  * IN & OUT or DPL xDCI channels
 270  *
 271  * @ul_clnt_hdl:   client handle received from ipa_usb_xdci_connect()
 272  *                 for OUT channel
 273  * @dl_clnt_hdl:   client handle received from ipa_usb_xdci_connect()
 274  *                 for IN channel
 275  * @teth_prot:   tethering protocol
 276  *
 277  * Note: Should not be called from atomic context
 278  * Note: for DPL, the ul will be ignored as irrelevant
 279  *
 280  * @Return 0 on success, negative on failure
 281  */
 282 int ipa_usb_xdci_resume(u32 ul_clnt_hdl, u32 dl_clnt_hdl,
 283                         enum ipa_usb_teth_prot teth_prot);
 284
 285 #else /* CONFIG_IPA3 */
 286
 287 static inline int ipa_usb_init_teth_prot(enum ipa_usb_teth_prot teth_prot,
 288                            struct ipa_usb_teth_params *teth_params,
 289                            int (*ipa_usb_notify_cb)(enum ipa_usb_notify_event,
 290                            void *),
 291                            void *user_data)
 292 {
 293         return -EPERM;
 294 }
 295
 296 static inline int ipa_usb_xdci_connect(
 297                          struct ipa_usb_xdci_chan_params *ul_chan_params,
 298                          struct ipa_usb_xdci_chan_params *dl_chan_params,
 299                          struct ipa_req_chan_out_params *ul_out_params,
 300                          struct ipa_req_chan_out_params *dl_out_params,
 301                          struct ipa_usb_xdci_connect_params *connect_params)
 302 {
 303         return -EPERM;
 304 }
 305
 306 static inline int ipa_usb_xdci_disconnect(u32 ul_clnt_hdl, u32 dl_clnt_hdl,
 307                             enum ipa_usb_teth_prot teth_prot)
 308 {
 309         return -EPERM;
 310 }
 311
 312 static inline int ipa_usb_deinit_teth_prot(enum ipa_usb_teth_prot teth_prot)
 313 {
 314         return -EPERM;
 315 }
 316
 317 static inline int ipa_usb_xdci_suspend(u32 ul_clnt_hdl, u32 dl_clnt_hdl,
 318                          enum ipa_usb_teth_prot teth_prot,
 319                          bool with_remote_wakeup)
 320 {
 321         return -EPERM;
 322 }
 323
 324 static inline int ipa_usb_xdci_resume(u32 ul_clnt_hdl, u32 dl_clnt_hdl,
 325                         enum ipa_usb_teth_prot teth_prot)
 326 {
 327         return -EPERM;
 328 }
 329
 330
 331 #endif /* CONFIG_IPA3 */
 332
 333 #endif /* _IPA_USB_H_ */