[mirror_edk2.git] / MdePkg / Include / Protocol / AbsolutePointer.h

/** @file\r
  The file provides services that allow information about a\r
  absolute pointer device to be retrieved.\r
  \r
  Copyright (c) 2006 - 2008, Intel Corporation\r
  All rights reserved. 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 __ABSOLUTE_POINTER_H__\r
#define __ABSOLUTE_POINTER_H__\r
\r
\r
#define EFI_ABSOLUTE_POINTER_PROTOCOL_GUID \\r
  { 0x8D59D32B, 0xC655, 0x4AE9, { 0x9B, 0x15, 0xF2, 0x59, 0x04, 0x99, 0x2A, 0x43 } }\r
\r
\r
typedef struct _EFI_ABSOLUTE_POINTER_PROTOCOL EFI_ABSOLUTE_POINTER_PROTOCOL;\r
\r
\r
//*******************************************************\r
// EFI_ABSOLUTE_POINTER_MODE\r
//*******************************************************\r
\r
\r
/**\r
  The following data values in the EFI_ABSOLUTE_POINTER_MODE\r
  interface are read-only and are changed by using the appropriate\r
  interface functions.\r
  \r
  @param AbsoluteMinX The Absolute Minimum of the device on the\r
                      x-axis.\r
\r
  @param AbsoluteMinY The Absolute Minimum of the device on the\r
                      y axis.\r
\r
  @param AbsoluteMinZ The Absolute Minimum of the device on the\r
                      z-axis.\r
\r
  @param AbsoluteMaxX The Absolute Maximum of the device on the\r
                      x-axis. If 0, and the AbsoluteMinX is 0,\r
                      then the pointer device does not support a\r
                      xaxis.\r
\r
  @param AbsoluteMaxY The Absolute Maximum of the device on the\r
                      y -axis. If 0,, and the AbsoluteMinX is 0,\r
                      then the pointer device does not support a\r
                      yaxis.\r
\r
  @param AbsoluteMaxZ The Absolute Maximum of the device on the\r
                      z-axis. If 0 , and the AbsoluteMinX is 0,\r
                      then the pointer device does not support a\r
                      zaxis. \r
\r
  @param Attributes   The following bits are set as needed (or'd\r
                      together) to indicate the capabilities of the device\r
                      supported. The remaining bits are undefined and should be 0.\r
\r
**/\r
typedef struct {\r
  UINT64 AbsoluteMinX;\r
  UINT64 AbsoluteMinY;\r
  UINT64 AbsoluteMinZ;\r
  UINT64 AbsoluteMaxX;\r
  UINT64 AbsoluteMaxY;\r
  UINT64 AbsoluteMaxZ;\r
  UINT32 Attributes;\r
} EFI_ABSOLUTE_POINTER_MODE;\r
\r
///\r
/// If set, indicates this device supports an alternate button input. \r
/// \r
#define EFI_ABSP_SupportsAltActive    0x00000001\r
\r
///\r
/// If set, indicates this device returns pressure data in parameter CurrentZ.\r
/// \r
#define EFI_ABSP_SupportsPressureAsZ  0x00000002\r
\r
\r
/**\r
  This function resets the pointer device hardware. As part of\r
  initialization process, the firmware/device will make a quick\r
  but reasonable attempt to verify that the device is\r
  functioning. If the ExtendedVerification flag is TRUE the\r
  firmware may take an extended amount of time to verify the\r
  device is operating on reset. Otherwise the reset operation is\r
  to occur as quickly as possible. The hardware verification\r
  process is not defined by this specification and is left up to\r
  the platform firmware or driver to implement.\r
\r
  @param This                 A pointer to the EFI_ABSOLUTE_POINTER_PROTOCOL\r
                              instance.\r
\r
  @param ExtendedVerification Indicates that the driver may\r
                              perform a more exhaustive\r
                              verification operation of the\r
                              device during reset.\r
\r
  @retval EFI_SUCCESS       The device was reset.\r
  \r
  @retval EFI_DEVICE_ERROR  The device is not functioning\r
                            correctly and could not be reset.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_ABSOLUTE_POINTER_RESET)(\r
  IN EFI_ABSOLUTE_POINTER_PROTOCOL *This,\r
  IN BOOLEAN                       ExtendedVerification\r
);\r
\r
\r
\r
\r
/**\r
  Definitions of bits within ActiveButtons.\r
  \r
  @param EFI_ABSP_TouchActive This bit is set if the touch\r
                              sensor is active.\r
  \r
  @param EFI_ABS_AltActive    This bit is set if the alt sensor,\r
                              such as pen-side button, is\r
                              active.\r
**/\r
#define EFI_ABSP_TouchActive  0x00000001\r
#define EFI_ABS_AltActive     0x00000002\r
\r
\r
/**\r
  Definition of EFI_ABSOLUTE_POINTER_STATE.\r
  \r
  @param CurrentX The unsigned position of the activation on the\r
                  x axis If the AboluteMinX and the AboluteMaxX\r
                  fields of the EFI_ABSOLUTE_POINTER_MODE\r
                  structure are both 0, then this pointer device\r
                  does not support an x-axis, and this field\r
                  must be ignored.\r
\r
  @param CurrentY The unsigned position of the activation on the\r
                  x axis If the AboluteMinY and the AboluteMaxY\r
                  fields of the EFI_ABSOLUTE_POINTER_MODE\r
                  structure are both 0, then this pointer device\r
                  does not support an y-axis, and this field\r
                  must be ignored.\r
\r
  @param CurrentZ The unsigned position of the activation on the\r
                  x axis, or the pressure measurement. If the\r
                  AboluteMinZ and the AboluteMaxZ fields of the\r
                  EFI_ABSOLUTE_POINTER_MODE structure are\r
                  both 0, then this pointer device does not\r
                  support an z-axis, and this field must be\r
                  ignored.\r
\r
  @param ActiveButtons Bits are set to 1 in this structure item\r
                       to indicate that device buttons are\r
                       active.\r
\r
**/\r
typedef struct {\r
  UINT64 CurrentX;\r
  UINT64 CurrentY;\r
  UINT64 CurrentZ;\r
  UINT32 ActiveButtons;\r
} EFI_ABSOLUTE_POINTER_STATE;\r
\r
/**\r
  The GetState() function retrieves the current state of a pointer\r
  device. This includes information on the active state associated\r
  with the pointer device and the current position of the axes\r
  associated with the pointer device. If the state of the pointer\r
  device has not changed since the last call to GetState(), then\r
  EFI_NOT_READY is returned. If the state of the pointer device\r
  has changed since the last call to GetState(), then the state\r
  information is placed in State, and EFI_SUCCESS is returned. If\r
  a device error occurs while attempting to retrieve the state\r
  information, then EFI_DEVICE_ERROR is returned.\r
\r
\r
  @param This   A pointer to the EFI_ABSOLUTE_POINTER_PROTOCOL\r
                instance.\r
\r
  @param State  A pointer to the state information on the\r
                pointer device.\r
\r
  @retval EFI_SUCCESS       The state of the pointer device was\r
                            returned in State.\r
\r
  @retval EFI_NOT_READY     The state of the pointer device has not\r
                            changed since the last call to GetState().\r
\r
  @retval EFI_DEVICE_ERROR  A device error occurred while\r
                            attempting to retrieve the pointer\r
                            device's current state.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_ABSOLUTE_POINTER_GET_STATE)(\r
  IN 		EFI_ABSOLUTE_POINTER_PROTOCOL  *This,\r
  IN OUT    EFI_ABSOLUTE_POINTER_STATE *State\r
);\r
\r
\r
/**\r
  @par Protocol Description:\r
  The EFI_ABSOLUTE_POINTER_PROTOCOL provides a set of services\r
  for a pointer device that can be used as an input device from an\r
  application written to this specification. The services include\r
  the ability to reset the pointer device, retrieve the state of\r
  the pointer device, and retrieve the capabilities of the pointer\r
  device. In addition certain data items describing the device are\r
  provided.\r
\r
\r
  @param Reset        Resets the pointer device.\r
\r
  @param GetState     Retrieves the current state of the pointer\r
                      device.\r
\r
  @param WaitForInput Event to use with WaitForEvent() to wait\r
                      for input from the pointer device.\r
  @param Mode         Pointer to EFI_ABSOLUTE_POINTER_MODE data.\r
\r
**/\r
struct _EFI_ABSOLUTE_POINTER_PROTOCOL {\r
  EFI_ABSOLUTE_POINTER_RESET      Reset;\r
  EFI_ABSOLUTE_POINTER_GET_STATE  GetState;\r
  EFI_EVENT                       WaitForInput;\r
  EFI_ABSOLUTE_POINTER_MODE       *Mode;\r
};\r
\r
\r
extern EFI_GUID gEfiAbsolutePointerProtocolGuid;\r
\r
\r
#endif\r
\r
Commit	Line	Data
d1f95000	1	/** @file\r
	2	The file provides services that allow information about a\r
	3	absolute pointer device to be retrieved.\r
	4	\r
4ca9b6c4	5	Copyright (c) 2006 - 2008, Intel Corporation\r
d1f95000	6	All rights reserved. This program and the accompanying materials \r
	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
d1f95000	14	**/\r
	15	\r
	16	#ifndef __ABSOLUTE_POINTER_H__\r
	17	#define __ABSOLUTE_POINTER_H__\r
	18	\r
	19	\r
	20	#define EFI_ABSOLUTE_POINTER_PROTOCOL_GUID \\r
	21	{ 0x8D59D32B, 0xC655, 0x4AE9, { 0x9B, 0x15, 0xF2, 0x59, 0x04, 0x99, 0x2A, 0x43 } }\r
	22	\r
	23	\r
	24	typedef struct _EFI_ABSOLUTE_POINTER_PROTOCOL EFI_ABSOLUTE_POINTER_PROTOCOL;\r
	25	\r
	26	\r
	27	//*******************************************************\r
	28	// EFI_ABSOLUTE_POINTER_MODE\r
	29	//*******************************************************\r
	30	\r
	31	\r
	32	/**\r
	33	The following data values in the EFI_ABSOLUTE_POINTER_MODE\r
	34	interface are read-only and are changed by using the appropriate\r
4ca9b6c4	35	interface functions.\r
d1f95000	36	\r
	37	@param AbsoluteMinX The Absolute Minimum of the device on the\r
	38	x-axis.\r
	39	\r
	40	@param AbsoluteMinY The Absolute Minimum of the device on the\r
	41	y axis.\r
	42	\r
	43	@param AbsoluteMinZ The Absolute Minimum of the device on the\r
	44	z-axis.\r
	45	\r
	46	@param AbsoluteMaxX The Absolute Maximum of the device on the\r
	47	x-axis. If 0, and the AbsoluteMinX is 0,\r
	48	then the pointer device does not support a\r
	49	xaxis.\r
	50	\r
	51	@param AbsoluteMaxY The Absolute Maximum of the device on the\r
	52	y -axis. If 0,, and the AbsoluteMinX is 0,\r
	53	then the pointer device does not support a\r
	54	yaxis.\r
	55	\r
	56	@param AbsoluteMaxZ The Absolute Maximum of the device on the\r
	57	z-axis. If 0 , and the AbsoluteMinX is 0,\r
	58	then the pointer device does not support a\r
	59	zaxis. \r
	60	\r
4ca9b6c4 LG	61	@param Attributes The following bits are set as needed (or'd\r
	62	together) to indicate the capabilities of the device\r
	63	supported. The remaining bits are undefined and should be 0.\r
	64	\r
d1f95000	65	**/\r
	66	typedef struct {\r
	67	UINT64 AbsoluteMinX;\r
	68	UINT64 AbsoluteMinY;\r
	69	UINT64 AbsoluteMinZ;\r
	70	UINT64 AbsoluteMaxX;\r
	71	UINT64 AbsoluteMaxY;\r
	72	UINT64 AbsoluteMaxZ;\r
	73	UINT32 Attributes;\r
	74	} EFI_ABSOLUTE_POINTER_MODE;\r
	75	\r
