2 * Copyright (c) 2010-2012 Broadcom. All rights reserved.
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
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.
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.
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.
37 #include "interface/vchi/vchi_cfg.h"
38 #include "interface/vchi/vchi_common.h"
39 #include "interface/vchi/connections/connection.h"
43 /******************************************************************************
45 *****************************************************************************/
47 #define VCHI_BULK_ROUND_UP(x) ((((unsigned long)(x))+VCHI_BULK_ALIGN-1) & ~(VCHI_BULK_ALIGN-1))
48 #define VCHI_BULK_ROUND_DOWN(x) (((unsigned long)(x)) & ~(VCHI_BULK_ALIGN-1))
49 #define VCHI_BULK_ALIGN_NBYTES(x) (VCHI_BULK_ALIGNED(x) ? 0 : (VCHI_BULK_ALIGN - ((unsigned long)(x) & (VCHI_BULK_ALIGN-1))))
52 #define VCHI_BULK_ALIGNED(x) 1
54 #define VCHI_BULK_ALIGNED(x) (((unsigned long)(x) & (VCHI_BULK_ALIGN-1)) == 0)
61 #define VCHI_VERSION(v_) { v_, v_ }
62 #define VCHI_VERSION_EX(v_, m_) { v_, m_ }
68 } VCHI_MSG_VECTOR_TYPE_T;
70 typedef struct vchi_msg_vector_ex {
72 VCHI_MSG_VECTOR_TYPE_T type;
76 VCHI_MEM_HANDLE_T handle;
81 // an ordinary data pointer
87 // a nested vector list
89 struct vchi_msg_vector_ex *vec;
93 } VCHI_MSG_VECTOR_EX_T;
96 // Construct an entry in a msg vector for a pointer (p) of length (l)
97 #define VCHI_VEC_POINTER(p,l) VCHI_VEC_POINTER, { { (VCHI_MEM_HANDLE_T)(p), (l) } }
99 // Construct an entry in a msg vector for a message handle (h), starting at offset (o) of length (l)
100 #define VCHI_VEC_HANDLE(h,o,l) VCHI_VEC_HANDLE, { { (h), (o), (l) } }
102 // Macros to manipulate 'FOURCC' values
103 #define MAKE_FOURCC(x) ((int32_t)( (x[0] << 24) | (x[1] << 16) | (x[2] << 8) | x[3] ))
104 #define FOURCC_TO_CHAR(x) (x >> 24) & 0xFF,(x >> 16) & 0xFF,(x >> 8) & 0xFF, x & 0xFF
107 // Opaque service information
108 struct opaque_vchi_service_t;
110 // Descriptor for a held message. Allocated by client, initialised by vchi_msg_hold,
111 // vchi_msg_iter_hold or vchi_msg_iter_hold_next. Fields are for internal VCHI use only.
113 struct opaque_vchi_service_t *service;
119 // structure used to provide the information needed to open a server or a client
121 struct vchi_version version;
123 VCHI_CONNECTION_T *connection;
124 uint32_t rx_fifo_size;
125 uint32_t tx_fifo_size;
126 VCHI_CALLBACK_T callback;
127 void *callback_param;
128 /* client intends to receive bulk transfers of
129 odd lengths or into unaligned buffers */
130 int32_t want_unaligned_bulk_rx;
131 /* client intends to transmit bulk transfers of
132 odd lengths or out of unaligned buffers */
133 int32_t want_unaligned_bulk_tx;
134 /* client wants to check CRCs on (bulk) xfers.
135 Only needs to be set at 1 end - will do both directions. */
137 } SERVICE_CREATION_T;
139 // Opaque handle for a VCHI instance
140 typedef struct opaque_vchi_instance_handle_t *VCHI_INSTANCE_T;
142 // Opaque handle for a server or client
143 typedef struct opaque_vchi_service_handle_t *VCHI_SERVICE_HANDLE_T;
145 // Service registration & startup
146 typedef void (*VCHI_SERVICE_INIT)(VCHI_INSTANCE_T initialise_instance, VCHI_CONNECTION_T **connections, uint32_t num_connections);
148 typedef struct service_info_tag {
149 const char * const vll_filename; /* VLL to load to start this service. This is an empty string if VLL is "static" */
150 VCHI_SERVICE_INIT init; /* Service initialisation function */
151 void *vll_handle; /* VLL handle; NULL when unloaded or a "static VLL" in build */
154 /******************************************************************************
155 Global funcs - implementation is specific to which side you are on (local / remote)
156 *****************************************************************************/
162 extern /*@observer@*/ VCHI_CONNECTION_T * vchi_create_connection( const VCHI_CONNECTION_API_T * function_table,
163 const VCHI_MESSAGE_DRIVER_T * low_level);
166 // Routine used to initialise the vchi on both local + remote connections
167 extern int32_t vchi_initialise( VCHI_INSTANCE_T *instance_handle );
169 extern int32_t vchi_exit( void );
171 extern int32_t vchi_connect( VCHI_CONNECTION_T **connections,
172 const uint32_t num_connections,
173 VCHI_INSTANCE_T instance_handle );
175 //When this is called, ensure that all services have no data pending.
176 //Bulk transfers can remain 'queued'
177 extern int32_t vchi_disconnect( VCHI_INSTANCE_T instance_handle );
179 // Global control over bulk CRC checking
180 extern int32_t vchi_crc_control( VCHI_CONNECTION_T *connection,
181 VCHI_CRC_CONTROL_T control );
184 extern void * vchi_allocate_buffer(VCHI_SERVICE_HANDLE_T handle, uint32_t *length);
185 extern void vchi_free_buffer(VCHI_SERVICE_HANDLE_T handle, void *address);
186 extern uint32_t vchi_current_time(VCHI_INSTANCE_T instance_handle);
189 /******************************************************************************
191 *****************************************************************************/
192 // Routine to create a named service
193 extern int32_t vchi_service_create( VCHI_INSTANCE_T instance_handle,
194 SERVICE_CREATION_T *setup,
195 VCHI_SERVICE_HANDLE_T *handle );
197 // Routine to destory a service
198 extern int32_t vchi_service_destroy( const VCHI_SERVICE_HANDLE_T handle );
200 // Routine to open a named service
201 extern int32_t vchi_service_open( VCHI_INSTANCE_T instance_handle,
202 SERVICE_CREATION_T *setup,
203 VCHI_SERVICE_HANDLE_T *handle);
205 extern int32_t vchi_get_peer_version( const VCHI_SERVICE_HANDLE_T handle,
206 short *peer_version );
208 // Routine to close a named service
209 extern int32_t vchi_service_close( const VCHI_SERVICE_HANDLE_T handle );
211 // Routine to increment ref count on a named service
212 extern int32_t vchi_service_use( const VCHI_SERVICE_HANDLE_T handle );
214 // Routine to decrement ref count on a named service
215 extern int32_t vchi_service_release( const VCHI_SERVICE_HANDLE_T handle );
217 // Routine to set a control option for a named service
218 extern int32_t vchi_service_set_option( const VCHI_SERVICE_HANDLE_T handle,
219 VCHI_SERVICE_OPTION_T option,
222 /* Routine to send a message from kernel memory across a service */
224 vchi_queue_kernel_message(VCHI_SERVICE_HANDLE_T handle,
228 /* Routine to send a message from user memory across a service */
230 vchi_queue_user_message(VCHI_SERVICE_HANDLE_T handle,
234 // Routine to receive a msg from a service
235 // Dequeue is equivalent to hold, copy into client buffer, release
236 extern int32_t vchi_msg_dequeue( VCHI_SERVICE_HANDLE_T handle,
238 uint32_t max_data_size_to_read,
239 uint32_t *actual_msg_size,
240 VCHI_FLAGS_T flags );
242 // Routine to look at a message in place.
243 // The message is not dequeued, so a subsequent call to peek or dequeue
244 // will return the same message.
245 extern int32_t vchi_msg_peek( VCHI_SERVICE_HANDLE_T handle,
248 VCHI_FLAGS_T flags );
250 // Routine to remove a message after it has been read in place with peek
251 // The first message on the queue is dequeued.
252 extern int32_t vchi_msg_remove( VCHI_SERVICE_HANDLE_T handle );
254 // Routine to look at a message in place.
255 // The message is dequeued, so the caller is left holding it; the descriptor is
256 // filled in and must be released when the user has finished with the message.
257 extern int32_t vchi_msg_hold( VCHI_SERVICE_HANDLE_T handle,
258 void **data, // } may be NULL, as info can be
259 uint32_t *msg_size, // } obtained from HELD_MSG_T
261 VCHI_HELD_MSG_T *message_descriptor );
263 // Initialise an iterator to look through messages in place
264 extern int32_t vchi_msg_look_ahead( VCHI_SERVICE_HANDLE_T handle,
265 VCHI_MSG_ITER_T *iter,
266 VCHI_FLAGS_T flags );
268 /******************************************************************************
269 Global service support API - operations on held messages and message iterators
270 *****************************************************************************/
272 // Routine to get the address of a held message
273 extern void *vchi_held_msg_ptr( const VCHI_HELD_MSG_T *message );
275 // Routine to get the size of a held message
276 extern int32_t vchi_held_msg_size( const VCHI_HELD_MSG_T *message );
278 // Routine to get the transmit timestamp as written into the header by the peer
279 extern uint32_t vchi_held_msg_tx_timestamp( const VCHI_HELD_MSG_T *message );
281 // Routine to get the reception timestamp, written as we parsed the header
282 extern uint32_t vchi_held_msg_rx_timestamp( const VCHI_HELD_MSG_T *message );
284 // Routine to release a held message after it has been processed
285 extern int32_t vchi_held_msg_release( VCHI_HELD_MSG_T *message );
287 // Indicates whether the iterator has a next message.
288 extern int32_t vchi_msg_iter_has_next( const VCHI_MSG_ITER_T *iter );
290 // Return the pointer and length for the next message and advance the iterator.
291 extern int32_t vchi_msg_iter_next( VCHI_MSG_ITER_T *iter,
293 uint32_t *msg_size );
295 // Remove the last message returned by vchi_msg_iter_next.
296 // Can only be called once after each call to vchi_msg_iter_next.
297 extern int32_t vchi_msg_iter_remove( VCHI_MSG_ITER_T *iter );
299 // Hold the last message returned by vchi_msg_iter_next.
300 // Can only be called once after each call to vchi_msg_iter_next.
301 extern int32_t vchi_msg_iter_hold( VCHI_MSG_ITER_T *iter,
302 VCHI_HELD_MSG_T *message );
304 // Return information for the next message, and hold it, advancing the iterator.
305 extern int32_t vchi_msg_iter_hold_next( VCHI_MSG_ITER_T *iter,
306 void **data, // } may be NULL
307 uint32_t *msg_size, // }
308 VCHI_HELD_MSG_T *message );
311 /******************************************************************************
313 *****************************************************************************/
315 // Routine to prepare interface for a transfer from the other side
316 extern int32_t vchi_bulk_queue_receive( VCHI_SERVICE_HANDLE_T handle,
320 void *transfer_handle );
323 // Prepare interface for a transfer from the other side into relocatable memory.
324 int32_t vchi_bulk_queue_receive_reloc( const VCHI_SERVICE_HANDLE_T handle,
325 VCHI_MEM_HANDLE_T h_dst,
328 const VCHI_FLAGS_T flags,
329 void * const bulk_handle );
331 // Routine to queue up data ready for transfer to the other (once they have signalled they are ready)
332 extern int32_t vchi_bulk_queue_transmit( VCHI_SERVICE_HANDLE_T handle,
333 const void *data_src,
336 void *transfer_handle );
339 /******************************************************************************
340 Configuration plumbing
341 *****************************************************************************/
343 // function prototypes for the different mid layers (the state info gives the different physical connections)
344 extern const VCHI_CONNECTION_API_T *single_get_func_table( void );
345 //extern const VCHI_CONNECTION_API_T *local_server_get_func_table( void );
346 //extern const VCHI_CONNECTION_API_T *local_client_get_func_table( void );
348 // declare all message drivers here
349 const VCHI_MESSAGE_DRIVER_T *vchi_mphi_message_driver_func_table( void );
355 extern int32_t vchi_bulk_queue_transmit_reloc( VCHI_SERVICE_HANDLE_T handle,
356 VCHI_MEM_HANDLE_T h_src,
360 void *transfer_handle );
363 /****************************** End of file **********************************/