drivers/staging/vc04_services/interface/vchi/vchi.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 VCHI_H_
  35 #define VCHI_H_
  36
  37 #include "interface/vchi/vchi_cfg.h"
  38 #include "interface/vchi/vchi_common.h"
  39 #include "interface/vchi/connections/connection.h"
  40 #include "vchi_mh.h"
  41
  42
  43 /******************************************************************************
  44  Global defs
  45  *****************************************************************************/
  46
  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))))
  50
  51 #ifdef USE_VCHIQ_ARM
  52 #define VCHI_BULK_ALIGNED(x)      1
  53 #else
  54 #define VCHI_BULK_ALIGNED(x)      (((unsigned long)(x) & (VCHI_BULK_ALIGN-1)) == 0)
  55 #endif
  56
  57 struct vchi_version {
  58         uint32_t version;
  59         uint32_t version_min;
  60 };
  61 #define VCHI_VERSION(v_) { v_, v_ }
  62 #define VCHI_VERSION_EX(v_, m_) { v_, m_ }
  63
  64 typedef enum
  65 {
  66    VCHI_VEC_POINTER,
  67    VCHI_VEC_HANDLE,
  68    VCHI_VEC_LIST
  69 } VCHI_MSG_VECTOR_TYPE_T;
  70
  71 typedef struct vchi_msg_vector_ex {
  72
  73    VCHI_MSG_VECTOR_TYPE_T type;
  74    union
  75    {
  76       // a memory handle
  77       struct
  78       {
  79          VCHI_MEM_HANDLE_T handle;
  80          uint32_t offset;
  81          int32_t vec_len;
  82       } handle;
  83
  84       // an ordinary data pointer
  85       struct
  86       {
  87          const void *vec_base;
  88          int32_t vec_len;
  89       } ptr;
  90
  91       // a nested vector list
  92       struct
  93       {
  94          struct vchi_msg_vector_ex *vec;
  95          uint32_t vec_len;
  96       } list;
  97    } u;
  98 } VCHI_MSG_VECTOR_EX_T;
  99
 100
 101 // Construct an entry in a msg vector for a pointer (p) of length (l)
 102 #define VCHI_VEC_POINTER(p,l)  VCHI_VEC_POINTER, { { (VCHI_MEM_HANDLE_T)(p), (l) } }
 103
 104 // Construct an entry in a msg vector for a message handle (h), starting at offset (o) of length (l)
 105 #define VCHI_VEC_HANDLE(h,o,l) VCHI_VEC_HANDLE,  { { (h), (o), (l) } }
 106
 107 // Macros to manipulate 'FOURCC' values
 108 #define MAKE_FOURCC(x) ((int32_t)( (x[0] << 24) | (x[1] << 16) | (x[2] << 8) | x[3] ))
 109 #define FOURCC_TO_CHAR(x) (x >> 24) & 0xFF,(x >> 16) & 0xFF,(x >> 8) & 0xFF, x & 0xFF
 110
 111
 112 // Opaque service information
 113 struct opaque_vchi_service_t;
 114
 115 // Descriptor for a held message. Allocated by client, initialised by vchi_msg_hold,
 116 // vchi_msg_iter_hold or vchi_msg_iter_hold_next. Fields are for internal VCHI use only.
 117 typedef struct
 118 {
 119    struct opaque_vchi_service_t *service;
 120    void *message;
 121 } VCHI_HELD_MSG_T;
 122
 123
 124
 125 // structure used to provide the information needed to open a server or a client
 126 typedef struct {
 127         struct vchi_version version;
 128         int32_t service_id;
 129         VCHI_CONNECTION_T *connection;
 130         uint32_t rx_fifo_size;
 131         uint32_t tx_fifo_size;
 132         VCHI_CALLBACK_T callback;
 133         void *callback_param;
 134         /* client intends to receive bulk transfers of
 135                 odd lengths or into unaligned buffers */
 136         int32_t want_unaligned_bulk_rx;
 137         /* client intends to transmit bulk transfers of
 138                 odd lengths or out of unaligned buffers */
 139         int32_t want_unaligned_bulk_tx;
 140         /* client wants to check CRCs on (bulk) xfers.
 141                 Only needs to be set at 1 end - will do both directions. */
 142         int32_t want_crc;
 143 } SERVICE_CREATION_T;
 144
 145 // Opaque handle for a VCHI instance
 146 typedef struct opaque_vchi_instance_handle_t *VCHI_INSTANCE_T;
 147
 148 // Opaque handle for a server or client
 149 typedef struct opaque_vchi_service_handle_t *VCHI_SERVICE_HANDLE_T;
 150
 151 // Service registration & startup
 152 typedef void (*VCHI_SERVICE_INIT)(VCHI_INSTANCE_T initialise_instance, VCHI_CONNECTION_T **connections, uint32_t num_connections);
 153
 154 typedef struct service_info_tag {
 155    const char * const vll_filename; /* VLL to load to start this service. This is an empty string if VLL is "static" */
 156    VCHI_SERVICE_INIT init;          /* Service initialisation function */
 157    void *vll_handle;                /* VLL handle; NULL when unloaded or a "static VLL" in build */
 158 } SERVICE_INFO_T;
 159
 160 /******************************************************************************
 161  Global funcs - implementation is specific to which side you are on (local / remote)
 162  *****************************************************************************/
 163
 164 #ifdef __cplusplus
 165 extern "C" {
 166 #endif
 167
 168 extern /*@observer@*/ VCHI_CONNECTION_T * vchi_create_connection( const VCHI_CONNECTION_API_T * function_table,
 169                                                    const VCHI_MESSAGE_DRIVER_T * low_level);
 170
 171
 172 // Routine used to initialise the vchi on both local + remote connections
 173 extern int32_t vchi_initialise( VCHI_INSTANCE_T *instance_handle );
 174
 175 extern int32_t vchi_exit( void );
 176
 177 extern int32_t vchi_connect( VCHI_CONNECTION_T **connections,
 178                              const uint32_t num_connections,
 179                              VCHI_INSTANCE_T instance_handle );
 180
 181 //When this is called, ensure that all services have no data pending.
 182 //Bulk transfers can remain 'queued'
 183 extern int32_t vchi_disconnect( VCHI_INSTANCE_T instance_handle );
 184
 185 // Global control over bulk CRC checking
 186 extern int32_t vchi_crc_control( VCHI_CONNECTION_T *connection,
 187                                  VCHI_CRC_CONTROL_T control );
 188
 189 // helper functions
 190 extern void * vchi_allocate_buffer(VCHI_SERVICE_HANDLE_T handle, uint32_t *length);
 191 extern void vchi_free_buffer(VCHI_SERVICE_HANDLE_T handle, void *address);
 192 extern uint32_t vchi_current_time(VCHI_INSTANCE_T instance_handle);
 193
 194
 195 /******************************************************************************
 196  Global service API
 197  *****************************************************************************/
 198 // Routine to create a named service
 199 extern int32_t vchi_service_create( VCHI_INSTANCE_T instance_handle,
 200                                     SERVICE_CREATION_T *setup,
 201                                     VCHI_SERVICE_HANDLE_T *handle );
 202
 203 // Routine to destory a service
 204 extern int32_t vchi_service_destroy( const VCHI_SERVICE_HANDLE_T handle );
 205
 206 // Routine to open a named service
 207 extern int32_t vchi_service_open( VCHI_INSTANCE_T instance_handle,
 208                                   SERVICE_CREATION_T *setup,
 209                                   VCHI_SERVICE_HANDLE_T *handle);
 210
 211 extern int32_t vchi_get_peer_version( const VCHI_SERVICE_HANDLE_T handle,
 212                                       short *peer_version );
 213
 214 // Routine to close a named service
 215 extern int32_t vchi_service_close( const VCHI_SERVICE_HANDLE_T handle );
 216
 217 // Routine to increment ref count on a named service
 218 extern int32_t vchi_service_use( const VCHI_SERVICE_HANDLE_T handle );
 219
 220 // Routine to decrement ref count on a named service
 221 extern int32_t vchi_service_release( const VCHI_SERVICE_HANDLE_T handle );
 222
 223 // Routine to set a control option for a named service
 224 extern int32_t vchi_service_set_option( const VCHI_SERVICE_HANDLE_T handle,
 225                                         VCHI_SERVICE_OPTION_T option,
 226                                         int value);
 227
 228 // Routine to send a message across a service
 229 extern int32_t vchi_msg_queue( VCHI_SERVICE_HANDLE_T handle,
 230                                const void *data,
 231                                uint32_t data_size,
 232                                VCHI_FLAGS_T flags,
 233                                void *msg_handle );
 234
 235 // scatter-gather (vector) and send message
 236 int32_t vchi_msg_queuev_ex( VCHI_SERVICE_HANDLE_T handle,
 237                             VCHI_MSG_VECTOR_EX_T *vector,
 238                             uint32_t count,
 239                             VCHI_FLAGS_T flags,
 240                             void *msg_handle );
 241
 242 // legacy scatter-gather (vector) and send message, only handles pointers
 243 int32_t vchi_msg_queuev( VCHI_SERVICE_HANDLE_T handle,
 244                          VCHI_MSG_VECTOR_T *vector,
 245                          uint32_t count,
 246                          VCHI_FLAGS_T flags,
 247                          void *msg_handle );
 248
 249 // Routine to receive a msg from a service
 250 // Dequeue is equivalent to hold, copy into client buffer, release
 251 extern int32_t vchi_msg_dequeue( VCHI_SERVICE_HANDLE_T handle,
 252                                  void *data,
 253                                  uint32_t max_data_size_to_read,
 254                                  uint32_t *actual_msg_size,
 255                                  VCHI_FLAGS_T flags );
 256
 257 // Routine to look at a message in place.
 258 // The message is not dequeued, so a subsequent call to peek or dequeue
 259 // will return the same message.
 260 extern int32_t vchi_msg_peek( VCHI_SERVICE_HANDLE_T handle,
 261                               void **data,
 262                               uint32_t *msg_size,
 263                               VCHI_FLAGS_T flags );
 264
 265 // Routine to remove a message after it has been read in place with peek
 266 // The first message on the queue is dequeued.
 267 extern int32_t vchi_msg_remove( VCHI_SERVICE_HANDLE_T handle );
 268
 269 // Routine to look at a message in place.
 270 // The message is dequeued, so the caller is left holding it; the descriptor is
 271 // filled in and must be released when the user has finished with the message.
 272 extern int32_t vchi_msg_hold( VCHI_SERVICE_HANDLE_T handle,
 273                               void **data,        // } may be NULL, as info can be
 274                               uint32_t *msg_size, // } obtained from HELD_MSG_T
 275                               VCHI_FLAGS_T flags,
 276                               VCHI_HELD_MSG_T *message_descriptor );
 277
 278 // Initialise an iterator to look through messages in place
 279 extern int32_t vchi_msg_look_ahead( VCHI_SERVICE_HANDLE_T handle,
 280                                     VCHI_MSG_ITER_T *iter,
 281                                     VCHI_FLAGS_T flags );
 282
 283 /******************************************************************************
 284  Global service support API - operations on held messages and message iterators
 285  *****************************************************************************/
 286
 287 // Routine to get the address of a held message
 288 extern void *vchi_held_msg_ptr( const VCHI_HELD_MSG_T *message );
 289
 290 // Routine to get the size of a held message
 291 extern int32_t vchi_held_msg_size( const VCHI_HELD_MSG_T *message );
 292
 293 // Routine to get the transmit timestamp as written into the header by the peer
 294 extern uint32_t vchi_held_msg_tx_timestamp( const VCHI_HELD_MSG_T *message );
 295
 296 // Routine to get the reception timestamp, written as we parsed the header
 297 extern uint32_t vchi_held_msg_rx_timestamp( const VCHI_HELD_MSG_T *message );
 298
 299 // Routine to release a held message after it has been processed
 300 extern int32_t vchi_held_msg_release( VCHI_HELD_MSG_T *message );
 301
 302 // Indicates whether the iterator has a next message.
 303 extern int32_t vchi_msg_iter_has_next( const VCHI_MSG_ITER_T *iter );
 304
 305 // Return the pointer and length for the next message and advance the iterator.
 306 extern int32_t vchi_msg_iter_next( VCHI_MSG_ITER_T *iter,
 307                                    void **data,
 308                                    uint32_t *msg_size );
 309
 310 // Remove the last message returned by vchi_msg_iter_next.
 311 // Can only be called once after each call to vchi_msg_iter_next.
 312 extern int32_t vchi_msg_iter_remove( VCHI_MSG_ITER_T *iter );
 313
 314 // Hold the last message returned by vchi_msg_iter_next.
 315 // Can only be called once after each call to vchi_msg_iter_next.
 316 extern int32_t vchi_msg_iter_hold( VCHI_MSG_ITER_T *iter,
 317                                    VCHI_HELD_MSG_T *message );
 318
 319 // Return information for the next message, and hold it, advancing the iterator.
 320 extern int32_t vchi_msg_iter_hold_next( VCHI_MSG_ITER_T *iter,
 321                                         void **data,        // } may be NULL
 322                                         uint32_t *msg_size, // }
 323                                         VCHI_HELD_MSG_T *message );
 324
 325
 326 /******************************************************************************
 327  Global bulk API
 328  *****************************************************************************/
 329
 330 // Routine to prepare interface for a transfer from the other side
 331 extern int32_t vchi_bulk_queue_receive( VCHI_SERVICE_HANDLE_T handle,
 332                                         void *data_dst,
 333                                         uint32_t data_size,
 334                                         VCHI_FLAGS_T flags,
 335                                         void *transfer_handle );
 336
 337
 338 // Prepare interface for a transfer from the other side into relocatable memory.
 339 int32_t vchi_bulk_queue_receive_reloc( const VCHI_SERVICE_HANDLE_T handle,
 340                                        VCHI_MEM_HANDLE_T h_dst,
 341                                        uint32_t offset,
 342                                        uint32_t data_size,
 343                                        const VCHI_FLAGS_T flags,
 344                                        void * const bulk_handle );
 345
 346 // Routine to queue up data ready for transfer to the other (once they have signalled they are ready)
 347 extern int32_t vchi_bulk_queue_transmit( VCHI_SERVICE_HANDLE_T handle,
 348                                          const void *data_src,
 349                                          uint32_t data_size,
 350                                          VCHI_FLAGS_T flags,
 351                                          void *transfer_handle );
 352
 353
 354 /******************************************************************************
 355  Configuration plumbing
 356  *****************************************************************************/
 357
 358 // function prototypes for the different mid layers (the state info gives the different physical connections)
 359 extern const VCHI_CONNECTION_API_T *single_get_func_table( void );
 360 //extern const VCHI_CONNECTION_API_T *local_server_get_func_table( void );
 361 //extern const VCHI_CONNECTION_API_T *local_client_get_func_table( void );
 362
 363 // declare all message drivers here
 364 const VCHI_MESSAGE_DRIVER_T *vchi_mphi_message_driver_func_table( void );
 365
 366 #ifdef __cplusplus
 367 }
 368 #endif
 369
 370 extern int32_t vchi_bulk_queue_transmit_reloc( VCHI_SERVICE_HANDLE_T handle,
 371                                                VCHI_MEM_HANDLE_T h_src,
 372                                                uint32_t offset,
 373                                                uint32_t data_size,
 374                                                VCHI_FLAGS_T flags,
 375                                                void *transfer_handle );
 376 #endif /* VCHI_H_ */
 377
 378 /****************************** End of file **********************************/