1/*
2Copyright (c) 2012, Broadcom Europe Ltd
3All rights reserved.
4
5Redistribution and use in source and binary forms, with or without
6modification, are permitted provided that the following conditions are met:
7 * Redistributions of source code must retain the above copyright
8 notice, this list of conditions and the following disclaimer.
9 * Redistributions in binary form must reproduce the above copyright
10 notice, this list of conditions and the following disclaimer in the
11 documentation and/or other materials provided with the distribution.
12 * Neither the name of the copyright holder nor the
13 names of its contributors may be used to endorse or promote products
14 derived from this software without specific prior written permission.
15
16THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
20DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26*/
27
28/*
29 * \file
30 *
31 * \brief Contains the protypes for the interface functions.
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
46typedef struct opaque_vchi_connection_connected_service_handle_t *VCHI_CONNECTION_SERVICE_HANDLE_T;
47
48// opaque handle to the connection state information
49typedef struct opaque_vchi_connection_info_t VCHI_CONNECTION_STATE_T;
50
51typedef 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
59typedef 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
63typedef 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
67typedef int32_t (*VCHI_CONNECTION_SERVICE_CONNECT_T)( VCHI_CONNECTION_STATE_T *state_handle,
68 vcos_fourcc_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 vcos_bool_t want_crc,
75 vcos_bool_t want_unaligned_bulk_rx,
76 vcos_bool_t want_unaligned_bulk_tx,
77 VCHI_CONNECTION_SERVICE_HANDLE_T *service_handle );
78
79// Routine to close a service
80typedef int32_t (*VCHI_CONNECTION_SERVICE_DISCONNECT_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle );
81
82// Routine to queue a message
83typedef 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
90typedef 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
97typedef 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
104typedef 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
110typedef 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
117typedef 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
122typedef 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
126typedef 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
134typedef vcos_bool_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
138typedef 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
144typedef 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
148typedef 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
153typedef 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
160typedef 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
167typedef int32_t (*VCHI_CONNECTION_SERVER_PRESENT)( VCHI_CONNECTION_STATE_T *state, vcos_fourcc_t service_id, int32_t peer_flags );
168
169// Routine to report the number of RX slots available
170typedef int (*VCHI_CONNECTION_RX_SLOTS_AVAILABLE)( const VCHI_CONNECTION_STATE_T *state );
171
172// Routine to report the RX slot size
173typedef 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
176typedef void (*VCHI_CONNECTION_RX_BULK_BUFFER_ADDED)(VCHI_CONNECTION_STATE_T *state,
177 vcos_fourcc_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
185typedef void (*VCHI_CONNECTION_FLOW_CONTROL)(VCHI_CONNECTION_STATE_T *state, vcos_fourcc_t service_id, int32_t xoff);
186
187// Callback to inform a service that a server available reply message has been received
188typedef void (*VCHI_CONNECTION_SERVER_AVAILABLE_REPLY)(VCHI_CONNECTION_STATE_T *state, vcos_fourcc_t service_id, uint32_t flags);
189
190// Callback to indicate that bulk auxiliary messages have arrived
191typedef void (*VCHI_CONNECTION_BULK_AUX_RECEIVED)(VCHI_CONNECTION_STATE_T *state);
192
193// Callback to indicate that bulk auxiliary messages have arrived
194typedef void (*VCHI_CONNECTION_BULK_AUX_TRANSMITTED)(VCHI_CONNECTION_STATE_T *state, void *handle);
195
196// Callback with all the connection info you require
197typedef 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
200typedef void (*VCHI_CONNECTION_DISCONNECT)(VCHI_CONNECTION_STATE_T *state, uint32_t flags);
201
202// Callback to inform of a power control request
203typedef void (*VCHI_CONNECTION_POWER_CONTROL)(VCHI_CONNECTION_STATE_T *state, MESSAGE_TX_CHANNEL_T channel, vcos_bool_t enable);
204
205// allocate memory suitably aligned for this connection
206typedef void * (*VCHI_BUFFER_ALLOCATE)(VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, uint32_t * length);
207
208// free memory allocated by buffer_allocate
209typedef void (*VCHI_BUFFER_FREE)(VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, void * address);
210
211
212/******************************************************************************
213 System driver struct
214 *****************************************************************************/
215
216struct 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
313struct vchi_connection_t {
314 const VCHI_CONNECTION_API_T *api;
315 VCHI_CONNECTION_STATE_T *state;
316#ifdef VCHI_COARSE_LOCKING
317 VCOS_SEMAPHORE_T sem;
318#endif
319};
320
321
322#endif /* CONNECTION_H_ */
323
324/****************************** End of file **********************************/
325