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