99e8ed21	76	///\r
	77	/// If set, indicates this device supports an alternate button input. \r
	78	/// \r
d1f95000	79	#define EFI_ABSP_SupportsAltActive 0x00000001\r
d1f95000	80	\r
99e8ed21	81	///\r
	82	/// If set, indicates this device returns pressure data in parameter CurrentZ.\r
	83	/// \r
d1f95000	84	#define EFI_ABSP_SupportsPressureAsZ 0x00000002\r
	85	\r
	86	\r
	87	/**\r
	88	This function resets the pointer device hardware. As part of\r
	89	initialization process, the firmware/device will make a quick\r
	90	but reasonable attempt to verify that the device is\r
	91	functioning. If the ExtendedVerification flag is TRUE the\r
	92	firmware may take an extended amount of time to verify the\r
	93	device is operating on reset. Otherwise the reset operation is\r
	94	to occur as quickly as possible. The hardware verification\r
	95	process is not defined by this specification and is left up to\r
	96	the platform firmware or driver to implement.\r
	97	\r
4ca9b6c4 LG	98	@param This A pointer to the EFI_ABSOLUTE_POINTER_PROTOCOL\r
4ca9b6c4 LG	99	instance.\r
d1f95000	100	\r
	101	@param ExtendedVerification Indicates that the driver may\r
	102	perform a more exhaustive\r
	103	verification operation of the\r
	104	device during reset.\r
	105	\r
4ca9b6c4	106	@retval EFI_SUCCESS The device was reset.\r
d1f95000	107	\r
	108	@retval EFI_DEVICE_ERROR The device is not functioning\r
	109	correctly and could not be reset.\r
	110	\r
	111	**/\r
	112	typedef\r
	113	EFI_STATUS\r
