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 VCHIQ instance
  53 struct vchiq_instance;
  54
  55 // Opaque handle for a server or client
  56 struct vchi_service;
  57
  58 /******************************************************************************
  59  * Global funcs - implementation is specific to which side you are on
  60  * (local / remote)
  61  *****************************************************************************/
  62
  63 // Routine used to initialise the vchi on both local + remote connections
  64 extern int32_t vchi_initialise(struct vchiq_instance **instance);
  65
  66 extern int32_t vchi_connect(struct vchiq_instance *instance);
  67
  68 //When this is called, ensure that all services have no data pending.
  69 //Bulk transfers can remain 'queued'
  70 extern int32_t vchi_disconnect(struct vchiq_instance *instance);
  71
  72 /******************************************************************************
  73  * Global service API
  74  *****************************************************************************/
  75 // Routine to open a named service
  76 extern int32_t vchi_service_open(struct vchiq_instance *instance,
  77                                  struct service_creation *setup,
  78                                  struct vchi_service **service);
  79
  80 extern int32_t vchi_get_peer_version(struct vchi_service *service,
  81                                      short *peer_version);
  82
  83 // Routine to close a named service
  84 extern int32_t vchi_service_close(struct vchi_service *service);
  85
  86 // Routine to increment ref count on a named service
  87 extern int32_t vchi_service_use(struct vchi_service *service);
  88
  89 // Routine to decrement ref count on a named service
  90 extern int32_t vchi_service_release(struct vchi_service *service);
  91
  92 /* Routine to send a message from kernel memory across a service */
  93 extern int vchi_queue_kernel_message(struct vchi_service *service, void *data,
  94                                      unsigned int size);
  95
  96 // Routine to receive a msg from a service
  97 // Dequeue is equivalent to hold, copy into client buffer, release
  98 extern int32_t vchi_msg_dequeue(struct vchi_service *service, void *data,
  99                                 uint32_t max_data_size_to_read,
 100                                 uint32_t *actual_msg_size,
 101                                 enum vchi_flags flags);
 102
 103 // Routine to look at a message in place.
 104 // The message is dequeued, so the caller is left holding it; the descriptor is
 105 // filled in and must be released when the user has finished with the message.
 106 extern int32_t vchi_msg_hold(struct vchi_service *service,
 107                              void **data,        // } may be NULL, as info can be
 108                              uint32_t *msg_size, // } obtained from HELD_MSG_T
 109                              enum vchi_flags flags,
 110                              struct vchi_held_msg *message_descriptor);
 111
 112 /*******************************************************************************
 113  * Global service support API - operations on held messages
 114  * and message iterators
 115  ******************************************************************************/
 116
 117 // Routine to release a held message after it has been processed
 118 extern int32_t vchi_held_msg_release(struct vchi_held_msg *message);
 119
 120 /******************************************************************************
 121  * Global bulk API
 122  *****************************************************************************/
 123
 124 // Routine to prepare interface for a transfer from the other side
 125 extern int32_t vchi_bulk_queue_receive(struct vchi_service *service,
 126                                        void *data_dst,
 127                                        uint32_t data_size,
 128                                        enum vchi_flags flags,
 129                                        void *transfer_handle);
 130
 131 // Routine to queue up data ready for transfer to the other (once they have signalled they are ready)
 132 extern int32_t vchi_bulk_queue_transmit(struct vchi_service *service,
 133                                         const void *data_src,
 134                                         uint32_t data_size,
 135                                         enum vchi_flags flags,
 136                                         void *transfer_handle);
 137
 138 /******************************************************************************
 139  * Configuration plumbing
 140  *****************************************************************************/
 141
 142 #endif /* VCHI_H_ */
 143
 144 /****************************** End of file **********************************/