1 /* SPDX-License-Identifier: GPL-2.0 OR BSD-3-Clause */ 2 /* Copyright (c) 2010-2012 Broadcom. All rights reserved. */ 3 4 #ifndef VCHI_H_ 5 #define VCHI_H_ 6 7 #include "interface/vchi/vchi_cfg.h" 8 #include "interface/vchi/vchi_common.h" 9 10 /****************************************************************************** 11 Global defs 12 *****************************************************************************/ 13 14 #define VCHI_BULK_ROUND_UP(x) ((((unsigned long)(x))+VCHI_BULK_ALIGN-1) & ~(VCHI_BULK_ALIGN-1)) 15 #define VCHI_BULK_ROUND_DOWN(x) (((unsigned long)(x)) & ~(VCHI_BULK_ALIGN-1)) 16 #define VCHI_BULK_ALIGN_NBYTES(x) (VCHI_BULK_ALIGNED(x) ? 0 : (VCHI_BULK_ALIGN - ((unsigned long)(x) & (VCHI_BULK_ALIGN-1)))) 17 18 #ifdef USE_VCHIQ_ARM 19 #define VCHI_BULK_ALIGNED(x) 1 20 #else 21 #define VCHI_BULK_ALIGNED(x) (((unsigned long)(x) & (VCHI_BULK_ALIGN-1)) == 0) 22 #endif 23 24 struct vchi_version { 25 uint32_t version; 26 uint32_t version_min; 27 }; 28 #define VCHI_VERSION(v_) { v_, v_ } 29 #define VCHI_VERSION_EX(v_, m_) { v_, m_ } 30 31 // Macros to manipulate 'FOURCC' values 32 #define MAKE_FOURCC(x) ((int32_t)((x[0] << 24) | (x[1] << 16) | (x[2] << 8) | x[3])) 33 34 // Opaque service information 35 struct opaque_vchi_service_t; 36 37 // Descriptor for a held message. Allocated by client, initialised by vchi_msg_hold, 38 // vchi_msg_iter_hold or vchi_msg_iter_hold_next. Fields are for internal VCHI use only. 39 struct vchi_held_msg { 40 struct opaque_vchi_service_t *service; 41 void *message; 42 }; 43 44 // structure used to provide the information needed to open a server or a client 45 struct service_creation { 46 struct vchi_version version; 47 int32_t service_id; 48 VCHI_CALLBACK_T callback; 49 void *callback_param; 50 }; 51 52 // Opaque handle for a VCHI instance 53 typedef struct opaque_vchi_instance_handle_t *VCHI_INSTANCE_T; 54 55 // Opaque handle for a server or client 56 typedef struct opaque_vchi_service_handle_t *VCHI_SERVICE_HANDLE_T; 57 58 /****************************************************************************** 59 Global funcs - implementation is specific to which side you are on (local / remote) 60 *****************************************************************************/ 61 62 #ifdef __cplusplus 63 extern "C" { 64 #endif 65 66 // Routine used to initialise the vchi on both local + remote connections 67 extern int32_t vchi_initialise(VCHI_INSTANCE_T *instance_handle); 68 69 extern int32_t vchi_exit(void); 70 71 extern int32_t vchi_connect(VCHI_INSTANCE_T instance_handle); 72 73 //When this is called, ensure that all services have no data pending. 74 //Bulk transfers can remain 'queued' 75 extern int32_t vchi_disconnect(VCHI_INSTANCE_T instance_handle); 76 77 // helper functions 78 extern void *vchi_allocate_buffer(VCHI_SERVICE_HANDLE_T handle, uint32_t *length); 79 extern void vchi_free_buffer(VCHI_SERVICE_HANDLE_T handle, void *address); 80 extern uint32_t vchi_current_time(VCHI_INSTANCE_T instance_handle); 81 82 /****************************************************************************** 83 Global service API 84 *****************************************************************************/ 85 // Routine to destroy a service 86 extern int32_t vchi_service_destroy(const VCHI_SERVICE_HANDLE_T handle); 87 88 // Routine to open a named service 89 extern int32_t vchi_service_open(VCHI_INSTANCE_T instance_handle, 90 struct service_creation *setup, 91 VCHI_SERVICE_HANDLE_T *handle); 92 93 extern int32_t vchi_get_peer_version(const VCHI_SERVICE_HANDLE_T handle, 94 short *peer_version); 95 96 // Routine to close a named service 97 extern int32_t vchi_service_close(const VCHI_SERVICE_HANDLE_T handle); 98 99 // Routine to increment ref count on a named service 100 extern int32_t vchi_service_use(const VCHI_SERVICE_HANDLE_T handle); 101 102 // Routine to decrement ref count on a named service 103 extern int32_t vchi_service_release(const VCHI_SERVICE_HANDLE_T handle); 104 105 // Routine to set a control option for a named service 106 extern int32_t vchi_service_set_option(const VCHI_SERVICE_HANDLE_T handle, 107 VCHI_SERVICE_OPTION_T option, 108 int value); 109 110 /* Routine to send a message from kernel memory across a service */ 111 extern int 112 vchi_queue_kernel_message(VCHI_SERVICE_HANDLE_T handle, 113 void *data, 114 unsigned int size); 115 116 /* Routine to send a message from user memory across a service */ 117 extern int 118 vchi_queue_user_message(VCHI_SERVICE_HANDLE_T handle, 119 void __user *data, 120 unsigned int size); 121 122 // Routine to receive a msg from a service 123 // Dequeue is equivalent to hold, copy into client buffer, release 124 extern int32_t vchi_msg_dequeue(VCHI_SERVICE_HANDLE_T handle, 125 void *data, 126 uint32_t max_data_size_to_read, 127 uint32_t *actual_msg_size, 128 VCHI_FLAGS_T flags); 129 130 // Routine to look at a message in place. 131 // The message is not dequeued, so a subsequent call to peek or dequeue 132 // will return the same message. 133 extern int32_t vchi_msg_peek(VCHI_SERVICE_HANDLE_T handle, 134 void **data, 135 uint32_t *msg_size, 136 VCHI_FLAGS_T flags); 137 138 // Routine to remove a message after it has been read in place with peek 139 // The first message on the queue is dequeued. 140 extern int32_t vchi_msg_remove(VCHI_SERVICE_HANDLE_T handle); 141 142 // Routine to look at a message in place. 143 // The message is dequeued, so the caller is left holding it; the descriptor is 144 // filled in and must be released when the user has finished with the message. 145 extern int32_t vchi_msg_hold(VCHI_SERVICE_HANDLE_T handle, 146 void **data, // } may be NULL, as info can be 147 uint32_t *msg_size, // } obtained from HELD_MSG_T 148 VCHI_FLAGS_T flags, 149 struct vchi_held_msg *message_descriptor); 150 151 // Initialise an iterator to look through messages in place 152 extern int32_t vchi_msg_look_ahead(VCHI_SERVICE_HANDLE_T handle, 153 struct vchi_msg_iter *iter, 154 VCHI_FLAGS_T flags); 155 156 /****************************************************************************** 157 Global service support API - operations on held messages and message iterators 158 *****************************************************************************/ 159 160 // Routine to get the address of a held message 161 extern void *vchi_held_msg_ptr(const struct vchi_held_msg *message); 162 163 // Routine to get the size of a held message 164 extern int32_t vchi_held_msg_size(const struct vchi_held_msg *message); 165 166 // Routine to get the transmit timestamp as written into the header by the peer 167 extern uint32_t vchi_held_msg_tx_timestamp(const struct vchi_held_msg *message); 168 169 // Routine to get the reception timestamp, written as we parsed the header 170 extern uint32_t vchi_held_msg_rx_timestamp(const struct vchi_held_msg *message); 171 172 // Routine to release a held message after it has been processed 173 extern int32_t vchi_held_msg_release(struct vchi_held_msg *message); 174 175 // Indicates whether the iterator has a next message. 176 extern int32_t vchi_msg_iter_has_next(const struct vchi_msg_iter *iter); 177 178 // Return the pointer and length for the next message and advance the iterator. 179 extern int32_t vchi_msg_iter_next(struct vchi_msg_iter *iter, 180 void **data, 181 uint32_t *msg_size); 182 183 // Remove the last message returned by vchi_msg_iter_next. 184 // Can only be called once after each call to vchi_msg_iter_next. 185 extern int32_t vchi_msg_iter_remove(struct vchi_msg_iter *iter); 186 187 // Hold the last message returned by vchi_msg_iter_next. 188 // Can only be called once after each call to vchi_msg_iter_next. 189 extern int32_t vchi_msg_iter_hold(struct vchi_msg_iter *iter, 190 struct vchi_held_msg *message); 191 192 // Return information for the next message, and hold it, advancing the iterator. 193 extern int32_t vchi_msg_iter_hold_next(struct vchi_msg_iter *iter, 194 void **data, // } may be NULL 195 uint32_t *msg_size, // } 196 struct vchi_held_msg *message); 197 198 /****************************************************************************** 199 Global bulk API 200 *****************************************************************************/ 201 202 // Routine to prepare interface for a transfer from the other side 203 extern int32_t vchi_bulk_queue_receive(VCHI_SERVICE_HANDLE_T handle, 204 void *data_dst, 205 uint32_t data_size, 206 VCHI_FLAGS_T flags, 207 void *transfer_handle); 208 209 // Prepare interface for a transfer from the other side into relocatable memory. 210 int32_t vchi_bulk_queue_receive_reloc(const VCHI_SERVICE_HANDLE_T handle, 211 uint32_t offset, 212 uint32_t data_size, 213 const VCHI_FLAGS_T flags, 214 void * const bulk_handle); 215 216 // Routine to queue up data ready for transfer to the other (once they have signalled they are ready) 217 extern int32_t vchi_bulk_queue_transmit(VCHI_SERVICE_HANDLE_T handle, 218 const void *data_src, 219 uint32_t data_size, 220 VCHI_FLAGS_T flags, 221 void *transfer_handle); 222 223 /****************************************************************************** 224 Configuration plumbing 225 *****************************************************************************/ 226 227 #ifdef __cplusplus 228 } 229 #endif 230 231 extern int32_t vchi_bulk_queue_transmit_reloc(VCHI_SERVICE_HANDLE_T handle, 232 uint32_t offset, 233 uint32_t data_size, 234 VCHI_FLAGS_T flags, 235 void *transfer_handle); 236 #endif /* VCHI_H_ */ 237 238 /****************************** End of file **********************************/ 239
