[mirror_edk2.git] / MdeModulePkg / Bus / Usb / UsbBusDxe / UsbUtility.h

/** @file\r
\r
    Manage Usb Port/Hc/Etc.\r
\r
Copyright (c) 2007, Intel Corporation. All rights reserved.<BR>\r
This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
which accompanies this distribution.  The full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
#ifndef _EFI_USB_UTILITY_H_\r
#define _EFI_USB_UTILITY_H_\r
\r
/**\r
  Get the capability of the host controller.\r
\r
  @param  UsbBus           The usb driver.\r
  @param  MaxSpeed         The maximum speed this host controller supports.\r
  @param  NumOfPort        The number of the root hub port.\r
  @param  Is64BitCapable   Whether this controller support 64 bit addressing.\r
\r
  @retval EFI_SUCCESS      The host controller capability is returned.\r
  @retval Others           Failed to retrieve the host controller capability.\r
\r
**/\r
EFI_STATUS\r
UsbHcGetCapability (\r
  IN  USB_BUS             *UsbBus,\r
  OUT UINT8               *MaxSpeed,\r
  OUT UINT8               *NumOfPort,\r
  OUT UINT8               *Is64BitCapable\r
  );\r
\r
\r
/**\r
  Get the root hub port state.\r
\r
  @param  UsbBus           The USB bus driver.\r
  @param  PortIndex        The index of port.\r
  @param  PortStatus       The variable to save port state.\r
\r
  @retval EFI_SUCCESS      The root port state is returned in.\r
  @retval Others           Failed to get the root hub port state.\r
\r
**/\r
EFI_STATUS\r
UsbHcGetRootHubPortStatus (\r
  IN  USB_BUS             *UsbBus,\r
  IN  UINT8               PortIndex,\r
  OUT EFI_USB_PORT_STATUS *PortStatus\r
  );\r
\r
/**\r
  Set the root hub port feature.\r
\r
  @param  UsbBus           The USB bus driver.\r
  @param  PortIndex        The port index.\r
  @param  Feature          The port feature to set.\r
\r
  @retval EFI_SUCCESS      The port feature is set.\r
  @retval Others           Failed to set port feature.\r
\r
**/\r
EFI_STATUS\r
UsbHcSetRootHubPortFeature (\r
  IN USB_BUS              *UsbBus,\r
  IN UINT8                PortIndex,\r
  IN EFI_USB_PORT_FEATURE Feature\r
  );\r
\r
/**\r
  Clear the root hub port feature.\r
\r
  @param  UsbBus           The USB bus driver.\r
  @param  PortIndex        The port index.\r
  @param  Feature          The port feature to clear.\r
\r
  @retval EFI_SUCCESS      The port feature is clear.\r
  @retval Others           Failed to clear port feature.\r
\r
**/\r
EFI_STATUS\r
UsbHcClearRootHubPortFeature (\r
  IN USB_BUS              *UsbBus,\r
  IN UINT8                PortIndex,\r
  IN EFI_USB_PORT_FEATURE Feature\r
  );\r
\r
/**\r
  Execute a control transfer to the device.\r
\r
  @param  UsbBus           The USB bus driver.\r
  @param  DevAddr          The device address.\r
  @param  DevSpeed         The device speed.\r
  @param  MaxPacket        Maximum packet size of endpoint 0.\r
  @param  Request          The control transfer request.\r
  @param  Direction        The direction of data stage.\r
  @param  Data             The buffer holding data.\r
  @param  DataLength       The length of the data.\r
  @param  TimeOut          Timeout (in ms) to wait until timeout.\r
  @param  Translator       The transaction translator for low/full speed device.\r
  @param  UsbResult        The result of transfer.\r
\r
  @retval EFI_SUCCESS      The control transfer finished without error.\r
  @retval Others           The control transfer failed, reason returned in UsbReslt.\r
\r
**/\r
EFI_STATUS\r
UsbHcControlTransfer (\r
  IN  USB_BUS                             *UsbBus,\r
  IN  UINT8                               DevAddr,\r
  IN  UINT8                               DevSpeed,\r
  IN  UINTN                               MaxPacket,\r
  IN  EFI_USB_DEVICE_REQUEST              *Request,\r
  IN  EFI_USB_DATA_DIRECTION              Direction,\r
  IN  OUT VOID                            *Data,\r
  IN  OUT UINTN                           *DataLength,\r
  IN  UINTN                               TimeOut,\r
  IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,\r
  OUT UINT32                              *UsbResult\r
  );\r
