BluetoothHc.h@ 77662

Last change on this file since 77662 was 77662, checked in by vboxsync, 6 years ago
EFI: First step in UDK2018 merge. Does not build yet.
Property svn:eol-style set to `native`
File size: 20.2 KB

Line
1	/** @file
2	EFI Bluetooth Host Controller Protocol as defined in UEFI 2.5.
3	This protocol abstracts the Bluetooth host controller layer message transmit and receive.
4
5	Copyright (c) 2015 - 2017, Intel Corporation. All rights reserved.<BR>
6	This program and the accompanying materials are licensed and made available under
7	the terms and conditions of the BSD License that accompanies this distribution.
8	The full text of the license may be found at
9	http://opensource.org/licenses/bsd-license.php.
10
11	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13
14	@par Revision Reference:
15	This Protocol is introduced in UEFI Specification 2.5
16
17	**/
18
19	#ifndef __EFI_BLUETOOTH_HC_PROTOCOL_H__
20	#define __EFI_BLUETOOTH_HC_PROTOCOL_H__
21
22	#define EFI_BLUETOOTH_HC_PROTOCOL_GUID \
23	{ \
24	0xb3930571, 0xbeba, 0x4fc5, { 0x92, 0x3, 0x94, 0x27, 0x24, 0x2e, 0x6a, 0x43 } \
25	}
26
27	typedef struct _EFI_BLUETOOTH_HC_PROTOCOL EFI_BLUETOOTH_HC_PROTOCOL;
28
29	/**
30	Send HCI command packet.
31
32	The SendCommand() function sends HCI command packet. Buffer holds the whole HCI
33	command packet, including OpCode, OCF, OGF, parameter length, and parameters. When
34	this function is returned, it just means the HCI command packet is sent, it does not mean
35	the command is success or complete. Caller might need to wait a command status event
36	to know the command status, or wait a command complete event to know if the
37	command is completed.
38
39	@param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
40	@param[in,out] BufferSize On input, indicates the size, in bytes, of the data buffer
41	specified by Buffer. On output, indicates the amount of
42	data actually transferred.
43	@param[in] Buffer A pointer to the buffer of data that will be transmitted to
44	Bluetooth host controller.
45	@param[in] Timeout Indicating the transfer should be completed within this
46	time frame. The units are in milliseconds. If Timeout is 0,
47	then the caller must wait for the function to be completed
48	until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
49
50	@retval EFI_SUCCESS The HCI command packet is sent successfully.
51	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
52	BufferSize is NULL.
53	*BufferSize is 0.
54	Buffer is NULL.
55	@retval EFI_TIMEOUT Sending HCI command packet fail due to timeout.
56	@retval EFI_DEVICE_ERROR Sending HCI command packet fail due to host controller or device
57	error.
58
59	**/
60	typedef
61	EFI_STATUS
62	(EFIAPI *EFI_BLUETOOTH_HC_SEND_COMMAND)(
63	IN EFI_BLUETOOTH_HC_PROTOCOL *This,
64	IN OUT UINTN *BufferSize,
65	IN VOID *Buffer,
66	IN UINTN Timeout
67	);
68
69	/**
70	Receive HCI event packet.
71
72	The ReceiveEvent() function receives HCI event packet. Buffer holds the whole HCI event
73	packet, including EventCode, parameter length, and parameters.
74
75	@param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
76	@param[in,out] BufferSize On input, indicates the size, in bytes, of the data buffer
77	specified by Buffer. On output, indicates the amount of
78	data actually transferred.
79	@param[out] Buffer A pointer to the buffer of data that will be received from
80	Bluetooth host controller.
81	@param[in] Timeout Indicating the transfer should be completed within this
82	time frame. The units are in milliseconds. If Timeout is 0,
83	then the caller must wait for the function to be completed
84	until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
85
86	@retval EFI_SUCCESS The HCI event packet is received successfully.
87	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
88	BufferSize is NULL.
89	*BufferSize is 0.
90	Buffer is NULL.
91	@retval EFI_TIMEOUT Receiving HCI event packet fail due to timeout.
92	@retval EFI_DEVICE_ERROR Receiving HCI event packet fail due to host controller or device
93	error.
94
95	**/
96	typedef
97	EFI_STATUS
98	(EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_EVENT)(
99	IN EFI_BLUETOOTH_HC_PROTOCOL *This,
100	IN OUT UINTN *BufferSize,
101	OUT VOID *Buffer,
102	IN UINTN Timeout
103	);
104
105	/**
106	The async callback of AsyncReceiveEvent().
107
108	@param[in] Data Data received via asynchronous transfer.
109	@param[in] DataLength The length of Data in bytes, received via asynchronous
110	transfer.
111	@param[in] Context Context passed from asynchronous transfer request.
112
113	@retval EFI_SUCCESS The callback does execute successfully.
114	@retval Others The callback doesn't execute successfully.
115
116	**/
117	typedef
118	EFI_STATUS
119	(EFIAPI *EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK) (
120	IN VOID *Data,
121	IN UINTN DataLength,
122	IN VOID *Context
123	);
124
125	/**
126	Receive HCI event packet in non-blocking way.
127
128	The AsyncReceiveEvent() function receives HCI event packet in non-blocking way. Data
129	in Callback function holds the whole HCI event packet, including EventCode, parameter
130	length, and parameters.
131
132	@param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
133	@param[in] IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the
134	request is deleted.
135	@param[in] PollingInterval Indicates the periodic rate, in milliseconds, that the
136	transfer is to be executed.
137	@param[in] DataLength Specifies the length, in bytes, of the data to be received.
138	@param[in] Callback The callback function. This function is called if the
139	asynchronous transfer is completed.
140	@param[in] Context Data passed into Callback function. This is optional
141	parameter and may be NULL.
142
143	@retval EFI_SUCCESS The HCI asynchronous receive request is submitted successfully.
144	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
145	DataLength is 0.
146	If IsNewTransfer is TRUE, and an asynchronous receive
147	request already exists.
148	**/
149	typedef
150	EFI_STATUS
151	(EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT) (
152	IN EFI_BLUETOOTH_HC_PROTOCOL *This,
153	IN BOOLEAN IsNewTransfer,
154	IN UINTN PollingInterval,
155	IN UINTN DataLength,
156	IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,
157	IN VOID *Context
158	);
159
160	/**
161	Send HCI ACL data packet.
162
163	The SendACLData() function sends HCI ACL data packet. Buffer holds the whole HCI ACL
164	data packet, including Handle, PB flag, BC flag, data length, and data.
165
166	The SendACLData() function and ReceiveACLData() function just send and receive data
167	payload from application layer. In order to protect the payload data, the Bluetooth bus is
168	required to call HCI_Set_Connection_Encryption command to enable hardware based
169	encryption after authentication completed, according to pairing mode and host
170	capability.
171
172	@param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
173	@param[in, out] BufferSize On input, indicates the size, in bytes, of the data buffer
174	specified by Buffer. On output, indicates the amount of
175	data actually transferred.
176	@param[in] Buffer A pointer to the buffer of data that will be transmitted to
177	Bluetooth host controller.
178	@param[in] Timeout Indicating the transfer should be completed within this
179	time frame. The units are in milliseconds. If Timeout is 0,
180	then the caller must wait for the function to be completed
181	until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
182
183	@retval EFI_SUCCESS The HCI ACL data packet is sent successfully.
184	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
185	BufferSize is NULL.
186	*BufferSize is 0.
187	Buffer is NULL.
188	@retval EFI_TIMEOUT Sending HCI ACL data packet fail due to timeout.
189	@retval EFI_DEVICE_ERROR Sending HCI ACL data packet fail due to host controller or device
190	error.
191
192	**/
193	typedef
194	EFI_STATUS
195	(EFIAPI *EFI_BLUETOOTH_HC_SEND_ACL_DATA)(
196	IN EFI_BLUETOOTH_HC_PROTOCOL *This,
197	IN OUT UINTN *BufferSize,
198	IN VOID *Buffer,
199	IN UINTN Timeout
200	);
201
202	/**
203	Receive HCI ACL data packet.
204
205	The ReceiveACLData() function receives HCI ACL data packet. Buffer holds the whole HCI
206	ACL data packet, including Handle, PB flag, BC flag, data length, and data.
207
208	@param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
209	@param[in, out] BufferSize On input, indicates the size, in bytes, of the data buffer
210	specified by Buffer. On output, indicates the amount of
211	data actually transferred.
212	@param[out] Buffer A pointer to the buffer of data that will be received from
213	Bluetooth host controller.
214	@param[in] Timeout Indicating the transfer should be completed within this
215	time frame. The units are in milliseconds. If Timeout is 0,
216	then the caller must wait for the function to be completed
217	until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
218
219	@retval EFI_SUCCESS The HCI ACL data packet is received successfully.
220	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
221	BufferSize is NULL.
222	*BufferSize is 0.
223	Buffer is NULL.
224	@retval EFI_TIMEOUT Receiving HCI ACL data packet fail due to timeout.
225	@retval EFI_DEVICE_ERROR Receiving HCI ACL data packet fail due to host controller or device
226	error.
227
228	**/
229	typedef
230	EFI_STATUS
231	(EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA)(
232	IN EFI_BLUETOOTH_HC_PROTOCOL *This,
233	IN OUT UINTN *BufferSize,
234	OUT VOID *Buffer,
235	IN UINTN Timeout
236	);
237
238	/**
239	Receive HCI ACL data packet in non-blocking way.
240
241	The AsyncReceiveACLData() function receives HCI ACL data packet in non-blocking way.
242	Data in Callback holds the whole HCI ACL data packet, including Handle, PB flag, BC flag,
243	data length, and data.
244
245	@param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
246	@param[in] IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the
247	request is deleted.
248	@param[in] PollingInterval Indicates the periodic rate, in milliseconds, that the
249	transfer is to be executed.
250	@param[in] DataLength Specifies the length, in bytes, of the data to be received.
251	@param[in] Callback The callback function. This function is called if the
252	asynchronous transfer is completed.
253	@param[in] Context Data passed into Callback function. This is optional
254	parameter and may be NULL.
255
256	@retval EFI_SUCCESS The HCI asynchronous receive request is submitted successfully.
257	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
258	DataLength is 0.
259	If IsNewTransfer is TRUE, and an asynchronous receive
260	request already exists.
261	**/
262	typedef
263	EFI_STATUS
264	(EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA) (
265	IN EFI_BLUETOOTH_HC_PROTOCOL *This,
266	IN BOOLEAN IsNewTransfer,
267	IN UINTN PollingInterval,
268	IN UINTN DataLength,
269	IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,
270	IN VOID *Context
271	);
272
273	/**
274	Send HCI SCO data packet.
275
276	The SendSCOData() function sends HCI SCO data packet. Buffer holds the whole HCI SCO
277	data packet, including ConnectionHandle, PacketStatus flag, data length, and data.
278
279	@param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
280	@param[in,out] BufferSize On input, indicates the size, in bytes, of the data buffer
281	specified by Buffer. On output, indicates the amount of
282	data actually transferred.
283	@param[in] Buffer A pointer to the buffer of data that will be transmitted to
284	Bluetooth host controller.
285	@param[in] Timeout Indicating the transfer should be completed within this
286	time frame. The units are in milliseconds. If Timeout is 0,
287	then the caller must wait for the function to be completed
288	until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
289
290	@retval EFI_SUCCESS The HCI SCO data packet is sent successfully.
291	@retval EFI_UNSUPPORTED The implementation does not support HCI SCO transfer.
292	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
293	BufferSize is NULL.
294	*BufferSize is 0.
295	Buffer is NULL.
296	@retval EFI_TIMEOUT Sending HCI SCO data packet fail due to timeout.
297	@retval EFI_DEVICE_ERROR Sending HCI SCO data packet fail due to host controller or device
298	error.
299	**/
300	typedef
301	EFI_STATUS
302	(EFIAPI *EFI_BLUETOOTH_HC_SEND_SCO_DATA)(
303	IN EFI_BLUETOOTH_HC_PROTOCOL *This,
304	IN OUT UINTN *BufferSize,
305	IN VOID *Buffer,
306	IN UINTN Timeout
307	);
308
309	/**
310	Receive HCI SCO data packet.
311
312	The ReceiveSCOData() function receives HCI SCO data packet. Buffer holds the whole HCI
313	SCO data packet, including ConnectionHandle, PacketStatus flag, data length, and data.
314
315	@param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
316	@param[in,out] BufferSize On input, indicates the size, in bytes, of the data buffer
317	specified by Buffer. On output, indicates the amount of
318	data actually transferred.
319	@param[out] Buffer A pointer to the buffer of data that will be received from
320	Bluetooth host controller.
321	@param[in] Timeout Indicating the transfer should be completed within this
322	time frame. The units are in milliseconds. If Timeout is 0,
323	then the caller must wait for the function to be completed
324	until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
325
326	@retval EFI_SUCCESS The HCI SCO data packet is received successfully.
327	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
328	BufferSize is NULL.
329	*BufferSize is 0.
330	Buffer is NULL.
331	@retval EFI_TIMEOUT Receiving HCI SCO data packet fail due to timeout.
332	@retval EFI_DEVICE_ERROR Receiving HCI SCO data packet fail due to host controller or device
333	error.
334	**/
335	typedef
336	EFI_STATUS
337	(EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA)(
338	IN EFI_BLUETOOTH_HC_PROTOCOL *This,
339	IN OUT UINTN *BufferSize,
340	OUT VOID *Buffer,
341	IN UINTN Timeout
342	);
343
344	/**
345	Receive HCI SCO data packet in non-blocking way.
346
347	The AsyncReceiveSCOData() function receives HCI SCO data packet in non-blocking way.
348	Data in Callback holds the whole HCI SCO data packet, including ConnectionHandle,
349	PacketStatus flag, data length, and data.
350
351	@param[in] This Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
352	@param[in] IsNewTransfer If TRUE, a new transfer will be submitted. If FALSE, the
353	request is deleted.
354	@param[in] PollingInterval Indicates the periodic rate, in milliseconds, that the
355	transfer is to be executed.
356	@param[in] DataLength Specifies the length, in bytes, of the data to be received.
357	@param[in] Callback The callback function. This function is called if the
358	asynchronous transfer is completed.
359	@param[in] Context Data passed into Callback function. This is optional
360	parameter and may be NULL.
361
362	@retval EFI_SUCCESS The HCI asynchronous receive request is submitted successfully.
363	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
364	DataLength is 0.
365	If IsNewTransfer is TRUE, and an asynchronous receive
366	request already exists.
367	**/
368	typedef
369	EFI_STATUS
370	(EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA) (
371	IN EFI_BLUETOOTH_HC_PROTOCOL *This,
372	IN BOOLEAN IsNewTransfer,
373	IN UINTN PollingInterval,
374	IN UINTN DataLength,
375	IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,
376	IN VOID *Context
377	);
378
379	//
380	// The EFI_BLUETOOTH_HC_PROTOCOL is used to transmit or receive HCI layer data packets.
381	//
382	struct _EFI_BLUETOOTH_HC_PROTOCOL {
383	//
384	// Send HCI command packet.
385	//
386	EFI_BLUETOOTH_HC_SEND_COMMAND SendCommand;
387	//
388	// Receive HCI event packets.
389	//
390	EFI_BLUETOOTH_HC_RECEIVE_EVENT ReceiveEvent;
391	//
392	// Non-blocking receive HCI event packets.
393	//
394	EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT AsyncReceiveEvent;
395	//
396	// Send HCI ACL (asynchronous connection-oriented) data packets.
397	//
398	EFI_BLUETOOTH_HC_SEND_ACL_DATA SendACLData;
399	//
400	// Receive HCI ACL data packets.
401	//
402	EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA ReceiveACLData;
403	//
404	// Non-blocking receive HCI ACL data packets.
405	//
406	EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA AsyncReceiveACLData;
407	//
408	// Send HCI synchronous (SCO and eSCO) data packets.
409	//
410	EFI_BLUETOOTH_HC_SEND_SCO_DATA SendSCOData;
411	//
412	// Receive HCI synchronous data packets.
413	//
414	EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA ReceiveSCOData;
415	//
416	// Non-blocking receive HCI synchronous data packets.
417	//
418	EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA AsyncReceiveSCOData;
419	};
420
421	extern EFI_GUID gEfiBluetoothHcProtocolGuid;
422
423	#endif
424

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Devices/EFI/FirmwareNew/MdePkg/Include/Protocol/BluetoothHc.h@ 77662

Download in other formats: