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