include/linux/qcn_sdio_al.h

   1 /* Copyright (c) 2019 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 _QCN_SDIO_AL_
  14 #define _QCN_SDIO_AL_
  15
  16
  17 /**
  18  * ------------------------------------
  19  * ------- SDIO AL Interface ----------
  20  * ------------------------------------
  21  *
  22  * This file contains the proposed SDIO AL (Abstraction Layer) interface.
  23  * Terminologies:
  24  *      SDIO AL : SDIO host function-1 driver
  25  *      SDIO AL client: Clients of SDIO host function-1 driver.
  26  *                      WLAN, QMI, DIAG etc. are possible clients.
  27  *      Remote SDIO client: SDIO client on device side which implements ADMA
  28  *                          functionality as function-1
  29  */
  30
  31 enum sdio_al_dma_direction {
  32         SDIO_AL_TX,
  33         SDIO_AL_RX,
  34 };
  35
  36 /**
  37  * struct sdio_al_client_handle - unique handler to identify
  38  *                                each SDIO AL (Abstraction Layer) client
  39  *
  40  * @id: unique id for each client
  41  * @block_size: block size
  42  * @func: pointer to sdio_func data structure, some clients may need this.
  43  * @client_priv: This is client priv that can used by client driver.
  44  */
  45 struct sdio_al_client_handle {
  46         int id;
  47         struct sdio_al_client_data *client_data;
  48         unsigned int block_size;
  49         struct sdio_func *func;
  50         void *client_priv;
  51 };
  52
  53 /**
  54  * struct sdio_al_xfer_result - Completed buffer information
  55  *
  56  * @buf_addr: Address of data buffer
  57  *
  58  * @xfer_len: Transfer data length in bytes
  59  *
  60  * @xfer_status: status of transfer, 0 if successful,
  61  *                      negative in case of error
  62  */
  63 struct sdio_al_xfer_result {
  64         void *buf_addr;
  65         size_t xfer_len;
  66         int xfer_status;
  67 };
  68
  69 enum sdio_al_lpm_event {
  70         LPM_ENTER, /* SDIO client will be put to LPM mode soon */
  71         LPM_EXIT,  /* SDIO client has exited LPM mode */
  72 };
  73
  74 /**
  75  * sdio_al_client_data - client data of sdio_al
  76  *
  77  * @name: client name, could be one of the following:
  78  *                  "SDIO_AL_CLIENT_WLAN",
  79  *                  "SDIO_AL_CLIENT_QMI",
  80  *                  "SDIO_AL_CLIENT_DIAG",
  81  *                  "SDIO_AL_CLIENT_TTY"
  82  *
  83  * @probe: This probe function is called by SDIO AL driver when it is ready for
  84  *         SDIO traffic. SDIO AL client must wait for this callback before
  85  *         initiating any transfer over SDIO transport layer.
  86  *
  87  * @remove: This remove function is called by SDIO AL driver when it isn't ready
  88  *          for SDIO traffic. SDIO AL client must stop issuing any transfers
  89  *          after getting this callback, ongoing transfers would be errored out
  90  *          by SDIO AL.
  91  *
  92  * @lpm_notify_cb: callback to notify SDIO AL clients about Low Power modes.
  93  *
  94  */
  95 struct sdio_al_client_data {
  96         const char *name;
  97
  98         int id;
  99
 100         int mode;
 101
 102         int (*probe)(struct sdio_al_client_handle *);
 103
 104         int (*remove)(struct sdio_al_client_handle *);
 105
 106         void (*lpm_notify_cb)(struct sdio_al_client_handle *,
 107                         enum sdio_al_lpm_event event);
 108 };
 109
 110 /**
 111  * sdio_al_channel_handle - channel handle of sdio_al
 112  *
 113  * @id: Channel id unique at the AL layer
 114  *
 115  * @client_data: Client to which this channel belongs
 116  *
 117  */
 118 struct sdio_al_channel_handle {
 119         unsigned int channel_id;
 120
 121         struct sdio_al_channel_data *channel_data;
 122         void *priv;
 123 };
 124
 125 /**
 126  * sdio_al_channel_data - channel data of sdio_al
 127  *
 128  * @name: channel name, could be one of the following:
 129  *                  "SDIO_AL_WLAN_CH0",
 130  *                  "SDIO_AL_WLAN_CH1",
 131  *                  "SDIO_AL_QMI_CH0",
 132  *                  "SDIO_AL_DIAG_CH0",
 133  *                  "SDIO_AL_TTY_CH0"
 134  *
 135  * @client_data: The client driver by which this channel is being claimed
 136  *
 137  * @ul_xfer_cb: UL/TX data transfer callback.
 138  *              SDIO AL client can queue request using sdio_al_queue_transfer()
 139  *              asynchronous API, once request is transported over SDIO
 140  *              transport, SDIO AL calls "ul_xfer_cb" to notify the transfer
 141  complete.
 142  *
 143  * @dl_xfer_cb: DL/RX data transfer callback
 144  *              Once SDIO AL receives requested data from remote SDIO client
 145  *              then SDIO AL invokes "dl_xfer_cb" callback to notify the SDIO
 146  *              AL client.
 147  *
 148  * @dl_data_avail_cb: callback to notify SDIO AL client that it can read
 149  *              specified bytes of data from remote SDIO client, SDIO AL client
 150  *              is then expected call sdio_al_queue_transfer() to read the data.
 151  *              This is optional and if client doesn't provide this callback
 152  *              then SDIO AL would allocate the buffer and SDIO AL
 153  *              client would have to memcpy the buffer in dl_xfer_cb().
 154  *
 155  */
 156 struct sdio_al_channel_data {
 157         const char *name;
 158
 159         struct sdio_al_client_data *client_data;
 160
 161         void (*ul_xfer_cb)(struct sdio_al_channel_handle *,
 162                         struct sdio_al_xfer_result *, void *ctxt);
 163
 164         void (*dl_xfer_cb)(struct sdio_al_channel_handle *,
 165                         struct sdio_al_xfer_result *, void *ctxt);
 166
 167         void (*dl_data_avail_cb)(struct sdio_al_channel_handle *,
 168                         unsigned int len);
 169
 170         void (*dl_meta_data_cb)(struct sdio_al_channel_handle *,
 171                         unsigned int data);
 172 };
 173
 174 /**
 175  * sdio_al_is_ready - API Check to know whether the al driver is ready
 176  * This API can be used to deffer the probe incase of early execution.
 177  *
 178  * @return zero on success and negative value on error.
 179  *
 180  */
 181 int sdio_al_is_ready(void);
 182
 183 /**
 184  * sdio_al_register_client - register as client of sdio AL (function-1 driver)
 185  *  SDIO AL driver would allocate the unique instance of
 186  *  "struct sdio_al_client_handle" and returns to client.
 187  *
 188  * @client_data: pointer to SDIO AL client data (struct sdio_al_client_data)
 189  *
 190  * @return valid sdio_al_client_handler ptr on success, negative value on error.
 191  *
 192  */
 193 struct sdio_al_client_handle *sdio_al_register_client(
 194                 struct sdio_al_client_data *client_data);
 195
 196 /**
 197  * sdio_al_deregister_client - deregisters client from SDIO AL
 198  * (function-1 driver)
 199  *
 200  * @handle: sdio_al client handler
 201  *
 202  */
 203 void sdio_al_deregister_client(struct sdio_al_client_handle *handle);
 204
 205 /**
 206  * sdio_al_register_channel - register a channel for a client of SDIO AL
 207  * SDIO AL driver would allocate a unique instance of the "struct
 208  * sdio_al_channel_handle" and returns to the client.
 209  *
 210  * @client_handle: The client to which the channel shall belong
 211  *
 212  * @channel_data: The channel data which contains the details of the channel
 213  *
 214  * @return valid channel handle in success error on success, error pointer on
 215  * failure
 216  */
 217 struct sdio_al_channel_handle *sdio_al_register_channel(
 218                 struct sdio_al_client_handle *client_handle,
 219                 struct sdio_al_channel_data *client_data);
 220
 221 /**
 222  * sdio_al_deregister_channel - deregister a channel for a client of SDIO AL
 223  *
 224  * @ch_handle: The channel handle which needs to deregistered
 225  *
 226  * @return none
 227  */
 228 void sdio_al_deregister_channel(struct sdio_al_channel_handle *ch_handle);
 229
 230
 231 /**
 232  * sdio_al_queue_transfer_async - Queue asynchronous data transfer request
 233  * All transfers are asynchronous transfers, SDIO AL will call
 234  * ul_xfer_cb or dl_xfer_cb callback to nofity completion to SDIO AL client.
 235  *
 236  * @ch_handle: sdio_al channel handle
 237  *
 238  * @dir: Data direction (DMA_TO_DEVICE for TX, DMA_FROM_DEVICE for RX)
 239  *
 240  * @buf: Data buffer
 241  *
 242  * @len: Size in bytes
 243  *
 244  * @priority: set any non-zero value for higher priority, 0 for normal priority
 245  *            All SDIO AL clients except WLAN client is expected to use normal
 246  *            priority.
 247  *
 248  * @return 0 on success, non-zero in case of error
 249  */
 250 int sdio_al_queue_transfer_async(struct sdio_al_channel_handle *handle,
 251                 enum sdio_al_dma_direction dir,
 252                 void *buf, size_t len, int priority, void *ctxt);
 253
 254 /**
 255  * sdio_al_queue_transfer - Queue synchronous data transfer request
 256  * In constrast to asynchronous transfer API sdio_al_queue_transfer(), this
 257  * API will completely the request synchronously. If there is no outstanding
 258  * request at SDIO AL Layer, request will be immediately initiated on SDIO bus.
 259  *
 260  * @ch_handle: sdio_al channel handle
 261  *
 262  * @dir: Data direction (DMA_TO_DEVICE for TX, DMA_FROM_DEVICE for RX)
 263  *
 264  * @buf: Data buffer
 265  *
 266  * @len: Size in bytes
 267  *
 268  * @priority: set any non-zero value for higher priority, 0 for normal priority
 269  *            All SDIO AL clients except WLAN client is expected to use normal
 270  *            priority.
 271  *
 272  * @return 0 on success, non-zero in case of error
 273  */
 274 int sdio_al_queue_transfer(struct sdio_al_channel_handle *ch_handle,
 275                 enum sdio_al_dma_direction dir,
 276                 void *buf, size_t len, int priority);
 277
 278
 279 /**
 280  * sdio_al_meta_transfer - Queue synchronous data transfer request
 281  * In constrast to asynchronous transfer API sdio_al_queue_transfer(), this
 282  * API will completely the request synchronously. If there is no outstanding
 283  * request at SDIO AL Layer, request will be immediately initiated on SDIO bus.
 284  *
 285  * @ch_handle: sdio_al channel handle
 286  *
 287  * @data: Meta data to be transferred
 288  *
 289  * @return 0 on success, non-zero in case of error
 290  */
 291 int sdio_al_meta_transfer(struct sdio_al_channel_handle *ch_handle,
 292                 unsigned int data, unsigned int trans);
 293
 294 extern void qcn_sdio_client_probe_complete(int id);
 295 int qcn_sdio_card_state(bool enable);
 296 #endif /* _QCN_SDIO_AL_ */