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 VCHIQ_IF_H 35 #define VCHIQ_IF_H 36 37 #include "interface/vchi/vchi_mh.h" 38 39 #define VCHIQ_SERVICE_HANDLE_INVALID 0 40 41 #define VCHIQ_SLOT_SIZE 4096 42 #define VCHIQ_MAX_MSG_SIZE (VCHIQ_SLOT_SIZE - sizeof(VCHIQ_HEADER_T)) 43 #define VCHIQ_CHANNEL_SIZE VCHIQ_MAX_MSG_SIZE /* For backwards compatibility */ 44 45 #define VCHIQ_MAKE_FOURCC(x0, x1, x2, x3) \ 46 (((x0) << 24) | ((x1) << 16) | ((x2) << 8) | (x3)) 47 #define VCHIQ_GET_SERVICE_USERDATA(service) vchiq_get_service_userdata(service) 48 #define VCHIQ_GET_SERVICE_FOURCC(service) vchiq_get_service_fourcc(service) 49 50 typedef enum { 51 VCHIQ_SERVICE_OPENED, /* service, -, - */ 52 VCHIQ_SERVICE_CLOSED, /* service, -, - */ 53 VCHIQ_MESSAGE_AVAILABLE, /* service, header, - */ 54 VCHIQ_BULK_TRANSMIT_DONE, /* service, -, bulk_userdata */ 55 VCHIQ_BULK_RECEIVE_DONE, /* service, -, bulk_userdata */ 56 VCHIQ_BULK_TRANSMIT_ABORTED, /* service, -, bulk_userdata */ 57 VCHIQ_BULK_RECEIVE_ABORTED /* service, -, bulk_userdata */ 58 } VCHIQ_REASON_T; 59 60 typedef enum { 61 VCHIQ_ERROR = -1, 62 VCHIQ_SUCCESS = 0, 63 VCHIQ_RETRY = 1 64 } VCHIQ_STATUS_T; 65 66 typedef enum { 67 VCHIQ_BULK_MODE_CALLBACK, 68 VCHIQ_BULK_MODE_BLOCKING, 69 VCHIQ_BULK_MODE_NOCALLBACK, 70 VCHIQ_BULK_MODE_WAITING /* Reserved for internal use */ 71 } VCHIQ_BULK_MODE_T; 72 73 typedef enum { 74 VCHIQ_SERVICE_OPTION_AUTOCLOSE, 75 VCHIQ_SERVICE_OPTION_SLOT_QUOTA, 76 VCHIQ_SERVICE_OPTION_MESSAGE_QUOTA, 77 VCHIQ_SERVICE_OPTION_SYNCHRONOUS, 78 VCHIQ_SERVICE_OPTION_TRACE 79 } VCHIQ_SERVICE_OPTION_T; 80 81 typedef struct vchiq_header_struct { 82 /* The message identifier - opaque to applications. */ 83 int msgid; 84 85 /* Size of message data. */ 86 unsigned int size; 87 88 char data[0]; /* message */ 89 } VCHIQ_HEADER_T; 90 91 typedef struct { 92 const void *data; 93 unsigned int size; 94 } VCHIQ_ELEMENT_T; 95 96 typedef unsigned int VCHIQ_SERVICE_HANDLE_T; 97 98 typedef VCHIQ_STATUS_T (*VCHIQ_CALLBACK_T)(VCHIQ_REASON_T, VCHIQ_HEADER_T *, 99 VCHIQ_SERVICE_HANDLE_T, void *); 100 101 typedef struct vchiq_service_base_struct { 102 int fourcc; 103 VCHIQ_CALLBACK_T callback; 104 void *userdata; 105 } VCHIQ_SERVICE_BASE_T; 106 107 typedef struct vchiq_service_params_struct { 108 int fourcc; 109 VCHIQ_CALLBACK_T callback; 110 void *userdata; 111 short version; /* Increment for non-trivial changes */ 112 short version_min; /* Update for incompatible changes */ 113 } VCHIQ_SERVICE_PARAMS_T; 114 115 typedef struct vchiq_config_struct { 116 unsigned int max_msg_size; 117 unsigned int bulk_threshold; /* The message size above which it 118 is better to use a bulk transfer 119 (<= max_msg_size) */ 120 unsigned int max_outstanding_bulks; 121 unsigned int max_services; 122 short version; /* The version of VCHIQ */ 123 short version_min; /* The minimum compatible version of VCHIQ */ 124 } VCHIQ_CONFIG_T; 125 126 typedef struct vchiq_instance_struct *VCHIQ_INSTANCE_T; 127 typedef void (*VCHIQ_REMOTE_USE_CALLBACK_T)(void *cb_arg); 128 129 extern VCHIQ_STATUS_T vchiq_initialise(VCHIQ_INSTANCE_T *pinstance); 130 extern VCHIQ_STATUS_T vchiq_shutdown(VCHIQ_INSTANCE_T instance); 131 extern VCHIQ_STATUS_T vchiq_connect(VCHIQ_INSTANCE_T instance); 132 extern VCHIQ_STATUS_T vchiq_add_service(VCHIQ_INSTANCE_T instance, 133 const VCHIQ_SERVICE_PARAMS_T *params, 134 VCHIQ_SERVICE_HANDLE_T *pservice); 135 extern VCHIQ_STATUS_T vchiq_open_service(VCHIQ_INSTANCE_T instance, 136 const VCHIQ_SERVICE_PARAMS_T *params, 137 VCHIQ_SERVICE_HANDLE_T *pservice); 138 extern VCHIQ_STATUS_T vchiq_close_service(VCHIQ_SERVICE_HANDLE_T service); 139 extern VCHIQ_STATUS_T vchiq_remove_service(VCHIQ_SERVICE_HANDLE_T service); 140 extern VCHIQ_STATUS_T vchiq_use_service(VCHIQ_SERVICE_HANDLE_T service); 141 extern VCHIQ_STATUS_T vchiq_use_service_no_resume( 142 VCHIQ_SERVICE_HANDLE_T service); 143 extern VCHIQ_STATUS_T vchiq_release_service(VCHIQ_SERVICE_HANDLE_T service); 144 145 extern VCHIQ_STATUS_T vchiq_queue_message(VCHIQ_SERVICE_HANDLE_T service, 146 const VCHIQ_ELEMENT_T *elements, unsigned int count); 147 extern void vchiq_release_message(VCHIQ_SERVICE_HANDLE_T service, 148 VCHIQ_HEADER_T *header); 149 extern VCHIQ_STATUS_T vchiq_queue_bulk_transmit(VCHIQ_SERVICE_HANDLE_T service, 150 void *data, unsigned int size, void *userdata); 151 extern VCHIQ_STATUS_T vchiq_queue_bulk_receive(VCHIQ_SERVICE_HANDLE_T service, 152 void *data, unsigned int size, void *userdata); 153 extern VCHIQ_STATUS_T vchiq_queue_bulk_transmit_handle( 154 VCHIQ_SERVICE_HANDLE_T service, VCHI_MEM_HANDLE_T handle, 155 const void *offset, unsigned int size, void *userdata); 156 extern VCHIQ_STATUS_T vchiq_queue_bulk_receive_handle( 157 VCHIQ_SERVICE_HANDLE_T service, VCHI_MEM_HANDLE_T handle, 158 void *offset, unsigned int size, void *userdata); 159 extern VCHIQ_STATUS_T vchiq_bulk_transmit(VCHIQ_SERVICE_HANDLE_T service, 160 void *data, unsigned int size, void *userdata, 161 VCHIQ_BULK_MODE_T mode); 162 extern VCHIQ_STATUS_T vchiq_bulk_receive(VCHIQ_SERVICE_HANDLE_T service, 163 void *data, unsigned int size, void *userdata, 164 VCHIQ_BULK_MODE_T mode); 165 extern VCHIQ_STATUS_T vchiq_bulk_transmit_handle(VCHIQ_SERVICE_HANDLE_T service, 166 VCHI_MEM_HANDLE_T handle, const void *offset, unsigned int size, 167 void *userdata, VCHIQ_BULK_MODE_T mode); 168 extern VCHIQ_STATUS_T vchiq_bulk_receive_handle(VCHIQ_SERVICE_HANDLE_T service, 169 VCHI_MEM_HANDLE_T handle, void *offset, unsigned int size, 170 void *userdata, VCHIQ_BULK_MODE_T mode); 171 extern int vchiq_get_client_id(VCHIQ_SERVICE_HANDLE_T service); 172 extern void *vchiq_get_service_userdata(VCHIQ_SERVICE_HANDLE_T service); 173 extern int vchiq_get_service_fourcc(VCHIQ_SERVICE_HANDLE_T service); 174 extern VCHIQ_STATUS_T vchiq_get_config(VCHIQ_INSTANCE_T instance, 175 int config_size, VCHIQ_CONFIG_T *pconfig); 176 extern VCHIQ_STATUS_T vchiq_set_service_option(VCHIQ_SERVICE_HANDLE_T service, 177 VCHIQ_SERVICE_OPTION_T option, int value); 178 179 extern VCHIQ_STATUS_T vchiq_remote_use(VCHIQ_INSTANCE_T instance, 180 VCHIQ_REMOTE_USE_CALLBACK_T callback, void *cb_arg); 181 extern VCHIQ_STATUS_T vchiq_remote_release(VCHIQ_INSTANCE_T instance); 182 183 extern VCHIQ_STATUS_T vchiq_dump_phys_mem(VCHIQ_SERVICE_HANDLE_T service, 184 void *ptr, size_t num_bytes); 185 186 extern VCHIQ_STATUS_T vchiq_get_peer_version(VCHIQ_SERVICE_HANDLE_T handle, 187 short *peer_version); 188 189 #endif /* VCHIQ_IF_H */ 190