\r
/**\r
  Execute a bulk transfer to the device's endpoint.\r
\r
  @param  UsbBus           The USB bus driver.\r
  @param  DevAddr          The target device address.\r
  @param  EpAddr           The target endpoint address, with direction encoded in\r
                           bit 7.\r
  @param  DevSpeed         The device's speed.\r
  @param  MaxPacket        The endpoint's max packet size.\r
  @param  BufferNum        The number of data buffer.\r
  @param  Data             Array of pointers to data buffer.\r
  @param  DataLength       The length of data buffer.\r
  @param  DataToggle       On input, the initial data toggle to use, also  return\r
                           the next toggle on output.\r
  @param  TimeOut          The time to wait until timeout.\r
  @param  Translator       The transaction translator for low/full speed device.\r
  @param  UsbResult        The result of USB execution.\r
\r
  @retval EFI_SUCCESS      The bulk transfer is finished without error.\r
  @retval Others           Failed to execute bulk transfer, result in UsbResult.\r
\r
**/\r
EFI_STATUS\r
UsbHcBulkTransfer (\r
  IN  USB_BUS                             *UsbBus,\r
  IN  UINT8                               DevAddr,\r
  IN  UINT8                               EpAddr,\r
  IN  UINT8                               DevSpeed,\r
  IN  UINTN                               MaxPacket,\r
  IN  UINT8                               BufferNum,\r
  IN  OUT VOID                            *Data[EFI_USB_MAX_BULK_BUFFER_NUM],\r
  IN  OUT UINTN                           *DataLength,\r
  IN  OUT UINT8                           *DataToggle,\r
  IN  UINTN                               TimeOut,\r
  IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,\r
  OUT UINT32                              *UsbResult\r
  );\r
\r
/**\r
  Queue or cancel an asynchronous interrupt transfer.\r
\r
  @param  UsbBus           The USB bus driver.\r
  @param  DevAddr          The target device address.\r
  @param  EpAddr           The target endpoint address, with direction encoded in\r
                           bit 7.\r
  @param  DevSpeed         The device's speed.\r
  @param  MaxPacket        The endpoint's max packet size.\r
  @param  IsNewTransfer    Whether this is a new request. If not, cancel the old\r
                           request.\r
  @param  DataToggle       Data toggle to use on input, next toggle on output.\r
  @param  PollingInterval  The interval to poll the interrupt transfer (in ms).\r
  @param  DataLength       The length of periodical data receive.\r
  @param  Translator       The transaction translator for low/full speed device.\r
  @param  Callback         Function to call when data is received.\r
  @param  Context          The context to the callback.\r
\r
  @retval EFI_SUCCESS      The asynchronous transfer is queued.\r
  @retval Others           Failed to queue the transfer.\r
\r
**/\r
EFI_STATUS\r
UsbHcAsyncInterruptTransfer (\r
  IN  USB_BUS                             *UsbBus,\r
  IN  UINT8                               DevAddr,\r
  IN  UINT8                               EpAddr,\r
  IN  UINT8                               DevSpeed,\r
  IN  UINTN                               MaxPacket,\r
  IN  BOOLEAN                             IsNewTransfer,\r
  IN OUT UINT8                            *DataToggle,\r
  IN  UINTN                               PollingInterval,\r
  IN  UINTN                               DataLength,\r
  IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,\r
  IN  EFI_ASYNC_USB_TRANSFER_CALLBACK     Callback,\r
  IN  VOID                                *Context OPTIONAL\r
  );\r
