drivers/staging/vc04_services/interface/vchi/connections/connection.h

   1 /**
   2  * Copyright (c) 2010-2012 Broadcom. All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  * 1. Redistributions of source code must retain the above copyright
   8  *    notice, this list of conditions, and the following disclaimer,
   9  *    without modification.
  10  * 2. Redistributions in binary form must reproduce the above copyright
  11  *    notice, this list of conditions and the following disclaimer in the
  12  *    documentation and/or other materials provided with the distribution.
  13  * 3. The names of the above-listed copyright holders may not be used
  14  *    to endorse or promote products derived from this software without
  15  *    specific prior written permission.
  16  *
  17  * ALTERNATIVELY, this software may be distributed under the terms of the
  18  * GNU General Public License ("GPL") version 2, as published by the Free
  19  * Software Foundation.
  20  *
  21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
  22  * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  23  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  24  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  25  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  26  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  27  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  28  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  29  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  30  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  31  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 #ifndef CONNECTION_H_
  35 #define CONNECTION_H_
  36
  37 #include <linux/kernel.h>
  38 #include <linux/types.h>
  39 #include <linux/semaphore.h>
  40
  41 #include "interface/vchi/vchi_cfg_internal.h"
  42 #include "interface/vchi/vchi_common.h"
  43 #include "interface/vchi/message_drivers/message.h"
  44
  45 /******************************************************************************
  46  Global defs
  47  *****************************************************************************/
  48
  49 // Opaque handle for a connection / service pair
  50 typedef struct opaque_vchi_connection_connected_service_handle_t *VCHI_CONNECTION_SERVICE_HANDLE_T;
  51
  52 // opaque handle to the connection state information
  53 typedef struct opaque_vchi_connection_info_t VCHI_CONNECTION_STATE_T;
  54
  55 typedef struct vchi_connection_t VCHI_CONNECTION_T;
  56
  57
  58 /******************************************************************************
  59  API
  60  *****************************************************************************/
  61
  62 // Routine to init a connection with a particular low level driver
  63 typedef VCHI_CONNECTION_STATE_T * (*VCHI_CONNECTION_INIT_T)( struct vchi_connection_t * connection,
  64                                                              const VCHI_MESSAGE_DRIVER_T * driver );
  65
  66 // Routine to control CRC enabling at a connection level
  67 typedef int32_t (*VCHI_CONNECTION_CRC_CONTROL_T)( VCHI_CONNECTION_STATE_T *state_handle,
  68                                                   VCHI_CRC_CONTROL_T control );
  69
  70 // Routine to create a service
  71 typedef int32_t (*VCHI_CONNECTION_SERVICE_CONNECT_T)( VCHI_CONNECTION_STATE_T *state_handle,
  72                                                       int32_t service_id,
  73                                                       uint32_t rx_fifo_size,
  74                                                       uint32_t tx_fifo_size,
  75                                                       int server,
  76                                                       VCHI_CALLBACK_T callback,
  77                                                       void *callback_param,
  78                                                       int32_t want_crc,
  79                                                       int32_t want_unaligned_bulk_rx,
  80                                                       int32_t want_unaligned_bulk_tx,
  81                                                       VCHI_CONNECTION_SERVICE_HANDLE_T *service_handle );
  82
  83 // Routine to close a service
  84 typedef int32_t (*VCHI_CONNECTION_SERVICE_DISCONNECT_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle );
  85
  86 // Routine to queue a message
  87 typedef int32_t (*VCHI_CONNECTION_SERVICE_QUEUE_MESSAGE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
  88                                                             const void *data,
  89                                                             uint32_t data_size,
  90                                                             VCHI_FLAGS_T flags,
  91                                                             void *msg_handle );
  92
  93 // scatter-gather (vector) message queueing
  94 typedef int32_t (*VCHI_CONNECTION_SERVICE_QUEUE_MESSAGEV_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
  95                                                              VCHI_MSG_VECTOR_T *vector,
  96                                                              uint32_t count,
  97                                                              VCHI_FLAGS_T flags,
  98                                                              void *msg_handle );
  99
 100 // Routine to dequeue a message
 101 typedef int32_t (*VCHI_CONNECTION_SERVICE_DEQUEUE_MESSAGE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
 102                                                               void *data,
 103                                                               uint32_t max_data_size_to_read,
 104                                                               uint32_t *actual_msg_size,
 105                                                               VCHI_FLAGS_T flags );
 106
 107 // Routine to peek at a message
 108 typedef int32_t (*VCHI_CONNECTION_SERVICE_PEEK_MESSAGE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
 109                                                            void **data,
 110                                                            uint32_t *msg_size,
 111                                                            VCHI_FLAGS_T flags );
 112
 113 // Routine to hold a message
 114 typedef int32_t (*VCHI_CONNECTION_SERVICE_HOLD_MESSAGE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
 115                                                            void **data,
 116                                                            uint32_t *msg_size,
 117                                                            VCHI_FLAGS_T flags,
 118                                                            void **message_handle );
 119
 120 // Routine to initialise a received message iterator
 121 typedef int32_t (*VCHI_CONNECTION_SERVICE_LOOKAHEAD_MESSAGE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
 122                                                                 VCHI_MSG_ITER_T *iter,
 123                                                                 VCHI_FLAGS_T flags );
 124
 125 // Routine to release a held message
 126 typedef int32_t (*VCHI_CONNECTION_HELD_MSG_RELEASE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
 127                                                        void *message_handle );
 128
 129 // Routine to get info on a held message
 130 typedef int32_t (*VCHI_CONNECTION_HELD_MSG_INFO_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
 131                                                     void *message_handle,
 132                                                     void **data,
 133                                                     int32_t *msg_size,
 134                                                     uint32_t *tx_timestamp,
 135                                                     uint32_t *rx_timestamp );
 136
 137 // Routine to check whether the iterator has a next message
 138 typedef int32_t (*VCHI_CONNECTION_MSG_ITER_HAS_NEXT_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service,
 139                                                        const VCHI_MSG_ITER_T *iter );
 140
 141 // Routine to advance the iterator
 142 typedef int32_t (*VCHI_CONNECTION_MSG_ITER_NEXT_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service,
 143                                                     VCHI_MSG_ITER_T *iter,
 144                                                     void **data,
 145                                                     uint32_t *msg_size );
 146
 147 // Routine to remove the last message returned by the iterator
 148 typedef int32_t (*VCHI_CONNECTION_MSG_ITER_REMOVE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service,
 149                                                       VCHI_MSG_ITER_T *iter );
 150
 151 // Routine to hold the last message returned by the iterator
 152 typedef int32_t (*VCHI_CONNECTION_MSG_ITER_HOLD_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service,
 153                                                     VCHI_MSG_ITER_T *iter,
 154                                                     void **msg_handle );
 155
 156 // Routine to transmit bulk data
 157 typedef int32_t (*VCHI_CONNECTION_BULK_QUEUE_TRANSMIT_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
 158                                                           const void *data_src,
 159                                                           uint32_t data_size,
 160                                                           VCHI_FLAGS_T flags,
 161                                                           void *bulk_handle );
 162
 163 // Routine to receive data
 164 typedef int32_t (*VCHI_CONNECTION_BULK_QUEUE_RECEIVE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
 165                                                          void *data_dst,
 166                                                          uint32_t data_size,
 167                                                          VCHI_FLAGS_T flags,
 168                                                          void *bulk_handle );
 169
 170 // Routine to report if a server is available
 171 typedef int32_t (*VCHI_CONNECTION_SERVER_PRESENT)( VCHI_CONNECTION_STATE_T *state, int32_t service_id, int32_t peer_flags );
 172
 173 // Routine to report the number of RX slots available
 174 typedef int (*VCHI_CONNECTION_RX_SLOTS_AVAILABLE)( const VCHI_CONNECTION_STATE_T *state );
 175
 176 // Routine to report the RX slot size
 177 typedef uint32_t (*VCHI_CONNECTION_RX_SLOT_SIZE)( const VCHI_CONNECTION_STATE_T *state );
 178
 179 // Callback to indicate that the other side has added a buffer to the rx bulk DMA FIFO
 180 typedef void (*VCHI_CONNECTION_RX_BULK_BUFFER_ADDED)(VCHI_CONNECTION_STATE_T *state,
 181                                                      int32_t service,
 182                                                      uint32_t length,
 183                                                      MESSAGE_TX_CHANNEL_T channel,
 184                                                      uint32_t channel_params,
 185                                                      uint32_t data_length,
 186                                                      uint32_t data_offset);
 187
 188 // Callback to inform a service that a Xon or Xoff message has been received
 189 typedef void (*VCHI_CONNECTION_FLOW_CONTROL)(VCHI_CONNECTION_STATE_T *state, int32_t service_id, int32_t xoff);
 190
 191 // Callback to inform a service that a server available reply message has been received
 192 typedef void (*VCHI_CONNECTION_SERVER_AVAILABLE_REPLY)(VCHI_CONNECTION_STATE_T *state, int32_t service_id, uint32_t flags);
 193
 194 // Callback to indicate that bulk auxiliary messages have arrived
 195 typedef void (*VCHI_CONNECTION_BULK_AUX_RECEIVED)(VCHI_CONNECTION_STATE_T *state);
 196
 197 // Callback to indicate that bulk auxiliary messages have arrived
 198 typedef void (*VCHI_CONNECTION_BULK_AUX_TRANSMITTED)(VCHI_CONNECTION_STATE_T *state, void *handle);
 199
 200 // Callback with all the connection info you require
 201 typedef void (*VCHI_CONNECTION_INFO)(VCHI_CONNECTION_STATE_T *state, uint32_t protocol_version, uint32_t slot_size, uint32_t num_slots, uint32_t min_bulk_size);
 202
 203 // Callback to inform of a disconnect
 204 typedef void (*VCHI_CONNECTION_DISCONNECT)(VCHI_CONNECTION_STATE_T *state, uint32_t flags);
 205
 206 // Callback to inform of a power control request
 207 typedef void (*VCHI_CONNECTION_POWER_CONTROL)(VCHI_CONNECTION_STATE_T *state, MESSAGE_TX_CHANNEL_T channel, int32_t enable);
 208
 209 // allocate memory suitably aligned for this connection
 210 typedef void * (*VCHI_BUFFER_ALLOCATE)(VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, uint32_t * length);
 211
 212 // free memory allocated by buffer_allocate
 213 typedef void   (*VCHI_BUFFER_FREE)(VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, void * address);
 214
 215
 216 /******************************************************************************
 217  System driver struct
 218  *****************************************************************************/
 219
 220 struct opaque_vchi_connection_api_t {
 221    // Routine to init the connection
 222    VCHI_CONNECTION_INIT_T                      init;
 223
 224    // Connection-level CRC control
 225    VCHI_CONNECTION_CRC_CONTROL_T               crc_control;
 226
 227    // Routine to connect to or create service
 228    VCHI_CONNECTION_SERVICE_CONNECT_T           service_connect;
 229
 230    // Routine to disconnect from a service
 231    VCHI_CONNECTION_SERVICE_DISCONNECT_T        service_disconnect;
 232
 233    // Routine to queue a message
 234    VCHI_CONNECTION_SERVICE_QUEUE_MESSAGE_T     service_queue_msg;
 235
 236    // scatter-gather (vector) message queue
 237    VCHI_CONNECTION_SERVICE_QUEUE_MESSAGEV_T    service_queue_msgv;
 238
 239    // Routine to dequeue a message
 240    VCHI_CONNECTION_SERVICE_DEQUEUE_MESSAGE_T   service_dequeue_msg;
 241
 242    // Routine to peek at a message
 243    VCHI_CONNECTION_SERVICE_PEEK_MESSAGE_T      service_peek_msg;
 244
 245    // Routine to hold a message
 246    VCHI_CONNECTION_SERVICE_HOLD_MESSAGE_T      service_hold_msg;
 247
 248    // Routine to initialise a received message iterator
 249    VCHI_CONNECTION_SERVICE_LOOKAHEAD_MESSAGE_T service_look_ahead_msg;
 250
 251    // Routine to release a message
 252    VCHI_CONNECTION_HELD_MSG_RELEASE_T          held_msg_release;
 253
 254    // Routine to get information on a held message
 255    VCHI_CONNECTION_HELD_MSG_INFO_T             held_msg_info;
 256
 257    // Routine to check for next message on iterator
 258    VCHI_CONNECTION_MSG_ITER_HAS_NEXT_T         msg_iter_has_next;
 259
 260    // Routine to get next message on iterator
 261    VCHI_CONNECTION_MSG_ITER_NEXT_T             msg_iter_next;
 262
 263    // Routine to remove the last message returned by iterator
 264    VCHI_CONNECTION_MSG_ITER_REMOVE_T           msg_iter_remove;
 265
 266    // Routine to hold the last message returned by iterator
 267    VCHI_CONNECTION_MSG_ITER_HOLD_T             msg_iter_hold;
 268
 269    // Routine to transmit bulk data
 270    VCHI_CONNECTION_BULK_QUEUE_TRANSMIT_T       bulk_queue_transmit;
 271
 272    // Routine to receive data
 273    VCHI_CONNECTION_BULK_QUEUE_RECEIVE_T        bulk_queue_receive;
 274
 275    // Routine to report the available servers
 276    VCHI_CONNECTION_SERVER_PRESENT              server_present;
 277
 278    // Routine to report the number of RX slots available
 279    VCHI_CONNECTION_RX_SLOTS_AVAILABLE          connection_rx_slots_available;
 280
 281    // Routine to report the RX slot size
 282    VCHI_CONNECTION_RX_SLOT_SIZE                connection_rx_slot_size;
 283
 284    // Callback to indicate that the other side has added a buffer to the rx bulk DMA FIFO
 285    VCHI_CONNECTION_RX_BULK_BUFFER_ADDED        rx_bulk_buffer_added;
 286
 287    // Callback to inform a service that a Xon or Xoff message has been received
 288    VCHI_CONNECTION_FLOW_CONTROL                flow_control;
 289
 290    // Callback to inform a service that a server available reply message has been received
 291    VCHI_CONNECTION_SERVER_AVAILABLE_REPLY      server_available_reply;
 292
 293    // Callback to indicate that bulk auxiliary messages have arrived
 294    VCHI_CONNECTION_BULK_AUX_RECEIVED           bulk_aux_received;
 295
 296    // Callback to indicate that a bulk auxiliary message has been transmitted
 297    VCHI_CONNECTION_BULK_AUX_TRANSMITTED        bulk_aux_transmitted;
 298
 299    // Callback to provide information about the connection
 300    VCHI_CONNECTION_INFO                        connection_info;
 301
 302    // Callback to notify that peer has requested disconnect
 303    VCHI_CONNECTION_DISCONNECT                  disconnect;
 304
 305    // Callback to notify that peer has requested power change
 306    VCHI_CONNECTION_POWER_CONTROL               power_control;
 307
 308    // allocate memory suitably aligned for this connection
 309    VCHI_BUFFER_ALLOCATE                        buffer_allocate;
 310
 311    // free memory allocated by buffer_allocate
 312    VCHI_BUFFER_FREE                            buffer_free;
 313
 314 };
 315
 316 struct vchi_connection_t {
 317    const VCHI_CONNECTION_API_T *api;
 318    VCHI_CONNECTION_STATE_T     *state;
 319 #ifdef VCHI_COARSE_LOCKING
 320    struct semaphore             sem;
 321 #endif
 322 };
 323
 324
 325 #endif /* CONNECTION_H_ */
 326
 327 /****************************** End of file **********************************/