vchiq_if.h revision 278277 
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
50typedef 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
60typedef enum {
61	VCHIQ_ERROR   = -1,
62	VCHIQ_SUCCESS = 0,
63	VCHIQ_RETRY   = 1
64} VCHIQ_STATUS_T;
65
66typedef 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
73typedef 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
80typedef 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
90typedef struct {
91	const void *data;
92	unsigned int size;
93} VCHIQ_ELEMENT_T;
94
95typedef unsigned int VCHIQ_SERVICE_HANDLE_T;
96
97typedef VCHIQ_STATUS_T (*VCHIQ_CALLBACK_T)(VCHIQ_REASON_T, VCHIQ_HEADER_T *,
98	VCHIQ_SERVICE_HANDLE_T, void *);
99
100typedef struct vchiq_service_base_struct {
101	int fourcc;
102	VCHIQ_CALLBACK_T callback;
103	void *userdata;
104} VCHIQ_SERVICE_BASE_T;
105
106typedef 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
114typedef 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
125typedef struct vchiq_instance_struct *VCHIQ_INSTANCE_T;
126typedef void (*VCHIQ_REMOTE_USE_CALLBACK_T)(void *cb_arg);
127
128extern VCHIQ_STATUS_T vchiq_initialise(VCHIQ_INSTANCE_T *pinstance);
129extern VCHIQ_STATUS_T vchiq_shutdown(VCHIQ_INSTANCE_T instance);
130extern VCHIQ_STATUS_T vchiq_connect(VCHIQ_INSTANCE_T instance);
131extern VCHIQ_STATUS_T vchiq_add_service(VCHIQ_INSTANCE_T instance,
132	const VCHIQ_SERVICE_PARAMS_T *params,
133	VCHIQ_SERVICE_HANDLE_T *pservice);
134extern VCHIQ_STATUS_T vchiq_open_service(VCHIQ_INSTANCE_T instance,
135	const VCHIQ_SERVICE_PARAMS_T *params,
136	VCHIQ_SERVICE_HANDLE_T *pservice);
137extern VCHIQ_STATUS_T vchiq_close_service(VCHIQ_SERVICE_HANDLE_T service);
138extern VCHIQ_STATUS_T vchiq_remove_service(VCHIQ_SERVICE_HANDLE_T service);
139extern VCHIQ_STATUS_T vchiq_use_service(VCHIQ_SERVICE_HANDLE_T service);
140extern VCHIQ_STATUS_T vchiq_use_service_no_resume(
141	VCHIQ_SERVICE_HANDLE_T service);
142extern VCHIQ_STATUS_T vchiq_release_service(VCHIQ_SERVICE_HANDLE_T service);
143
144extern VCHIQ_STATUS_T vchiq_queue_message(VCHIQ_SERVICE_HANDLE_T service,
145	const VCHIQ_ELEMENT_T *elements, unsigned int count);
146extern void           vchiq_release_message(VCHIQ_SERVICE_HANDLE_T service,
147	VCHIQ_HEADER_T *header);
148extern VCHIQ_STATUS_T vchiq_queue_bulk_transmit(VCHIQ_SERVICE_HANDLE_T service,
149	void *data, unsigned int size, void *userdata);
150extern VCHIQ_STATUS_T vchiq_queue_bulk_receive(VCHIQ_SERVICE_HANDLE_T service,
151	void *data, unsigned int size, void *userdata);
152extern 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);
155extern 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);
158extern 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);
161extern 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);
164extern 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);
167extern 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);
170extern int   vchiq_get_client_id(VCHIQ_SERVICE_HANDLE_T service);
171extern void *vchiq_get_service_userdata(VCHIQ_SERVICE_HANDLE_T service);
172extern int   vchiq_get_service_fourcc(VCHIQ_SERVICE_HANDLE_T service);
173extern VCHIQ_STATUS_T vchiq_get_config(VCHIQ_INSTANCE_T instance,
174	int config_size, VCHIQ_CONFIG_T *pconfig);
175extern VCHIQ_STATUS_T vchiq_set_service_option(VCHIQ_SERVICE_HANDLE_T service,
176	VCHIQ_SERVICE_OPTION_T option, int value);
177
178extern VCHIQ_STATUS_T vchiq_remote_use(VCHIQ_INSTANCE_T instance,
179	VCHIQ_REMOTE_USE_CALLBACK_T callback, void *cb_arg);
180extern VCHIQ_STATUS_T vchiq_remote_release(VCHIQ_INSTANCE_T instance);
181
182extern VCHIQ_STATUS_T vchiq_dump_phys_mem(VCHIQ_SERVICE_HANDLE_T service,
183	void *ptr, size_t num_bytes);
184
185extern VCHIQ_STATUS_T vchiq_get_peer_version(VCHIQ_SERVICE_HANDLE_T handle,
186      short *peer_version);
187
188#endif /* VCHIQ_IF_H */
189