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 destroy a service
  87 extern int32_t vchi_service_destroy(const struct vchi_service_handle *handle);
  88
  89 // Routine to open a named service
  90 extern int32_t vchi_service_open(struct vchi_instance_handle *instance_handle,
  91                                  struct service_creation *setup,
  92                                  struct vchi_service_handle **handle);
  93
  94 extern int32_t vchi_get_peer_version(const struct vchi_service_handle *handle,
  95                                      short *peer_version);
  96
  97 // Routine to close a named service
  98 extern int32_t vchi_service_close(const struct vchi_service_handle *handle);
  99
 100 // Routine to increment ref count on a named service
 101 extern int32_t vchi_service_use(const struct vchi_service_handle *handle);
 102
 103 // Routine to decrement ref count on a named service
 104 extern int32_t vchi_service_release(const struct vchi_service_handle *handle);
 105
 106 // Routine to set a control option for a named service
 107 extern int32_t vchi_service_set_option(const struct vchi_service_handle *handle,
 108                                        enum vchi_service_option option,
 109                                        int value);
 110
 111 /* Routine to send a message from kernel memory across a service */
 112 extern int
 113 vchi_queue_kernel_message(struct vchi_service_handle *handle,
 114                           void *data,
 115                           unsigned int size);
 116
 117 /* Routine to send a message from user memory across a service */
 118 extern int
 119 vchi_queue_user_message(struct vchi_service_handle *handle,
 120                         void __user *data,
 121                         unsigned int size);
 122
 123 // Routine to receive a msg from a service
 124 // Dequeue is equivalent to hold, copy into client buffer, release
 125 extern int32_t vchi_msg_dequeue(struct vchi_service_handle *handle,
 126                                 void *data,
 127                                 uint32_t max_data_size_to_read,
 128                                 uint32_t *actual_msg_size,
 129                                 enum vchi_flags flags);
 130
 131 // Routine to look at a message in place.
 132 // The message is not dequeued, so a subsequent call to peek or dequeue
 133 // will return the same message.
 134 extern int32_t vchi_msg_peek(struct vchi_service_handle *handle,
 135                              void **data,
 136                              uint32_t *msg_size,
 137                              enum vchi_flags flags);
 138
 139 // Routine to remove a message after it has been read in place with peek
 140 // The first message on the queue is dequeued.
 141 extern int32_t vchi_msg_remove(struct vchi_service_handle *handle);
 142
 143 // Routine to look at a message in place.
 144 // The message is dequeued, so the caller is left holding it; the descriptor is
 145 // filled in and must be released when the user has finished with the message.
 146 extern int32_t vchi_msg_hold(struct vchi_service_handle *handle,
 147                              void **data,        // } may be NULL, as info can be
 148                              uint32_t *msg_size, // } obtained from HELD_MSG_T
 149                              enum vchi_flags flags,
 150                              struct vchi_held_msg *message_descriptor);
 151
 152 // Initialise an iterator to look through messages in place
 153 extern int32_t vchi_msg_look_ahead(struct vchi_service_handle *handle,
 154                                    struct vchi_msg_iter *iter,
 155                                    enum vchi_flags flags);
 156
 157 /*******************************************************************************
 158  * Global service support API - operations on held messages
 159  * and message iterators
 160  ******************************************************************************/
 161
 162 // Routine to get the address of a held message
 163 extern void *vchi_held_msg_ptr(const struct vchi_held_msg *message);
 164
 165 // Routine to get the size of a held message
 166 extern int32_t vchi_held_msg_size(const struct vchi_held_msg *message);
 167
 168 // Routine to get the transmit timestamp as written into the header by the peer
 169 extern uint32_t vchi_held_msg_tx_timestamp(const struct vchi_held_msg *message);
 170
 171 // Routine to get the reception timestamp, written as we parsed the header
 172 extern uint32_t vchi_held_msg_rx_timestamp(const struct vchi_held_msg *message);
 173
 174 // Routine to release a held message after it has been processed
 175 extern int32_t vchi_held_msg_release(struct vchi_held_msg *message);
 176
 177 // Indicates whether the iterator has a next message.
 178 extern int32_t vchi_msg_iter_has_next(const struct vchi_msg_iter *iter);
 179
 180 // Return the pointer and length for the next message and advance the iterator.
 181 extern int32_t vchi_msg_iter_next(struct vchi_msg_iter *iter,
 182                                   void **data,
 183                                   uint32_t *msg_size);
 184
 185 // Remove the last message returned by vchi_msg_iter_next.
 186 // Can only be called once after each call to vchi_msg_iter_next.
 187 extern int32_t vchi_msg_iter_remove(struct vchi_msg_iter *iter);
 188
 189 // Hold the last message returned by vchi_msg_iter_next.
 190 // Can only be called once after each call to vchi_msg_iter_next.
 191 extern int32_t vchi_msg_iter_hold(struct vchi_msg_iter *iter,
 192                                   struct vchi_held_msg *message);
 193
 194 // Return information for the next message, and hold it, advancing the iterator.
 195 extern int32_t vchi_msg_iter_hold_next(struct vchi_msg_iter *iter,
 196                                        void **data,        // } may be NULL
 197                                        uint32_t *msg_size, // }
 198                                        struct vchi_held_msg *message);
 199
 200 /******************************************************************************
 201  * Global bulk API
 202  *****************************************************************************/
 203
 204 // Routine to prepare interface for a transfer from the other side
 205 extern int32_t vchi_bulk_queue_receive(struct vchi_service_handle *handle,
 206                                        void *data_dst,
 207                                        uint32_t data_size,
 208                                        enum vchi_flags flags,
 209                                        void *transfer_handle);
 210
 211 // Prepare interface for a transfer from the other side into relocatable memory.
 212 int32_t vchi_bulk_queue_receive_reloc(const struct vchi_service_handle *handle,
 213                                       uint32_t offset,
 214                                       uint32_t data_size,
 215                                       const enum vchi_flags flags,
 216                                       void * const bulk_handle);
 217
 218 // Routine to queue up data ready for transfer to the other (once they have signalled they are ready)
 219 extern int32_t vchi_bulk_queue_transmit(struct vchi_service_handle *handle,
 220                                         const void *data_src,
 221                                         uint32_t data_size,
 222                                         enum vchi_flags flags,
 223                                         void *transfer_handle);
 224
 225 /******************************************************************************
 226  * Configuration plumbing
 227  *****************************************************************************/
 228
 229 #ifdef __cplusplus
 230 }
 231 #endif
 232
 233 extern int32_t vchi_bulk_queue_transmit_reloc(struct vchi_service_handle *handle,
 234                                               uint32_t offset,
 235                                               uint32_t data_size,
 236                                               enum vchi_flags flags,
 237                                               void *transfer_handle);
 238 #endif /* VCHI_H_ */
 239
 240 /****************************** End of file **********************************/