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_T; 79 80 typedef struct vchiq_header_struct { 81 /* The message identifier - opaque to applications. */ 82 int msgid; 83 84 /* Size of message data. */ 85 unsigned int size; 86 87 char data[0]; /* message */ 88 } VCHIQ_HEADER_T; 89 90 typedef struct { 91 const void *data; 92 unsigned int size; 93 } VCHIQ_ELEMENT_T; 94 95 typedef unsigned int VCHIQ_SERVICE_HANDLE_T; 96 97 typedef VCHIQ_STATUS_T (*VCHIQ_CALLBACK_T)(VCHIQ_REASON_T, VCHIQ_HEADER_T *, 98 VCHIQ_SERVICE_HANDLE_T, void *); 99 100 typedef struct vchiq_service_base_struct { 101 int fourcc; 102 VCHIQ_CALLBACK_T callback; 103 void *userdata; 104 } VCHIQ_SERVICE_BASE_T; 105 106 typedef struct vchiq_service_params_struct { 107 int fourcc; 108 VCHIQ_CALLBACK_T callback; 109 void *userdata; 110 short version; /* Increment for non-trivial changes */ 111 short version_min; /* Update for incompatible changes */ 112 } VCHIQ_SERVICE_PARAMS_T; 113 114 typedef struct vchiq_config_struct { 115 unsigned int max_msg_size; 116 unsigned int bulk_threshold; /* The message size above which it 117 is better to use a bulk transfer 118 (<= max_msg_size) */ 119 unsigned int max_outstanding_bulks; 120 unsigned int max_services; 121 short version; /* The version of VCHIQ */ 122 short version_min; /* The minimum compatible version of VCHIQ */ 123 } VCHIQ_CONFIG_T; 124 125 typedef struct vchiq_instance_struct *VCHIQ_INSTANCE_T; 126 typedef void (*VCHIQ_REMOTE_USE_CALLBACK_T)(void *cb_arg); 127 128 extern VCHIQ_STATUS_T vchiq_initialise(VCHIQ_INSTANCE_T *pinstance); 129 extern VCHIQ_STATUS_T vchiq_shutdown(VCHIQ_INSTANCE_T instance); 130 extern VCHIQ_STATUS_T vchiq_connect(VCHIQ_INSTANCE_T instance); 131 extern VCHIQ_STATUS_T vchiq_add_service(VCHIQ_INSTANCE_T instance, 132 const VCHIQ_SERVICE_PARAMS_T *params, 133 VCHIQ_SERVICE_HANDLE_T *pservice); 134 extern VCHIQ_STATUS_T vchiq_open_service(VCHIQ_INSTANCE_T instance, 135 const VCHIQ_SERVICE_PARAMS_T *params, 136 VCHIQ_SERVICE_HANDLE_T *pservice); 137 extern VCHIQ_STATUS_T vchiq_close_service(VCHIQ_SERVICE_HANDLE_T service); 138 extern VCHIQ_STATUS_T vchiq_remove_service(VCHIQ_SERVICE_HANDLE_T service); 139 extern VCHIQ_STATUS_T vchiq_use_service(VCHIQ_SERVICE_HANDLE_T service); 140 extern VCHIQ_STATUS_T vchiq_use_service_no_resume( 141 VCHIQ_SERVICE_HANDLE_T service); 142 extern VCHIQ_STATUS_T vchiq_release_service(VCHIQ_SERVICE_HANDLE_T service); 143 144 extern VCHIQ_STATUS_T vchiq_queue_message(VCHIQ_SERVICE_HANDLE_T service, 145 const VCHIQ_ELEMENT_T *elements, unsigned int count); 146 extern void vchiq_release_message(VCHIQ_SERVICE_HANDLE_T service, 147 VCHIQ_HEADER_T *header); 148 extern VCHIQ_STATUS_T vchiq_queue_bulk_transmit(VCHIQ_SERVICE_HANDLE_T service, 149 void *data, unsigned int size, void *userdata); 150 extern VCHIQ_STATUS_T vchiq_queue_bulk_receive(VCHIQ_SERVICE_HANDLE_T service, 151 void *data, unsigned int size, void *userdata); 152 extern VCHIQ_STATUS_T vchiq_queue_bulk_transmit_handle( 153 VCHIQ_SERVICE_HANDLE_T service, VCHI_MEM_HANDLE_T handle, 154 const void *offset, unsigned int size, void *userdata); 155 extern VCHIQ_STATUS_T vchiq_queue_bulk_receive_handle( 156 VCHIQ_SERVICE_HANDLE_T service, VCHI_MEM_HANDLE_T handle, 157 void *offset, unsigned int size, void *userdata); 158 extern VCHIQ_STATUS_T vchiq_bulk_transmit(VCHIQ_SERVICE_HANDLE_T service, 159 void *data, unsigned int size, void *userdata, 160 VCHIQ_BULK_MODE_T mode); 161 extern VCHIQ_STATUS_T vchiq_bulk_receive(VCHIQ_SERVICE_HANDLE_T service, 162 void *data, unsigned int size, void *userdata, 163 VCHIQ_BULK_MODE_T mode); 164 extern VCHIQ_STATUS_T vchiq_bulk_transmit_handle(VCHIQ_SERVICE_HANDLE_T service, 165 VCHI_MEM_HANDLE_T handle, const void *offset, unsigned int size, 166 void *userdata, VCHIQ_BULK_MODE_T mode); 167 extern VCHIQ_STATUS_T vchiq_bulk_receive_handle(VCHIQ_SERVICE_HANDLE_T service, 168 VCHI_MEM_HANDLE_T handle, void *offset, unsigned int size, 169 void *userdata, VCHIQ_BULK_MODE_T mode); 170 extern int vchiq_get_client_id(VCHIQ_SERVICE_HANDLE_T service); 171 extern void *vchiq_get_service_userdata(VCHIQ_SERVICE_HANDLE_T service); 172 extern int vchiq_get_service_fourcc(VCHIQ_SERVICE_HANDLE_T service); 173 extern VCHIQ_STATUS_T vchiq_get_config(VCHIQ_INSTANCE_T instance, 174 int config_size, VCHIQ_CONFIG_T *pconfig); 175 extern VCHIQ_STATUS_T vchiq_set_service_option(VCHIQ_SERVICE_HANDLE_T service, 176 VCHIQ_SERVICE_OPTION_T option, int value); 177 178 extern VCHIQ_STATUS_T vchiq_remote_use(VCHIQ_INSTANCE_T instance, 179 VCHIQ_REMOTE_USE_CALLBACK_T callback, void *cb_arg); 180 extern VCHIQ_STATUS_T vchiq_remote_release(VCHIQ_INSTANCE_T instance); 181 182 extern VCHIQ_STATUS_T vchiq_dump_phys_mem(VCHIQ_SERVICE_HANDLE_T service, 183 void *ptr, size_t num_bytes); 184 185 extern VCHIQ_STATUS_T vchiq_get_peer_version(VCHIQ_SERVICE_HANDLE_T handle, 186 short *peer_version); 187 188 #endif /* VCHIQ_IF_H */ 189