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