2 * Copyright (c) 2010-2012 Broadcom. All rights reserved.
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
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.
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.
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.
34 #ifndef VCHI_COMMON_H_
35 #define VCHI_COMMON_H_
38 //flags used when sending messages (must be bitmapped)
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,
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
56 // constants for vchi_crc_control()
58 VCHI_CRC_NOTHING = -1,
59 VCHI_CRC_PER_SERVICE = 0,
60 VCHI_CRC_EVERYTHING = 1,
63 //callback reasons when an event occurs on a service
65 VCHI_CALLBACK_REASON_MIN,
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
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
83 VCHI_CALLBACK_SERVICE_CLOSED,
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,
91 // indicates that a bulk transfer has finished reading the source buffer
92 VCHI_CALLBACK_BULK_DATA_READ,
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,
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,
108 VCHI_CALLBACK_REASON_MAX
109 } VCHI_CALLBACK_REASON_T;
111 // service control options
113 VCHI_SERVICE_OPTION_MIN,
115 VCHI_SERVICE_OPTION_TRACE,
116 VCHI_SERVICE_OPTION_SYNCHRONOUS,
118 VCHI_SERVICE_OPTION_MAX
119 } VCHI_SERVICE_OPTION_T;
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
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,
136 * void foo(const VCHI_MSG_VECTOR_T *v, int n)
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;
146 typedef struct vchi_msg_vector {
147 const void *vec_base;
151 // Opaque type for a connection API
152 typedef struct opaque_vchi_connection_api_t VCHI_CONNECTION_API_T;
154 // Opaque type for a message driver
155 typedef struct opaque_vchi_message_driver_t VCHI_MESSAGE_DRIVER_T;
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.
165 struct opaque_vchi_service_t *service;
172 #endif // VCHI_COMMON_H_