sys/contrib/vchiq/interface/vchiq_arm/vchiq_if.h

   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 VCHIQ_IF_H
  35 #define VCHIQ_IF_H
  36
  37 #include "interface/vchi/vchi_mh.h"
  38
  39 #define VCHIQ_SERVICE_HANDLE_INVALID 0
  40
  41 #define VCHIQ_SLOT_SIZE     4096
  42 #define VCHIQ_MAX_MSG_SIZE  (VCHIQ_SLOT_SIZE - sizeof(VCHIQ_HEADER_T))
  43 #define VCHIQ_CHANNEL_SIZE  VCHIQ_MAX_MSG_SIZE /* For backwards compatibility */
  44
  45 #define VCHIQ_MAKE_FOURCC(x0, x1, x2, x3) \
  46                         (((x0) << 24) | ((x1) << 16) | ((x2) << 8) | (x3))
  47 #define VCHIQ_GET_SERVICE_USERDATA(service) vchiq_get_service_userdata(service)
  48 #define VCHIQ_GET_SERVICE_FOURCC(service)   vchiq_get_service_fourcc(service)
  49
  50 typedef enum {
  51         VCHIQ_SERVICE_OPENED,         /* service, -, -             */
  52         VCHIQ_SERVICE_CLOSED,         /* service, -, -             */
  53         VCHIQ_MESSAGE_AVAILABLE,      /* service, header, -        */
  54         VCHIQ_BULK_TRANSMIT_DONE,     /* service, -, bulk_userdata */
  55         VCHIQ_BULK_RECEIVE_DONE,      /* service, -, bulk_userdata */
  56         VCHIQ_BULK_TRANSMIT_ABORTED,  /* service, -, bulk_userdata */
  57         VCHIQ_BULK_RECEIVE_ABORTED    /* service, -, bulk_userdata */
  58 } VCHIQ_REASON_T;
  59
  60 typedef enum {
  61         VCHIQ_ERROR   = -1,
  62         VCHIQ_SUCCESS = 0,
  63         VCHIQ_RETRY   = 1
  64 } VCHIQ_STATUS_T;
  65
  66 typedef enum {
  67         VCHIQ_BULK_MODE_CALLBACK,
  68         VCHIQ_BULK_MODE_BLOCKING,
  69         VCHIQ_BULK_MODE_NOCALLBACK,
  70         VCHIQ_BULK_MODE_WAITING         /* Reserved for internal use */
  71 } VCHIQ_BULK_MODE_T;
  72
  73 typedef enum {
  74         VCHIQ_SERVICE_OPTION_AUTOCLOSE,
  75         VCHIQ_SERVICE_OPTION_SLOT_QUOTA,
  76         VCHIQ_SERVICE_OPTION_MESSAGE_QUOTA,
  77         VCHIQ_SERVICE_OPTION_SYNCHRONOUS
  78 } VCHIQ_SERVICE_OPTION_T;
  79
  80 typedef struct vchiq_header_struct {
  81         /* The message identifier - opaque to applications. */
  82         int msgid;
  83
  84         /* Size of message data. */
  85         unsigned int size;
  86
  87         char data[0];           /* message */
  88 } VCHIQ_HEADER_T;
  89
  90 typedef struct {
  91         const void *data;
  92         unsigned int size;
  93 } VCHIQ_ELEMENT_T;
  94
  95 typedef unsigned int VCHIQ_SERVICE_HANDLE_T;
  96
  97 typedef VCHIQ_STATUS_T (*VCHIQ_CALLBACK_T)(VCHIQ_REASON_T, VCHIQ_HEADER_T *,
  98         VCHIQ_SERVICE_HANDLE_T, void *);
  99
 100 typedef struct vchiq_service_base_struct {
 101         int fourcc;
 102         VCHIQ_CALLBACK_T callback;
 103         void *userdata;
 104 } VCHIQ_SERVICE_BASE_T;
 105
 106 typedef struct vchiq_service_params_struct {
 107         int fourcc;
 108         VCHIQ_CALLBACK_T callback;
 109         void *userdata;
 110         short version;       /* Increment for non-trivial changes */
 111         short version_min;   /* Update for incompatible changes */
 112 } VCHIQ_SERVICE_PARAMS_T;
 113
 114 typedef struct vchiq_config_struct {
 115         unsigned int max_msg_size;
 116         unsigned int bulk_threshold; /* The message size above which it
 117                                         is better to use a bulk transfer
 118                                         (<= max_msg_size) */
 119         unsigned int max_outstanding_bulks;
 120         unsigned int max_services;
 121         short version;      /* The version of VCHIQ */
 122         short version_min;  /* The minimum compatible version of VCHIQ */
 123 } VCHIQ_CONFIG_T;
 124
 125 typedef struct vchiq_instance_struct *VCHIQ_INSTANCE_T;
 126 typedef void (*VCHIQ_REMOTE_USE_CALLBACK_T)(void *cb_arg);
 127
 128 extern VCHIQ_STATUS_T vchiq_initialise(VCHIQ_INSTANCE_T *pinstance);
 129 extern VCHIQ_STATUS_T vchiq_shutdown(VCHIQ_INSTANCE_T instance);
 130 extern VCHIQ_STATUS_T vchiq_connect(VCHIQ_INSTANCE_T instance);
 131 extern VCHIQ_STATUS_T vchiq_add_service(VCHIQ_INSTANCE_T instance,
 132         const VCHIQ_SERVICE_PARAMS_T *params,
 133         VCHIQ_SERVICE_HANDLE_T *pservice);
 134 extern VCHIQ_STATUS_T vchiq_open_service(VCHIQ_INSTANCE_T instance,
 135         const VCHIQ_SERVICE_PARAMS_T *params,
 136         VCHIQ_SERVICE_HANDLE_T *pservice);
 137 extern VCHIQ_STATUS_T vchiq_close_service(VCHIQ_SERVICE_HANDLE_T service);
 138 extern VCHIQ_STATUS_T vchiq_remove_service(VCHIQ_SERVICE_HANDLE_T service);
 139 extern VCHIQ_STATUS_T vchiq_use_service(VCHIQ_SERVICE_HANDLE_T service);
 140 extern VCHIQ_STATUS_T vchiq_use_service_no_resume(
 141         VCHIQ_SERVICE_HANDLE_T service);
 142 extern VCHIQ_STATUS_T vchiq_release_service(VCHIQ_SERVICE_HANDLE_T service);
 143
 144 extern VCHIQ_STATUS_T vchiq_queue_message(VCHIQ_SERVICE_HANDLE_T service,
 145         const VCHIQ_ELEMENT_T *elements, unsigned int count);
 146 extern void           vchiq_release_message(VCHIQ_SERVICE_HANDLE_T service,
 147         VCHIQ_HEADER_T *header);
 148 extern VCHIQ_STATUS_T vchiq_queue_bulk_transmit(VCHIQ_SERVICE_HANDLE_T service,
 149         void *data, unsigned int size, void *userdata);
 150 extern VCHIQ_STATUS_T vchiq_queue_bulk_receive(VCHIQ_SERVICE_HANDLE_T service,
 151         void *data, unsigned int size, void *userdata);
 152 extern VCHIQ_STATUS_T vchiq_queue_bulk_transmit_handle(
 153         VCHIQ_SERVICE_HANDLE_T service, VCHI_MEM_HANDLE_T handle,
 154         const void *offset, unsigned int size, void *userdata);
 155 extern VCHIQ_STATUS_T vchiq_queue_bulk_receive_handle(
 156         VCHIQ_SERVICE_HANDLE_T service, VCHI_MEM_HANDLE_T handle,
 157         void *offset, unsigned int size, void *userdata);
 158 extern VCHIQ_STATUS_T vchiq_bulk_transmit(VCHIQ_SERVICE_HANDLE_T service,
 159         void *data, unsigned int size, void *userdata,
 160         VCHIQ_BULK_MODE_T mode);
 161 extern VCHIQ_STATUS_T vchiq_bulk_receive(VCHIQ_SERVICE_HANDLE_T service,
 162         void *data, unsigned int size, void *userdata,
 163         VCHIQ_BULK_MODE_T mode);
 164 extern VCHIQ_STATUS_T vchiq_bulk_transmit_handle(VCHIQ_SERVICE_HANDLE_T service,
 165         VCHI_MEM_HANDLE_T handle, const void *offset, unsigned int size,
 166         void *userdata, VCHIQ_BULK_MODE_T mode);
 167 extern VCHIQ_STATUS_T vchiq_bulk_receive_handle(VCHIQ_SERVICE_HANDLE_T service,
 168         VCHI_MEM_HANDLE_T handle, void *offset, unsigned int size,
 169         void *userdata, VCHIQ_BULK_MODE_T mode);
 170 extern int   vchiq_get_client_id(VCHIQ_SERVICE_HANDLE_T service);
 171 extern void *vchiq_get_service_userdata(VCHIQ_SERVICE_HANDLE_T service);
 172 extern int   vchiq_get_service_fourcc(VCHIQ_SERVICE_HANDLE_T service);
 173 extern VCHIQ_STATUS_T vchiq_get_config(VCHIQ_INSTANCE_T instance,
 174         int config_size, VCHIQ_CONFIG_T *pconfig);
 175 extern VCHIQ_STATUS_T vchiq_set_service_option(VCHIQ_SERVICE_HANDLE_T service,
 176         VCHIQ_SERVICE_OPTION_T option, int value);
 177
 178 extern VCHIQ_STATUS_T vchiq_remote_use(VCHIQ_INSTANCE_T instance,
 179         VCHIQ_REMOTE_USE_CALLBACK_T callback, void *cb_arg);
 180 extern VCHIQ_STATUS_T vchiq_remote_release(VCHIQ_INSTANCE_T instance);
 181
 182 extern VCHIQ_STATUS_T vchiq_dump_phys_mem(VCHIQ_SERVICE_HANDLE_T service,
 183         void *ptr, size_t num_bytes);
 184
 185 extern VCHIQ_STATUS_T vchiq_get_peer_version(VCHIQ_SERVICE_HANDLE_T handle,
 186       short *peer_version);
 187
 188 #endif /* VCHIQ_IF_H */