\r
/**\r
  Execute a synchronous interrupt transfer to the target endpoint.\r
\r
  @param  UsbBus           The USB bus driver.\r
  @param  DevAddr          The target device address.\r
  @param  EpAddr           The target endpoint address, with direction encoded in\r
                           bit 7.\r
  @param  DevSpeed         The device's speed.\r
  @param  MaxPacket        The endpoint's max packet size.\r
  @param  Data             Pointer to data buffer.\r
  @param  DataLength       The length of data buffer.\r
  @param  DataToggle       On input, the initial data toggle to use, also  return\r
                           the next toggle on output.\r
  @param  TimeOut          The time to wait until timeout.\r
  @param  Translator       The transaction translator for low/full speed device.\r
  @param  UsbResult        The result of USB execution.\r
\r
  @retval EFI_SUCCESS      The synchronous interrupt transfer is OK.\r
  @retval Others           Failed to execute the synchronous interrupt transfer.\r
\r
**/\r
EFI_STATUS\r
UsbHcSyncInterruptTransfer (\r
  IN  USB_BUS                             *UsbBus,\r
  IN  UINT8                               DevAddr,\r
  IN  UINT8                               EpAddr,\r
  IN  UINT8                               DevSpeed,\r
  IN  UINTN                               MaxPacket,\r
  IN OUT VOID                             *Data,\r
  IN OUT UINTN                            *DataLength,\r
  IN OUT UINT8                            *DataToggle,\r
  IN  UINTN                               TimeOut,\r
  IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,\r
  OUT UINT32                              *UsbResult\r
  );\r
\r
\r
/**\r
  Open the USB host controller protocol BY_CHILD.\r
\r
  @param  Bus              The USB bus driver.\r
  @param  Child            The child handle.\r
\r
  @return The open protocol return.\r
\r
**/\r
EFI_STATUS\r
UsbOpenHostProtoByChild (\r
  IN USB_BUS              *Bus,\r
  IN EFI_HANDLE           Child\r
  );\r
\r
/**\r
  Close the USB host controller protocol BY_CHILD.\r
\r
  @param  Bus              The USB bus driver.\r
  @param  Child            The child handle.\r
\r
  @return None.\r
\r
**/\r
VOID\r
UsbCloseHostProtoByChild (\r
  IN USB_BUS              *Bus,\r
  IN EFI_HANDLE           Child\r
  );\r
\r
/**\r
  return the current TPL, copied from the EDKII glue lib.\r
\r
  @param  VOID.\r
\r
  @return Current TPL.\r
\r
**/\r
EFI_TPL\r
UsbGetCurrentTpl (\r
  VOID\r
  );\r
\r
#endif\r
Commit	Line	Data
e237e7ae	1	/** @file\r
e237e7ae	2	\r
8616fc4c	3	Manage Usb Port/Hc/Etc.\r
8616fc4c	4	\r
cd5ebaa0 HT	5	Copyright (c) 2007, Intel Corporation. All rights reserved.<BR>\r
cd5ebaa0 HT	6	This program and the accompanying materials\r
e237e7ae	7	are licensed and made available under the terms and conditions of the BSD License\r
	8	which accompanies this distribution. The full text of the license may be found at\r
	9	http://opensource.org/licenses/bsd-license.php\r
	10	\r
	11	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
	12	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
	13	\r
8616fc4c	14	**/\r
e237e7ae	15	\r
8616fc4c	16	#ifndef _EFI_USB_UTILITY_H_\r
8616fc4c	17	#define _EFI_USB_UTILITY_H_\r
e237e7ae	18	\r
8616fc4c	19	/**\r
8616fc4c	20	Get the capability of the host controller.\r
e237e7ae	21	\r
8616fc4c	22	@param UsbBus The usb driver.\r
	23	@param MaxSpeed The maximum speed this host controller supports.\r
	24	@param NumOfPort The number of the root hub port.\r
	25	@param Is64BitCapable Whether this controller support 64 bit addressing.\r
e237e7ae	26	\r
8616fc4c	27	@retval EFI_SUCCESS The host controller capability is returned.\r
8616fc4c	28	@retval Others Failed to retrieve the host controller capability.\r
e237e7ae	29	\r
e237e7ae	30	**/\r
e237e7ae	31	EFI_STATUS\r
	32	UsbHcGetCapability (\r
	33	IN USB_BUS *UsbBus,\r
	34	OUT UINT8 *MaxSpeed,\r
	35	OUT UINT8 *NumOfPort,\r
	36	OUT UINT8 *Is64BitCapable\r
	37	);\r
	38	\r
