drivers/staging/vc04_services/interface/vchi/vchi_common.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 VCHI_COMMON_H_
  35 #define VCHI_COMMON_H_
  36
  37
  38 //flags used when sending messages (must be bitmapped)
  39 typedef enum {
  40    VCHI_FLAGS_NONE                      = 0x0,
  41    VCHI_FLAGS_BLOCK_UNTIL_OP_COMPLETE   = 0x1,   // waits for message to be received, or sent (NB. not the same as being seen on other side)
  42    VCHI_FLAGS_CALLBACK_WHEN_OP_COMPLETE = 0x2,   // run a callback when message sent
  43    VCHI_FLAGS_BLOCK_UNTIL_QUEUED        = 0x4,   // return once the transfer is in a queue ready to go
  44    VCHI_FLAGS_ALLOW_PARTIAL             = 0x8,
  45    VCHI_FLAGS_BLOCK_UNTIL_DATA_READ     = 0x10,
  46    VCHI_FLAGS_CALLBACK_WHEN_DATA_READ   = 0x20,
  47
  48    VCHI_FLAGS_ALIGN_SLOT            = 0x000080,  // internal use only
  49    VCHI_FLAGS_BULK_AUX_QUEUED       = 0x010000,  // internal use only
  50    VCHI_FLAGS_BULK_AUX_COMPLETE     = 0x020000,  // internal use only
  51    VCHI_FLAGS_BULK_DATA_QUEUED      = 0x040000,  // internal use only
  52    VCHI_FLAGS_BULK_DATA_COMPLETE    = 0x080000,  // internal use only
  53    VCHI_FLAGS_INTERNAL              = 0xFF0000
  54 } VCHI_FLAGS_T;
  55
  56 // constants for vchi_crc_control()
  57 typedef enum {
  58    VCHI_CRC_NOTHING = -1,
  59    VCHI_CRC_PER_SERVICE = 0,
  60    VCHI_CRC_EVERYTHING = 1,
  61 } VCHI_CRC_CONTROL_T;
  62
  63 //callback reasons when an event occurs on a service
  64 typedef enum {
  65    VCHI_CALLBACK_REASON_MIN,
  66
  67    //This indicates that there is data available
  68    //handle is the msg id that was transmitted with the data
  69    //    When a message is received and there was no FULL message available previously, send callback
  70    //    Tasks get kicked by the callback, reset their event and try and read from the fifo until it fails
  71    VCHI_CALLBACK_MSG_AVAILABLE,
  72    VCHI_CALLBACK_MSG_SENT,
  73    VCHI_CALLBACK_MSG_SPACE_AVAILABLE, // XXX not yet implemented
  74
  75    // This indicates that a transfer from the other side has completed
  76    VCHI_CALLBACK_BULK_RECEIVED,
  77    //This indicates that data queued up to be sent has now gone
  78    //handle is the msg id that was used when sending the data
  79    VCHI_CALLBACK_BULK_SENT,
  80    VCHI_CALLBACK_BULK_RX_SPACE_AVAILABLE, // XXX not yet implemented
  81    VCHI_CALLBACK_BULK_TX_SPACE_AVAILABLE, // XXX not yet implemented
  82
  83    VCHI_CALLBACK_SERVICE_CLOSED,
  84
  85    // this side has sent XOFF to peer due to lack of data consumption by service
  86    // (suggests the service may need to take some recovery action if it has
  87    // been deliberately holding off consuming data)
  88    VCHI_CALLBACK_SENT_XOFF,
  89    VCHI_CALLBACK_SENT_XON,
  90
  91    // indicates that a bulk transfer has finished reading the source buffer
  92    VCHI_CALLBACK_BULK_DATA_READ,
  93
  94    // power notification events (currently host side only)
  95    VCHI_CALLBACK_PEER_OFF,
  96    VCHI_CALLBACK_PEER_SUSPENDED,
  97    VCHI_CALLBACK_PEER_ON,
  98    VCHI_CALLBACK_PEER_RESUMED,
  99    VCHI_CALLBACK_FORCED_POWER_OFF,
 100
 101 #ifdef USE_VCHIQ_ARM
 102    // some extra notifications provided by vchiq_arm
 103    VCHI_CALLBACK_SERVICE_OPENED,
 104    VCHI_CALLBACK_BULK_RECEIVE_ABORTED,
 105    VCHI_CALLBACK_BULK_TRANSMIT_ABORTED,
 106 #endif
 107
 108    VCHI_CALLBACK_REASON_MAX
 109 } VCHI_CALLBACK_REASON_T;
 110
 111 // service control options
 112 typedef enum {
 113    VCHI_SERVICE_OPTION_MIN,
 114
 115    VCHI_SERVICE_OPTION_TRACE,
 116    VCHI_SERVICE_OPTION_SYNCHRONOUS,
 117
 118    VCHI_SERVICE_OPTION_MAX
 119 } VCHI_SERVICE_OPTION_T;
 120
 121
 122 //Callback used by all services / bulk transfers
 123 typedef void (*VCHI_CALLBACK_T)(void *callback_param, //my service local param
 124                                  VCHI_CALLBACK_REASON_T reason,
 125                                  void *handle); //for transmitting msg's only
 126
 127
 128
 129 /*
 130  * Define vector struct for scatter-gather (vector) operations
 131  * Vectors can be nested - if a vector element has negative length, then
 132  * the data pointer is treated as pointing to another vector array, with
 133  * '-vec_len' elements. Thus to append a header onto an existing vector,
 134  * you can do this:
 135  *
 136  * void foo(const VCHI_MSG_VECTOR_T *v, int n)
 137  * {
 138  *    VCHI_MSG_VECTOR_T nv[2];
 139  *    nv[0].vec_base = my_header;
 140  *    nv[0].vec_len = sizeof my_header;
 141  *    nv[1].vec_base = v;
 142  *    nv[1].vec_len = -n;
 143  *    ...
 144  *
 145  */
 146 typedef struct vchi_msg_vector {
 147    const void *vec_base;
 148    int32_t vec_len;
 149 } VCHI_MSG_VECTOR_T;
 150
 151 // Opaque type for a connection API
 152 typedef struct opaque_vchi_connection_api_t VCHI_CONNECTION_API_T;
 153
 154 // Opaque type for a message driver
 155 typedef struct opaque_vchi_message_driver_t VCHI_MESSAGE_DRIVER_T;
 156
 157
 158 // Iterator structure for reading ahead through received message queue. Allocated by client,
 159 // initialised by vchi_msg_look_ahead. Fields are for internal VCHI use only.
 160 // Iterates over messages in queue at the instant of the call to vchi_msg_lookahead -
 161 // will not proceed to messages received since. Behaviour is undefined if an iterator
 162 // is used again after messages for that service are removed/dequeued by any
 163 // means other than vchi_msg_iter_... calls on the iterator itself.
 164 typedef struct {
 165    struct opaque_vchi_service_t *service;
 166    void *last;
 167    void *next;
 168    void *remove;
 169 } VCHI_MSG_ITER_T;
 170
 171
 172 #endif // VCHI_COMMON_H_