8b13229b	114	(EFIAPI *EFI_ABSOLUTE_POINTER_RESET)(\r
8ae0b360	115	IN EFI_ABSOLUTE_POINTER_PROTOCOL *This,\r
8ae0b360	116	IN BOOLEAN ExtendedVerification\r
d1f95000	117	);\r
	118	\r
	119	\r
	120	\r
	121	\r
	122	/**\r
	123	Definitions of bits within ActiveButtons.\r
	124	\r
	125	@param EFI_ABSP_TouchActive This bit is set if the touch\r
	126	sensor is active.\r
	127	\r
	128	@param EFI_ABS_AltActive This bit is set if the alt sensor,\r
	129	such as pen-side button, is\r
	130	active.\r
	131	**/\r
	132	#define EFI_ABSP_TouchActive 0x00000001\r
	133	#define EFI_ABS_AltActive 0x00000002\r
	134	\r
	135	\r
	136	/**\r
	137	Definition of EFI_ABSOLUTE_POINTER_STATE.\r
	138	\r
	139	@param CurrentX The unsigned position of the activation on the\r
	140	x axis If the AboluteMinX and the AboluteMaxX\r
	141	fields of the EFI_ABSOLUTE_POINTER_MODE\r
	142	structure are both 0, then this pointer device\r
	143	does not support an x-axis, and this field\r
	144	must be ignored.\r
	145	\r
	146	@param CurrentY The unsigned position of the activation on the\r
	147	x axis If the AboluteMinY and the AboluteMaxY\r
	148	fields of the EFI_ABSOLUTE_POINTER_MODE\r
	149	structure are both 0, then this pointer device\r
	150	does not support an y-axis, and this field\r
	151	must be ignored.\r
	152	\r
	153	@param CurrentZ The unsigned position of the activation on the\r
	154	x axis, or the pressure measurement. If the\r
	155	AboluteMinZ and the AboluteMaxZ fields of the\r
	156	EFI_ABSOLUTE_POINTER_MODE structure are\r
	157	both 0, then this pointer device does not\r
	158	support an z-axis, and this field must be\r
	159	ignored.\r
	160	\r
4ca9b6c4	161	@param ActiveButtons Bits are set to 1 in this structure item\r
d1f95000	162	to indicate that device buttons are\r
	163	active.\r
	164	\r
	165	**/\r
	166	typedef struct {\r
	167	UINT64 CurrentX;\r
	168	UINT64 CurrentY;\r
	169	UINT64 CurrentZ;\r
	170	UINT32 ActiveButtons;\r
	171	} EFI_ABSOLUTE_POINTER_STATE;\r
	172	\r
	173	/**\r
	174	The GetState() function retrieves the current state of a pointer\r
	175	device. This includes information on the active state associated\r
	176	with the pointer device and the current position of the axes\r
	177	associated with the pointer device. If the state of the pointer\r
	178	device has not changed since the last call to GetState(), then\r
	179	EFI_NOT_READY is returned. If the state of the pointer device\r
	180	has changed since the last call to GetState(), then the state\r
	181	information is placed in State, and EFI_SUCCESS is returned. If\r
	182	a device error occurs while attempting to retrieve the state\r
	183	information, then EFI_DEVICE_ERROR is returned.\r
	184	\r
	185	\r
4ca9b6c4 LG	186	@param This A pointer to the EFI_ABSOLUTE_POINTER_PROTOCOL\r
4ca9b6c4 LG	187	instance.\r
d1f95000	188	\r
	189	@param State A pointer to the state information on the\r
	190	pointer device.\r
	191	\r
4ca9b6c4 LG	192	@retval EFI_SUCCESS The state of the pointer device was\r
4ca9b6c4 LG	193	returned in State.\r
d1f95000	194	\r
4ca9b6c4 LG	195	@retval EFI_NOT_READY The state of the pointer device has not\r
4ca9b6c4 LG	196	changed since the last call to GetState().\r
d1f95000	197	\r
	198	@retval EFI_DEVICE_ERROR A device error occurred while\r
	199	attempting to retrieve the pointer\r
	200	device's current state.\r
	201	\r
	202	**/\r
	203	typedef\r
	204	EFI_STATUS\r