e237e7ae	39	\r
8616fc4c	40	/**\r
	41	Get the root hub port state.\r
	42	\r
	43	@param UsbBus The USB bus driver.\r
	44	@param PortIndex The index of port.\r
	45	@param PortStatus The variable to save port state.\r
e237e7ae	46	\r
8616fc4c	47	@retval EFI_SUCCESS The root port state is returned in.\r
	48	@retval Others Failed to get the root hub port state.\r
	49	\r
	50	**/\r
e237e7ae	51	EFI_STATUS\r
	52	UsbHcGetRootHubPortStatus (\r
	53	IN USB_BUS *UsbBus,\r
	54	IN UINT8 PortIndex,\r
	55	OUT EFI_USB_PORT_STATUS *PortStatus\r
	56	);\r
	57	\r
8616fc4c	58	/**\r
8616fc4c	59	Set the root hub port feature.\r
e237e7ae	60	\r
8616fc4c	61	@param UsbBus The USB bus driver.\r
	62	@param PortIndex The port index.\r
	63	@param Feature The port feature to set.\r
	64	\r
	65	@retval EFI_SUCCESS The port feature is set.\r
	66	@retval Others Failed to set port feature.\r
	67	\r
	68	**/\r
e237e7ae	69	EFI_STATUS\r
	70	UsbHcSetRootHubPortFeature (\r
	71	IN USB_BUS *UsbBus,\r
	72	IN UINT8 PortIndex,\r
	73	IN EFI_USB_PORT_FEATURE Feature\r
	74	);\r
	75	\r
8616fc4c	76	/**\r
8616fc4c	77	Clear the root hub port feature.\r
e237e7ae	78	\r
8616fc4c	79	@param UsbBus The USB bus driver.\r
	80	@param PortIndex The port index.\r
	81	@param Feature The port feature to clear.\r
	82	\r
	83	@retval EFI_SUCCESS The port feature is clear.\r
	84	@retval Others Failed to clear port feature.\r
	85	\r
	86	**/\r
e237e7ae	87	EFI_STATUS\r
	88	UsbHcClearRootHubPortFeature (\r
	89	IN USB_BUS *UsbBus,\r
	90	IN UINT8 PortIndex,\r
	91	IN EFI_USB_PORT_FEATURE Feature\r
	92	);\r
	93	\r
8616fc4c	94	/**\r
8616fc4c	95	Execute a control transfer to the device.\r
e237e7ae	96	\r
8616fc4c	97	@param UsbBus The USB bus driver.\r
	98	@param DevAddr The device address.\r
	99	@param DevSpeed The device speed.\r
	100	@param MaxPacket Maximum packet size of endpoint 0.\r
	101	@param Request The control transfer request.\r
	102	@param Direction The direction of data stage.\r
	103	@param Data The buffer holding data.\r
	104	@param DataLength The length of the data.\r
	105	@param TimeOut Timeout (in ms) to wait until timeout.\r
	106	@param Translator The transaction translator for low/full speed device.\r
	107	@param UsbResult The result of transfer.\r
	108	\r
	109	@retval EFI_SUCCESS The control transfer finished without error.\r
	110	@retval Others The control transfer failed, reason returned in UsbReslt.\r
	111	\r
	112	**/\r
