xref: /freebsd/sys/contrib/vchiq/interface/vchi/connections/connection.h (revision dd41de95a84d979615a2ef11df6850622bf6184e)
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 CONNECTION_H_
35 #define CONNECTION_H_
36 
37 #include "interface/vchi/vchi_cfg_internal.h"
38 #include "interface/vchi/vchi_common.h"
39 #include "interface/vchi/message_drivers/message.h"
40 
41 /******************************************************************************
42  Global defs
43  *****************************************************************************/
44 
45 // Opaque handle for a connection / service pair
46 typedef struct opaque_vchi_connection_connected_service_handle_t *VCHI_CONNECTION_SERVICE_HANDLE_T;
47 
48 // opaque handle to the connection state information
49 typedef struct opaque_vchi_connection_info_t VCHI_CONNECTION_STATE_T;
50 
51 typedef struct vchi_connection_t VCHI_CONNECTION_T;
52 
53 
54 /******************************************************************************
55  API
56  *****************************************************************************/
57 
58 // Routine to init a connection with a particular low level driver
59 typedef VCHI_CONNECTION_STATE_T * (*VCHI_CONNECTION_INIT_T)( struct vchi_connection_t * connection,
60                                                              const VCHI_MESSAGE_DRIVER_T * driver );
61 
62 // Routine to control CRC enabling at a connection level
63 typedef int32_t (*VCHI_CONNECTION_CRC_CONTROL_T)( VCHI_CONNECTION_STATE_T *state_handle,
64                                                   VCHI_CRC_CONTROL_T control );
65 
66 // Routine to create a service
67 typedef int32_t (*VCHI_CONNECTION_SERVICE_CONNECT_T)( VCHI_CONNECTION_STATE_T *state_handle,
68                                                       int32_t service_id,
69                                                       uint32_t rx_fifo_size,
70                                                       uint32_t tx_fifo_size,
71                                                       int server,
72                                                       VCHI_CALLBACK_T callback,
73                                                       void *callback_param,
74                                                       int32_t want_crc,
75                                                       int32_t want_unaligned_bulk_rx,
76                                                       int32_t want_unaligned_bulk_tx,
77                                                       VCHI_CONNECTION_SERVICE_HANDLE_T *service_handle );
78 
79 // Routine to close a service
80 typedef int32_t (*VCHI_CONNECTION_SERVICE_DISCONNECT_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle );
81 
82 // Routine to queue a message
83 typedef int32_t (*VCHI_CONNECTION_SERVICE_QUEUE_MESSAGE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
84                                                             const void *data,
85                                                             uint32_t data_size,
86                                                             VCHI_FLAGS_T flags,
87                                                             void *msg_handle );
88 
89 // scatter-gather (vector) message queueing
90 typedef int32_t (*VCHI_CONNECTION_SERVICE_QUEUE_MESSAGEV_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
91                                                              VCHI_MSG_VECTOR_T *vector,
92                                                              uint32_t count,
93                                                              VCHI_FLAGS_T flags,
94                                                              void *msg_handle );
95 
96 // Routine to dequeue a message
97 typedef int32_t (*VCHI_CONNECTION_SERVICE_DEQUEUE_MESSAGE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
98                                                               void *data,
99                                                               uint32_t max_data_size_to_read,
100                                                               uint32_t *actual_msg_size,
101                                                               VCHI_FLAGS_T flags );
102 
103 // Routine to peek at a message
104 typedef int32_t (*VCHI_CONNECTION_SERVICE_PEEK_MESSAGE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
105                                                            void **data,
106                                                            uint32_t *msg_size,
107                                                            VCHI_FLAGS_T flags );
108 
109 // Routine to hold a message
110 typedef int32_t (*VCHI_CONNECTION_SERVICE_HOLD_MESSAGE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
111                                                            void **data,
112                                                            uint32_t *msg_size,
113                                                            VCHI_FLAGS_T flags,
114                                                            void **message_handle );
115 
116 // Routine to initialise a received message iterator
117 typedef int32_t (*VCHI_CONNECTION_SERVICE_LOOKAHEAD_MESSAGE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
118                                                                 VCHI_MSG_ITER_T *iter,
119                                                                 VCHI_FLAGS_T flags );
120 
121 // Routine to release a held message
122 typedef int32_t (*VCHI_CONNECTION_HELD_MSG_RELEASE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
123                                                        void *message_handle );
124 
125 // Routine to get info on a held message
126 typedef int32_t (*VCHI_CONNECTION_HELD_MSG_INFO_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
127                                                     void *message_handle,
128                                                     void **data,
129                                                     int32_t *msg_size,
130                                                     uint32_t *tx_timestamp,
131                                                     uint32_t *rx_timestamp );
132 
133 // Routine to check whether the iterator has a next message
134 typedef int32_t (*VCHI_CONNECTION_MSG_ITER_HAS_NEXT_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service,
135                                                        const VCHI_MSG_ITER_T *iter );
136 
137 // Routine to advance the iterator
138 typedef int32_t (*VCHI_CONNECTION_MSG_ITER_NEXT_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service,
139                                                     VCHI_MSG_ITER_T *iter,
140                                                     void **data,
141                                                     uint32_t *msg_size );
142 
143 // Routine to remove the last message returned by the iterator
144 typedef int32_t (*VCHI_CONNECTION_MSG_ITER_REMOVE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service,
145                                                       VCHI_MSG_ITER_T *iter );
146 
147 // Routine to hold the last message returned by the iterator
148 typedef int32_t (*VCHI_CONNECTION_MSG_ITER_HOLD_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service,
149                                                     VCHI_MSG_ITER_T *iter,
150                                                     void **msg_handle );
151 
152 // Routine to transmit bulk data
153 typedef int32_t (*VCHI_CONNECTION_BULK_QUEUE_TRANSMIT_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
154                                                           const void *data_src,
155                                                           uint32_t data_size,
156                                                           VCHI_FLAGS_T flags,
157                                                           void *bulk_handle );
158 
159 // Routine to receive data
160 typedef int32_t (*VCHI_CONNECTION_BULK_QUEUE_RECEIVE_T)( VCHI_CONNECTION_SERVICE_HANDLE_T service_handle,
161                                                          void *data_dst,
162                                                          uint32_t data_size,
163                                                          VCHI_FLAGS_T flags,
164                                                          void *bulk_handle );
165 
166 // Routine to report if a server is available
167 typedef int32_t (*VCHI_CONNECTION_SERVER_PRESENT)( VCHI_CONNECTION_STATE_T *state, int32_t service_id, int32_t peer_flags );
168 
169 // Routine to report the number of RX slots available
170 typedef int (*VCHI_CONNECTION_RX_SLOTS_AVAILABLE)( const VCHI_CONNECTION_STATE_T *state );
171 
172 // Routine to report the RX slot size
173 typedef uint32_t (*VCHI_CONNECTION_RX_SLOT_SIZE)( const VCHI_CONNECTION_STATE_T *state );
174 
175 // Callback to indicate that the other side has added a buffer to the rx bulk DMA FIFO
176 typedef void (*VCHI_CONNECTION_RX_BULK_BUFFER_ADDED)(VCHI_CONNECTION_STATE_T *state,
177                                                      int32_t service,
178                                                      uint32_t length,
179                                                      MESSAGE_TX_CHANNEL_T channel,
180                                                      uint32_t channel_params,
181                                                      uint32_t data_length,
182                                                      uint32_t data_offset);
183 
184 // Callback to inform a service that a Xon or Xoff message has been received
185 typedef void (*VCHI_CONNECTION_FLOW_CONTROL)(VCHI_CONNECTION_STATE_T *state, int32_t service_id, int32_t xoff);
186 
187 // Callback to inform a service that a server available reply message has been received
188 typedef void (*VCHI_CONNECTION_SERVER_AVAILABLE_REPLY)(VCHI_CONNECTION_STATE_T *state, int32_t service_id, uint32_t flags);
189 
190 // Callback to indicate that bulk auxiliary messages have arrived
191 typedef void (*VCHI_CONNECTION_BULK_AUX_RECEIVED)(VCHI_CONNECTION_STATE_T *state);
192 
193 // Callback to indicate that bulk auxiliary messages have arrived
194 typedef void (*VCHI_CONNECTION_BULK_AUX_TRANSMITTED)(VCHI_CONNECTION_STATE_T *state, void *handle);
195 
196 // Callback with all the connection info you require
197 typedef void (*VCHI_CONNECTION_INFO)(VCHI_CONNECTION_STATE_T *state, uint32_t protocol_version, uint32_t slot_size, uint32_t num_slots, uint32_t min_bulk_size);
198 
199 // Callback to inform of a disconnect
200 typedef void (*VCHI_CONNECTION_DISCONNECT)(VCHI_CONNECTION_STATE_T *state, uint32_t flags);
201 
202 // Callback to inform of a power control request
203 typedef void (*VCHI_CONNECTION_POWER_CONTROL)(VCHI_CONNECTION_STATE_T *state, MESSAGE_TX_CHANNEL_T channel, int32_t enable);
204 
205 // allocate memory suitably aligned for this connection
206 typedef void * (*VCHI_BUFFER_ALLOCATE)(VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, uint32_t * length);
207 
208 // free memory allocated by buffer_allocate
209 typedef void   (*VCHI_BUFFER_FREE)(VCHI_CONNECTION_SERVICE_HANDLE_T service_handle, void * address);
210 
211 
212 /******************************************************************************
213  System driver struct
214  *****************************************************************************/
215 
216 struct opaque_vchi_connection_api_t
217 {
218    // Routine to init the connection
219    VCHI_CONNECTION_INIT_T                      init;
220 
221    // Connection-level CRC control
222    VCHI_CONNECTION_CRC_CONTROL_T               crc_control;
223 
224    // Routine to connect to or create service
225    VCHI_CONNECTION_SERVICE_CONNECT_T           service_connect;
226 
227    // Routine to disconnect from a service
228    VCHI_CONNECTION_SERVICE_DISCONNECT_T        service_disconnect;
229 
230    // Routine to queue a message
231    VCHI_CONNECTION_SERVICE_QUEUE_MESSAGE_T     service_queue_msg;
232 
233    // scatter-gather (vector) message queue
234    VCHI_CONNECTION_SERVICE_QUEUE_MESSAGEV_T    service_queue_msgv;
235 
236    // Routine to dequeue a message
237    VCHI_CONNECTION_SERVICE_DEQUEUE_MESSAGE_T   service_dequeue_msg;
238 
239    // Routine to peek at a message
240    VCHI_CONNECTION_SERVICE_PEEK_MESSAGE_T      service_peek_msg;
241 
242    // Routine to hold a message
243    VCHI_CONNECTION_SERVICE_HOLD_MESSAGE_T      service_hold_msg;
244 
245    // Routine to initialise a received message iterator
246    VCHI_CONNECTION_SERVICE_LOOKAHEAD_MESSAGE_T service_look_ahead_msg;
247 
248    // Routine to release a message
249    VCHI_CONNECTION_HELD_MSG_RELEASE_T          held_msg_release;
250 
251    // Routine to get information on a held message
252    VCHI_CONNECTION_HELD_MSG_INFO_T             held_msg_info;
253 
254    // Routine to check for next message on iterator
255    VCHI_CONNECTION_MSG_ITER_HAS_NEXT_T         msg_iter_has_next;
256 
257    // Routine to get next message on iterator
258    VCHI_CONNECTION_MSG_ITER_NEXT_T             msg_iter_next;
259 
260    // Routine to remove the last message returned by iterator
261    VCHI_CONNECTION_MSG_ITER_REMOVE_T           msg_iter_remove;
262 
263    // Routine to hold the last message returned by iterator
264    VCHI_CONNECTION_MSG_ITER_HOLD_T             msg_iter_hold;
265 
266    // Routine to transmit bulk data
267    VCHI_CONNECTION_BULK_QUEUE_TRANSMIT_T       bulk_queue_transmit;
268 
269    // Routine to receive data
270    VCHI_CONNECTION_BULK_QUEUE_RECEIVE_T        bulk_queue_receive;
271 
272    // Routine to report the available servers
273    VCHI_CONNECTION_SERVER_PRESENT              server_present;
274 
275    // Routine to report the number of RX slots available
276    VCHI_CONNECTION_RX_SLOTS_AVAILABLE          connection_rx_slots_available;
277 
278    // Routine to report the RX slot size
279    VCHI_CONNECTION_RX_SLOT_SIZE                connection_rx_slot_size;
280 
281    // Callback to indicate that the other side has added a buffer to the rx bulk DMA FIFO
282    VCHI_CONNECTION_RX_BULK_BUFFER_ADDED        rx_bulk_buffer_added;
283 
284    // Callback to inform a service that a Xon or Xoff message has been received
285    VCHI_CONNECTION_FLOW_CONTROL                flow_control;
286 
287    // Callback to inform a service that a server available reply message has been received
288    VCHI_CONNECTION_SERVER_AVAILABLE_REPLY      server_available_reply;
289 
290    // Callback to indicate that bulk auxiliary messages have arrived
291    VCHI_CONNECTION_BULK_AUX_RECEIVED           bulk_aux_received;
292 
293    // Callback to indicate that a bulk auxiliary message has been transmitted
294    VCHI_CONNECTION_BULK_AUX_TRANSMITTED        bulk_aux_transmitted;
295 
296    // Callback to provide information about the connection
297    VCHI_CONNECTION_INFO                        connection_info;
298 
299    // Callback to notify that peer has requested disconnect
300    VCHI_CONNECTION_DISCONNECT                  disconnect;
301 
302    // Callback to notify that peer has requested power change
303    VCHI_CONNECTION_POWER_CONTROL               power_control;
304 
305    // allocate memory suitably aligned for this connection
306    VCHI_BUFFER_ALLOCATE                        buffer_allocate;
307 
308    // free memory allocated by buffer_allocate
309    VCHI_BUFFER_FREE                            buffer_free;
310 
311 };
312 
313 struct vchi_connection_t {
314    const VCHI_CONNECTION_API_T *api;
315    VCHI_CONNECTION_STATE_T     *state;
316 #ifdef VCHI_COARSE_LOCKING
317    struct semaphore             sem;
318 #endif
319 };
320 
321 
322 #endif /* CONNECTION_H_ */
323 
324 /****************************** End of file **********************************/
325