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 **********************************/