e237e7ae	113	EFI_STATUS\r
	114	UsbHcControlTransfer (\r
	115	IN USB_BUS *UsbBus,\r
	116	IN UINT8 DevAddr,\r
	117	IN UINT8 DevSpeed,\r
	118	IN UINTN MaxPacket,\r
	119	IN EFI_USB_DEVICE_REQUEST *Request,\r
	120	IN EFI_USB_DATA_DIRECTION Direction,\r
	121	IN OUT VOID *Data,\r
	122	IN OUT UINTN *DataLength,\r
	123	IN UINTN TimeOut,\r
	124	IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,\r
	125	OUT UINT32 *UsbResult\r
	126	);\r
	127	\r
8616fc4c	128	/**\r
	129	Execute a bulk transfer to the device's endpoint.\r
	130	\r
	131	@param UsbBus The USB bus driver.\r
	132	@param DevAddr The target device address.\r
	133	@param EpAddr The target endpoint address, with direction encoded in\r
	134	bit 7.\r
	135	@param DevSpeed The device's speed.\r
	136	@param MaxPacket The endpoint's max packet size.\r
	137	@param BufferNum The number of data buffer.\r
	138	@param Data Array of pointers to data buffer.\r
	139	@param DataLength The length of data buffer.\r
	140	@param DataToggle On input, the initial data toggle to use, also return\r
	141	the next toggle on output.\r
	142	@param TimeOut The time to wait until timeout.\r
	143	@param Translator The transaction translator for low/full speed device.\r
	144	@param UsbResult The result of USB execution.\r
	145	\r
	146	@retval EFI_SUCCESS The bulk transfer is finished without error.\r
	147	@retval Others Failed to execute bulk transfer, result in UsbResult.\r
e237e7ae	148	\r
8616fc4c	149	**/\r
e237e7ae	150	EFI_STATUS\r
	151	UsbHcBulkTransfer (\r
	152	IN USB_BUS *UsbBus,\r
	153	IN UINT8 DevAddr,\r
	154	IN UINT8 EpAddr,\r
	155	IN UINT8 DevSpeed,\r
	156	IN UINTN MaxPacket,\r
	157	IN UINT8 BufferNum,\r
	158	IN OUT VOID *Data[EFI_USB_MAX_BULK_BUFFER_NUM],\r
	159	IN OUT UINTN *DataLength,\r
	160	IN OUT UINT8 *DataToggle,\r
	161	IN UINTN TimeOut,\r
	162	IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,\r
	163	OUT UINT32 *UsbResult\r
	164	);\r
	165	\r
8616fc4c	166	/**\r
	167	Queue or cancel an asynchronous interrupt transfer.\r
	168	\r
	169	@param UsbBus The USB bus driver.\r
	170	@param DevAddr The target device address.\r
	171	@param EpAddr The target endpoint address, with direction encoded in\r
	172	bit 7.\r
	173	@param DevSpeed The device's speed.\r
	174	@param MaxPacket The endpoint's max packet size.\r
	175	@param IsNewTransfer Whether this is a new request. If not, cancel the old\r
	176	request.\r
	177	@param DataToggle Data toggle to use on input, next toggle on output.\r
	178	@param PollingInterval The interval to poll the interrupt transfer (in ms).\r
	179	@param DataLength The length of periodical data receive.\r
	180	@param Translator The transaction translator for low/full speed device.\r
	181	@param Callback Function to call when data is received.\r
	182	@param Context The context to the callback.\r
	183	\r
	184	@retval EFI_SUCCESS The asynchronous transfer is queued.\r
	185	@retval Others Failed to queue the transfer.\r
e237e7ae	186	\r
8616fc4c	187	**/\r
e237e7ae	188	EFI_STATUS\r
	189	UsbHcAsyncInterruptTransfer (\r
	190	IN USB_BUS *UsbBus,\r
	191	IN UINT8 DevAddr,\r
	192	IN UINT8 EpAddr,\r
	193	IN UINT8 DevSpeed,\r
	194	IN UINTN MaxPacket,\r
	195	IN BOOLEAN IsNewTransfer,\r
	196	IN OUT UINT8 *DataToggle,\r
	197	IN UINTN PollingInterval,\r
	198	IN UINTN DataLength,\r
	199	IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,\r
	200	IN EFI_ASYNC_USB_TRANSFER_CALLBACK Callback,\r
	201	IN VOID *Context OPTIONAL\r
	202	);\r
	203	\r