8b13229b	205	(EFIAPI *EFI_ABSOLUTE_POINTER_GET_STATE)(\r
4ca9b6c4 LG	206	IN EFI_ABSOLUTE_POINTER_PROTOCOL *This,\r
4ca9b6c4 LG	207	IN OUT EFI_ABSOLUTE_POINTER_STATE *State\r
d1f95000	208	);\r
	209	\r
	210	\r
	211	/**\r
4ca9b6c4	212	@par Protocol Description:\r
d1f95000	213	The EFI_ABSOLUTE_POINTER_PROTOCOL provides a set of services\r
	214	for a pointer device that can be used as an input device from an\r
	215	application written to this specification. The services include\r
	216	the ability to reset the pointer device, retrieve the state of\r
	217	the pointer device, and retrieve the capabilities of the pointer\r
	218	device. In addition certain data items describing the device are\r
	219	provided.\r
	220	\r
	221	\r
4ca9b6c4	222	@param Reset Resets the pointer device.\r
d1f95000	223	\r
4ca9b6c4 LG	224	@param GetState Retrieves the current state of the pointer\r
4ca9b6c4 LG	225	device.\r
d1f95000	226	\r
	227	@param WaitForInput Event to use with WaitForEvent() to wait\r
	228	for input from the pointer device.\r
4ca9b6c4	229	@param Mode Pointer to EFI_ABSOLUTE_POINTER_MODE data.\r
d1f95000	230	\r
	231	**/\r
	232	struct _EFI_ABSOLUTE_POINTER_PROTOCOL {\r
	233	EFI_ABSOLUTE_POINTER_RESET Reset;\r
	234	EFI_ABSOLUTE_POINTER_GET_STATE GetState;\r
	235	EFI_EVENT WaitForInput;\r
	236	EFI_ABSOLUTE_POINTER_MODE *Mode;\r
	237	};\r
	238	\r
	239	\r
	240	extern EFI_GUID gEfiAbsolutePointerProtocolGuid;\r
	241	\r
	242	\r
	243	#endif\r
	244	\r