drivers/staging/vc04_services/interface/vchi/vchi.h

   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 "vchi_cfg.h"
   8 #include "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 callback;
  49         void *callback_param;
  50 };
  51
  52 // Opaque handle for a VCHI instance
  53 struct vchi_instance_handle;
  54
  55 // Opaque handle for a server or client
  56 struct vchi_service_handle;
  57
  58 /******************************************************************************
  59  * Global funcs - implementation is specific to which side you are on
  60  * (local / remote)
  61  *****************************************************************************/
  62
  63 #ifdef __cplusplus
  64 extern "C" {
  65 #endif
  66
  67 // Routine used to initialise the vchi on both local + remote connections
  68 extern int32_t vchi_initialise(struct vchi_instance_handle **instance_handle);
  69
  70 extern int32_t vchi_exit(void);
  71
  72 extern int32_t vchi_connect(struct vchi_instance_handle *instance_handle);
  73
  74 //When this is called, ensure that all services have no data pending.
  75 //Bulk transfers can remain 'queued'
  76 extern int32_t vchi_disconnect(struct vchi_instance_handle *instance_handle);
  77
  78 // helper functions
  79 extern void *vchi_allocate_buffer(struct vchi_service_handle *handle, uint32_t *length);
  80 extern void vchi_free_buffer(struct vchi_service_handle *handle, void *address);
  81 extern uint32_t vchi_current_time(struct vchi_instance_handle *instance_handle);
  82
  83 /******************************************************************************
  84  * Global service API
  85  *****************************************************************************/
  86 // Routine to open a named service
  87 extern int32_t vchi_service_open(struct vchi_instance_handle *instance_handle,
  88                                  struct service_creation *setup,
  89                                  struct vchi_service_handle **handle);
  90
  91 extern int32_t vchi_get_peer_version(const struct vchi_service_handle *handle,
  92                                      short *peer_version);
  93
  94 // Routine to close a named service
  95 extern int32_t vchi_service_close(const struct vchi_service_handle *handle);
  96
  97 // Routine to increment ref count on a named service
  98 extern int32_t vchi_service_use(const struct vchi_service_handle *handle);
  99
 100 // Routine to decrement ref count on a named service
 101 extern int32_t vchi_service_release(const struct vchi_service_handle *handle);
 102
 103 /* Routine to send a message from kernel memory across a service */
 104 extern int
 105 vchi_queue_kernel_message(struct vchi_service_handle *handle,
 106                           void *data,
 107                           unsigned int size);
 108
 109 // Routine to receive a msg from a service
 110 // Dequeue is equivalent to hold, copy into client buffer, release
 111 extern int32_t vchi_msg_dequeue(struct vchi_service_handle *handle,
 112                                 void *data,
 113                                 uint32_t max_data_size_to_read,
 114                                 uint32_t *actual_msg_size,
 115                                 enum vchi_flags flags);
 116
 117 // Routine to look at a message in place.
 118 // The message is not dequeued, so a subsequent call to peek or dequeue
 119 // will return the same message.
 120 extern int32_t vchi_msg_peek(struct vchi_service_handle *handle,
 121                              void **data,
 122                              uint32_t *msg_size,
 123                              enum vchi_flags flags);
 124
 125 // Routine to remove a message after it has been read in place with peek
 126 // The first message on the queue is dequeued.
 127 extern int32_t vchi_msg_remove(struct vchi_service_handle *handle);
 128
 129 // Routine to look at a message in place.
 130 // The message is dequeued, so the caller is left holding it; the descriptor is
 131 // filled in and must be released when the user has finished with the message.
 132 extern int32_t vchi_msg_hold(struct vchi_service_handle *handle,
 133                              void **data,        // } may be NULL, as info can be
 134                              uint32_t *msg_size, // } obtained from HELD_MSG_T
 135                              enum vchi_flags flags,
 136                              struct vchi_held_msg *message_descriptor);
 137
 138 // Initialise an iterator to look through messages in place
 139 extern int32_t vchi_msg_look_ahead(struct vchi_service_handle *handle,
 140                                    struct vchi_msg_iter *iter,
 141                                    enum vchi_flags flags);
 142
 143 /*******************************************************************************
 144  * Global service support API - operations on held messages
 145  * and message iterators
 146  ******************************************************************************/
 147
 148 // Routine to get the address of a held message
 149 extern void *vchi_held_msg_ptr(const struct vchi_held_msg *message);
 150
 151 // Routine to get the size of a held message
 152 extern int32_t vchi_held_msg_size(const struct vchi_held_msg *message);
 153
 154 // Routine to get the transmit timestamp as written into the header by the peer
 155 extern uint32_t vchi_held_msg_tx_timestamp(const struct vchi_held_msg *message);
 156
 157 // Routine to get the reception timestamp, written as we parsed the header
 158 extern uint32_t vchi_held_msg_rx_timestamp(const struct vchi_held_msg *message);
 159
 160 // Routine to release a held message after it has been processed
 161 extern int32_t vchi_held_msg_release(struct vchi_held_msg *message);
 162
 163 // Indicates whether the iterator has a next message.
 164 extern int32_t vchi_msg_iter_has_next(const struct vchi_msg_iter *iter);
 165
 166 // Return the pointer and length for the next message and advance the iterator.
 167 extern int32_t vchi_msg_iter_next(struct vchi_msg_iter *iter,
 168                                   void **data,
 169                                   uint32_t *msg_size);
 170
 171 // Remove the last message returned by vchi_msg_iter_next.
 172 // Can only be called once after each call to vchi_msg_iter_next.
 173 extern int32_t vchi_msg_iter_remove(struct vchi_msg_iter *iter);
 174
 175 // Hold the last message returned by vchi_msg_iter_next.
 176 // Can only be called once after each call to vchi_msg_iter_next.
 177 extern int32_t vchi_msg_iter_hold(struct vchi_msg_iter *iter,
 178                                   struct vchi_held_msg *message);
 179
 180 // Return information for the next message, and hold it, advancing the iterator.
 181 extern int32_t vchi_msg_iter_hold_next(struct vchi_msg_iter *iter,
 182                                        void **data,        // } may be NULL
 183                                        uint32_t *msg_size, // }
 184                                        struct vchi_held_msg *message);
 185
 186 /******************************************************************************
 187  * Global bulk API
 188  *****************************************************************************/
 189
 190 // Routine to prepare interface for a transfer from the other side
 191 extern int32_t vchi_bulk_queue_receive(struct vchi_service_handle *handle,
 192                                        void *data_dst,
 193                                        uint32_t data_size,
 194                                        enum vchi_flags flags,
 195                                        void *transfer_handle);
 196
 197 // Prepare interface for a transfer from the other side into relocatable memory.
 198 int32_t vchi_bulk_queue_receive_reloc(const struct vchi_service_handle *handle,
 199                                       uint32_t offset,
 200                                       uint32_t data_size,
 201                                       const enum vchi_flags flags,
 202                                       void * const bulk_handle);
 203
 204 // Routine to queue up data ready for transfer to the other (once they have signalled they are ready)
 205 extern int32_t vchi_bulk_queue_transmit(struct vchi_service_handle *handle,
 206                                         const void *data_src,
 207                                         uint32_t data_size,
 208                                         enum vchi_flags flags,
 209                                         void *transfer_handle);
 210
 211 /******************************************************************************
 212  * Configuration plumbing
 213  *****************************************************************************/
 214
 215 #ifdef __cplusplus
 216 }
 217 #endif
 218
 219 extern int32_t vchi_bulk_queue_transmit_reloc(struct vchi_service_handle *handle,
 220                                               uint32_t offset,
 221                                               uint32_t data_size,
 222                                               enum vchi_flags flags,
 223                                               void *transfer_handle);
 224 #endif /* VCHI_H_ */
 225
 226 /****************************** End of file **********************************/