8616fc4c	204	/**\r
	205	Execute a synchronous interrupt transfer to the target endpoint.\r
	206	\r
	207	@param UsbBus The USB bus driver.\r
	208	@param DevAddr The target device address.\r
	209	@param EpAddr The target endpoint address, with direction encoded in\r
	210	bit 7.\r
	211	@param DevSpeed The device's speed.\r
	212	@param MaxPacket The endpoint's max packet size.\r
	213	@param Data Pointer to data buffer.\r
	214	@param DataLength The length of data buffer.\r
	215	@param DataToggle On input, the initial data toggle to use, also return\r
	216	the next toggle on output.\r
	217	@param TimeOut The time to wait until timeout.\r
	218	@param Translator The transaction translator for low/full speed device.\r
	219	@param UsbResult The result of USB execution.\r
	220	\r
	221	@retval EFI_SUCCESS The synchronous interrupt transfer is OK.\r
	222	@retval Others Failed to execute the synchronous interrupt transfer.\r
e237e7ae	223	\r
8616fc4c	224	**/\r
e237e7ae	225	EFI_STATUS\r
	226	UsbHcSyncInterruptTransfer (\r
	227	IN USB_BUS *UsbBus,\r
	228	IN UINT8 DevAddr,\r
	229	IN UINT8 EpAddr,\r
	230	IN UINT8 DevSpeed,\r
	231	IN UINTN MaxPacket,\r
	232	IN OUT VOID *Data,\r
	233	IN OUT UINTN *DataLength,\r
	234	IN OUT UINT8 *DataToggle,\r
	235	IN UINTN TimeOut,\r
	236	IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,\r
	237	OUT UINT32 *UsbResult\r
	238	);\r
	239	\r
e237e7ae	240	\r
8616fc4c	241	/**\r
	242	Open the USB host controller protocol BY_CHILD.\r
	243	\r
	244	@param Bus The USB bus driver.\r
	245	@param Child The child handle.\r
e237e7ae	246	\r
8616fc4c	247	@return The open protocol return.\r
	248	\r
	249	**/\r
e237e7ae	250	EFI_STATUS\r
	251	UsbOpenHostProtoByChild (\r
	252	IN USB_BUS *Bus,\r
	253	IN EFI_HANDLE Child\r
	254	);\r
	255	\r
8616fc4c	256	/**\r
	257	Close the USB host controller protocol BY_CHILD.\r
	258	\r
	259	@param Bus The USB bus driver.\r
	260	@param Child The child handle.\r
e237e7ae	261	\r
8616fc4c	262	@return None.\r
	263	\r
	264	**/\r
e237e7ae	265	VOID\r
	266	UsbCloseHostProtoByChild (\r
	267	IN USB_BUS *Bus,\r
	268	IN EFI_HANDLE Child\r
	269	);\r
	270	\r
8616fc4c	271	/**\r
	272	return the current TPL, copied from the EDKII glue lib.\r
	273	\r
	274	@param VOID.\r
e237e7ae	275	\r
8616fc4c	276	@return Current TPL.\r
	277	\r
	278	**/\r
e237e7ae	279	EFI_TPL\r
	280	UsbGetCurrentTpl (\r
	281	VOID\r
	282	);\r
	283	\r
e237e7ae	284	#endif\r