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 "interface/vchi/vchi_cfg_internal.h" 38 #include "interface/vchi/vchi_common.h" 39 #include "interface/vchi/message_drivers/message.h" 40 41 /****************************************************************************** 42 Global defs 43 *****************************************************************************/ 44 45 // Opaque handle for a connection / service pair 46 typedef struct opaque_vchi_connection_connected_service_handle_t *VCHI_CONNECTION_SERVICE_HANDLE_T; 47 48 // opaque handle to the connection state information 49 typedef struct opaque_vchi_connection_info_t VCHI_CONNECTION_STATE_T; 50 51 typedef struct vchi_connection_t VCHI_CONNECTION_T; 52 53 54 /****************************************************************************** 55 API 56 *****************************************************************************/ 57 58 // Routine to init a connection with a particular low level driver 59 typedef VCHI_CONNECTION_STATE_T * (*VCHI_CONNECTION_INIT_T)( struct vchi_connection_t * connection, 60 const VCHI_MESSAGE_DRIVER_T * driver ); 61 62 // Routine to control CRC enabling at a connection level 63 typedef int32_t (*VCHI_CONNECTION_CRC_CONTROL_T)( VCHI_CONNECTION_STATE_T *state_handle, 64 VCHI_CRC_CONTROL_T control ); 65 66 // Routine to create a service 67 typedef int32_t (*VCHI_CONNECTION_SERVICE_CONNECT_T)( VCHI_CONNECTION_STATE_T *state_handle, 68 int32_t service_id, 69 uint32_t rx_fifo_size, 70 uint32_t tx_fifo_size, 71 int server, 72 VCHI_CALLBACK_T callback, 73 void *callback_param, 74 int32_t want_crc, 75 int32_t want_unaligned_bulk_rx, 76 int32_t want_unaligned_bulk_tx, 77 VCHI_CONNECTION_SERVICE_HANDLE_T *service_handle ); 78 79 // Routine to close a service 80 typedef int32_t (*VCHI_CONNECTION_SERVICE_DISCONNECT_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle ); 81 82 // Routine to queue a message 83 typedef int32_t (*VCHI_CONNECTION_SERVICE_QUEUE_MESSAGE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, 84 const void *data, 85 uint32_t data_size, 86 VCHI_FLAGS_T flags, 87 void *msg_handle ); 88 89 // scatter-gather (vector) message queueing 90 typedef int32_t (*VCHI_CONNECTION_SERVICE_QUEUE_MESSAGEV_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, 91 VCHI_MSG_VECTOR_T *vector, 92 uint32_t count, 93 VCHI_FLAGS_T flags, 94 void *msg_handle ); 95 96 // Routine to dequeue a message 97 typedef int32_t (*VCHI_CONNECTION_SERVICE_DEQUEUE_MESSAGE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, 98 void *data, 99 uint32_t max_data_size_to_read, 100 uint32_t *actual_msg_size, 101 VCHI_FLAGS_T flags ); 102 103 // Routine to peek at a message 104 typedef int32_t (*VCHI_CONNECTION_SERVICE_PEEK_MESSAGE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, 105 void **data, 106 uint32_t *msg_size, 107 VCHI_FLAGS_T flags ); 108 109 // Routine to hold a message 110 typedef int32_t (*VCHI_CONNECTION_SERVICE_HOLD_MESSAGE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, 111 void **data, 112 uint32_t *msg_size, 113 VCHI_FLAGS_T flags, 114 void **message_handle ); 115 116 // Routine to initialise a received message iterator 117 typedef int32_t (*VCHI_CONNECTION_SERVICE_LOOKAHEAD_MESSAGE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, 118 VCHI_MSG_ITER_T *iter, 119 VCHI_FLAGS_T flags ); 120 121 // Routine to release a held message 122 typedef int32_t (*VCHI_CONNECTION_HELD_MSG_RELEASE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, 123 void *message_handle ); 124 125 // Routine to get info on a held message 126 typedef int32_t (*VCHI_CONNECTION_HELD_MSG_INFO_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, 127 void *message_handle, 128 void **data, 129 int32_t *msg_size, 130 uint32_t *tx_timestamp, 131 uint32_t *rx_timestamp ); 132 133 // Routine to check whether the iterator has a next message 134 typedef int32_t (*VCHI_CONNECTION_MSG_ITER_HAS_NEXT_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service, 135 const VCHI_MSG_ITER_T *iter ); 136 137 // Routine to advance the iterator 138 typedef int32_t (*VCHI_CONNECTION_MSG_ITER_NEXT_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service, 139 VCHI_MSG_ITER_T *iter, 140 void **data, 141 uint32_t *msg_size ); 142 143 // Routine to remove the last message returned by the iterator 144 typedef int32_t (*VCHI_CONNECTION_MSG_ITER_REMOVE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service, 145 VCHI_MSG_ITER_T *iter ); 146 147 // Routine to hold the last message returned by the iterator 148 typedef int32_t (*VCHI_CONNECTION_MSG_ITER_HOLD_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service, 149 VCHI_MSG_ITER_T *iter, 150 void **msg_handle ); 151 152 // Routine to transmit bulk data 153 typedef int32_t (*VCHI_CONNECTION_BULK_QUEUE_TRANSMIT_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, 154 const void *data_src, 155 uint32_t data_size, 156 VCHI_FLAGS_T flags, 157 void *bulk_handle ); 158 159 // Routine to receive data 160 typedef int32_t (*VCHI_CONNECTION_BULK_QUEUE_RECEIVE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, 161 void *data_dst, 162 uint32_t data_size, 163 VCHI_FLAGS_T flags, 164 void *bulk_handle ); 165 166 // Routine to report if a server is available 167 typedef int32_t (*VCHI_CONNECTION_SERVER_PRESENT)( VCHI_CONNECTION_STATE_T *state, int32_t service_id, int32_t peer_flags ); 168 169 // Routine to report the number of RX slots available 170 typedef int (*VCHI_CONNECTION_RX_SLOTS_AVAILABLE)( const VCHI_CONNECTION_STATE_T *state ); 171 172 // Routine to report the RX slot size 173 typedef uint32_t (*VCHI_CONNECTION_RX_SLOT_SIZE)( const VCHI_CONNECTION_STATE_T *state ); 174 175 // Callback to indicate that the other side has added a buffer to the rx bulk DMA FIFO 176 typedef void (*VCHI_CONNECTION_RX_BULK_BUFFER_ADDED)(VCHI_CONNECTION_STATE_T *state, 177 int32_t service, 178 uint32_t length, 179 MESSAGE_TX_CHANNEL_T channel, 180 uint32_t channel_params, 181 uint32_t data_length, 182 uint32_t data_offset); 183 184 // Callback to inform a service that a Xon or Xoff message has been received 185 typedef void (*VCHI_CONNECTION_FLOW_CONTROL)(VCHI_CONNECTION_STATE_T *state, int32_t service_id, int32_t xoff); 186 187 // Callback to inform a service that a server available reply message has been received 188 typedef void (*VCHI_CONNECTION_SERVER_AVAILABLE_REPLY)(VCHI_CONNECTION_STATE_T *state, int32_t service_id, uint32_t flags); 189 190 // Callback to indicate that bulk auxiliary messages have arrived 191 typedef void (*VCHI_CONNECTION_BULK_AUX_RECEIVED)(VCHI_CONNECTION_STATE_T *state); 192 193 // Callback to indicate that bulk auxiliary messages have arrived 194 typedef void (*VCHI_CONNECTION_BULK_AUX_TRANSMITTED)(VCHI_CONNECTION_STATE_T *state, void *handle); 195 196 // Callback with all the connection info you require 197 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); 198 199 // Callback to inform of a disconnect 200 typedef void (*VCHI_CONNECTION_DISCONNECT)(VCHI_CONNECTION_STATE_T *state, uint32_t flags); 201 202 // Callback to inform of a power control request 203 typedef void (*VCHI_CONNECTION_POWER_CONTROL)(VCHI_CONNECTION_STATE_T *state, MESSAGE_TX_CHANNEL_T channel, int32_t enable); 204 205 // allocate memory suitably aligned for this connection 206 typedef void * (*VCHI_BUFFER_ALLOCATE)(VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, uint32_t * length); 207 208 // free memory allocated by buffer_allocate 209 typedef void (*VCHI_BUFFER_FREE)(VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, void * address); 210 211 212 /****************************************************************************** 213 System driver struct 214 *****************************************************************************/ 215 216 struct opaque_vchi_connection_api_t 217 { 218 // Routine to init the connection 219 VCHI_CONNECTION_INIT_T init; 220 221 // Connection-level CRC control 222 VCHI_CONNECTION_CRC_CONTROL_T crc_control; 223 224 // Routine to connect to or create service 225 VCHI_CONNECTION_SERVICE_CONNECT_T service_connect; 226 227 // Routine to disconnect from a service 228 VCHI_CONNECTION_SERVICE_DISCONNECT_T service_disconnect; 229 230 // Routine to queue a message 231 VCHI_CONNECTION_SERVICE_QUEUE_MESSAGE_T service_queue_msg; 232 233 // scatter-gather (vector) message queue 234 VCHI_CONNECTION_SERVICE_QUEUE_MESSAGEV_T service_queue_msgv; 235 236 // Routine to dequeue a message 237 VCHI_CONNECTION_SERVICE_DEQUEUE_MESSAGE_T service_dequeue_msg; 238 239 // Routine to peek at a message 240 VCHI_CONNECTION_SERVICE_PEEK_MESSAGE_T service_peek_msg; 241 242 // Routine to hold a message 243 VCHI_CONNECTION_SERVICE_HOLD_MESSAGE_T service_hold_msg; 244 245 // Routine to initialise a received message iterator 246 VCHI_CONNECTION_SERVICE_LOOKAHEAD_MESSAGE_T service_look_ahead_msg; 247 248 // Routine to release a message 249 VCHI_CONNECTION_HELD_MSG_RELEASE_T held_msg_release; 250 251 // Routine to get information on a held message 252 VCHI_CONNECTION_HELD_MSG_INFO_T held_msg_info; 253 254 // Routine to check for next message on iterator 255 VCHI_CONNECTION_MSG_ITER_HAS_NEXT_T msg_iter_has_next; 256 257 // Routine to get next message on iterator 258 VCHI_CONNECTION_MSG_ITER_NEXT_T msg_iter_next; 259 260 // Routine to remove the last message returned by iterator 261 VCHI_CONNECTION_MSG_ITER_REMOVE_T msg_iter_remove; 262 263 // Routine to hold the last message returned by iterator 264 VCHI_CONNECTION_MSG_ITER_HOLD_T msg_iter_hold; 265 266 // Routine to transmit bulk data 267 VCHI_CONNECTION_BULK_QUEUE_TRANSMIT_T bulk_queue_transmit; 268 269 // Routine to receive data 270 VCHI_CONNECTION_BULK_QUEUE_RECEIVE_T bulk_queue_receive; 271 272 // Routine to report the available servers 273 VCHI_CONNECTION_SERVER_PRESENT server_present; 274 275 // Routine to report the number of RX slots available 276 VCHI_CONNECTION_RX_SLOTS_AVAILABLE connection_rx_slots_available; 277 278 // Routine to report the RX slot size 279 VCHI_CONNECTION_RX_SLOT_SIZE connection_rx_slot_size; 280 281 // Callback to indicate that the other side has added a buffer to the rx bulk DMA FIFO 282 VCHI_CONNECTION_RX_BULK_BUFFER_ADDED rx_bulk_buffer_added; 283 284 // Callback to inform a service that a Xon or Xoff message has been received 285 VCHI_CONNECTION_FLOW_CONTROL flow_control; 286 287 // Callback to inform a service that a server available reply message has been received 288 VCHI_CONNECTION_SERVER_AVAILABLE_REPLY server_available_reply; 289 290 // Callback to indicate that bulk auxiliary messages have arrived 291 VCHI_CONNECTION_BULK_AUX_RECEIVED bulk_aux_received; 292 293 // Callback to indicate that a bulk auxiliary message has been transmitted 294 VCHI_CONNECTION_BULK_AUX_TRANSMITTED bulk_aux_transmitted; 295 296 // Callback to provide information about the connection 297 VCHI_CONNECTION_INFO connection_info; 298 299 // Callback to notify that peer has requested disconnect 300 VCHI_CONNECTION_DISCONNECT disconnect; 301 302 // Callback to notify that peer has requested power change 303 VCHI_CONNECTION_POWER_CONTROL power_control; 304 305 // allocate memory suitably aligned for this connection 306 VCHI_BUFFER_ALLOCATE buffer_allocate; 307 308 // free memory allocated by buffer_allocate 309 VCHI_BUFFER_FREE buffer_free; 310 311 }; 312 313 struct vchi_connection_t { 314 const VCHI_CONNECTION_API_T *api; 315 VCHI_CONNECTION_STATE_T *state; 316 #ifdef VCHI_COARSE_LOCKING 317 struct semaphore sem; 318 #endif 319 }; 320 321 322 #endif /* CONNECTION_H_ */ 323 324 /****************************** End of file **********************************/ 325