IoTrapExDispatch.h 8.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186
  1. /** @file
  2. PCH IO TrapEx Dispatch Protocol
  3. Copyright (c) 2019 Intel Corporation. All rights reserved. <BR>
  4. SPDX-License-Identifier: BSD-2-Clause-Patent
  5. **/
  6. #ifndef _IO_TRAP_EX_DISPATCH_H_
  7. #define _IO_TRAP_EX_DISPATCH_H_
  8. //
  9. // Extern the GUID for protocol users.
  10. //
  11. extern EFI_GUID gIoTrapExDispatchProtocolGuid;
  12. typedef struct _IO_TRAP_EX_DISPATCH_PROTOCOL IO_TRAP_EX_DISPATCH_PROTOCOL;
  13. /**
  14. IO Trap Ex valid types
  15. **/
  16. typedef enum {
  17. IoTrapExTypeWrite,
  18. IoTrapExTypeRead,
  19. IoTrapExTypeReadWrite,
  20. IoTrapExTypeMaximum
  21. } IO_TRAP_EX_DISPATCH_TYPE;
  22. /**
  23. IO Trap Ex context structure containing information about the
  24. IO trap Ex event that should invoke the handler.
  25. ByteEnableMask bitwise to ignore the ByteEnable setting. E.g. 1111b for any byte access.
  26. Here are some examples for the usage.
  27. 1. To trigger the TRAP for the IO address from 0x2000 to 0x20FF with BYTE/WORD/DWORD read/write access:
  28. Address = 0x2000
  29. Length = 0x100
  30. Type = IoTrapExTypeReadWrite
  31. ByteEnable = 0x00 (BE is not matter)
  32. ByteEnableMask = 0x0F (BEM 0xF for any BYTE/WORD/DWORD access)
  33. 2. To trigger the TRAP for port 0x61 with BYTE read access:
  34. Address = 0x60
  35. Length = 4
  36. Type = IoTrapExTypeRead
  37. ByteEnable = 0x02 (BE is 0010b to trap only second byte of every DWORD)
  38. ByteEnableMask = 0x00 (BEM doesn't mask any BE bit)
  39. 3. To trigger the TRAP for port 0x60 and 0x64 with BYTE write access:
  40. Address = 0x60
  41. Length = 8
  42. Type = IoTrapExTypeWrite
  43. ByteEnable = 0x01 (BE is 0001b to trap only first byte of every DWORD)
  44. ByteEnableMask = 0x00 (BEM doesn't mask any BE bit)
  45. **/
  46. typedef struct {
  47. /**
  48. The Address must be dword alignment.
  49. **/
  50. UINT16 Address;
  51. UINT16 Length;
  52. IO_TRAP_EX_DISPATCH_TYPE Type;
  53. /**
  54. Bitmap to enable trap for each byte of every dword alignment address.
  55. The Io Trap Address must be dword alignment for ByteEnable.
  56. E.g. 0001b for first byte, 0010b for second byte, 1100b for third and fourth byte.
  57. **/
  58. UINT8 ByteEnable;
  59. /**
  60. ByteEnableMask bitwise to ignore the ByteEnable setting. E.g. 1111b for any byte access.
  61. The Io Trap Address must be dword alignment for ByteEnableMask.
  62. **/
  63. UINT8 ByteEnableMask;
  64. } IO_TRAP_EX_REGISTER_CONTEXT;
  65. /**
  66. Callback function for an PCH IO TRAP EX handler dispatch.
  67. @param[in] Address DWord-aligned address of the trapped cycle.
  68. @param[in] ByteEnable This is the DWord-aligned byte enables associated with the trapped cycle.
  69. A 1 in any bit location indicates that the corresponding byte is enabled in the cycle.
  70. @param[in] WriteCycle TRUE = Write cycle; FALSE = Read cycle
  71. @param[in] WriteData DWord of I/O write data. This field is undefined after trapping a read cycle.
  72. The byte of WriteData is only valid if the corresponding bits in ByteEnable is 1.
  73. E.g.
  74. If ByteEnable is 0001b, then only first byte of WriteData is valid.
  75. If ByteEnable is 0010b, then only second byte of WriteData is valid.
  76. **/
  77. typedef
  78. VOID
  79. (EFIAPI *IO_TRAP_EX_DISPATCH_CALLBACK) (
  80. IN UINT16 Address,
  81. IN UINT8 ByteEnable,
  82. IN BOOLEAN WriteCycle,
  83. IN UINT32 WriteData
  84. );
  85. /**
  86. Register a new IO Trap Ex SMI dispatch function.
  87. The caller will provide information of IO trap setting via the context.
  88. Please consider to use EfiSmmIoTrapDispatch2Protocol as possible.
  89. This is the function to extend the IoTrap capability, and it's expected
  90. to handle the special ByteEnable and ByteEnableMask setting.
  91. This register function will occupy one IoTrap register if possible.
  92. And it only support one handler for one IoTrap event.
  93. The Address of context MUST NOT be 0, and MUST be dword alignment.
  94. The Length of context MUST not less than 4, and MUST be power of 2.
  95. The ByteEnable and ByteEnableMask MUST not be zero at the same time.
  96. if the IO Trap handler is not used. It also enable the IO Trap Range to generate
  97. SMI.
  98. Caller must take care of reserving the IO addresses in ACPI.
  99. @param[in] This Pointer to the IO_TRAP_EX_DISPATCH_PROTOCOL instance.
  100. @param[in] DispatchFunction Pointer to dispatch function to be invoked for
  101. this SMI source.
  102. @param[in] RegisterContext Pointer to the dispatch function's context.
  103. The caller fills this context in before calling
  104. the register function to indicate to the register
  105. function the IO trap Ex SMI source for which the dispatch
  106. function should be invoked. This MUST not be NULL.
  107. @param[out] DispatchHandle Handle of dispatch function.
  108. @retval EFI_SUCCESS The dispatch function has been successfully
  109. registered and the SMI source has been enabled.
  110. @retval EFI_OUT_OF_RESOURCES Insufficient resources are available
  111. @retval EFI_INVALID_PARAMETER Address requested is already in use.
  112. @retval EFI_ACCESS_DENIED Return access denied if the SmmReadyToLock event has been triggered
  113. **/
  114. typedef
  115. EFI_STATUS
  116. (EFIAPI *IO_TRAP_EX_DISPATCH_REGISTER) (
  117. IN IO_TRAP_EX_DISPATCH_PROTOCOL *This,
  118. IN IO_TRAP_EX_DISPATCH_CALLBACK DispatchFunction,
  119. IN IO_TRAP_EX_REGISTER_CONTEXT *RegisterContext,
  120. OUT EFI_HANDLE *DispatchHandle
  121. );
  122. /**
  123. Unregister a SMI source dispatch function.
  124. This function is unsupported.
  125. @param[in] This Pointer to the IO_TRAP_EX_DISPATCH_PROTOCOL instance.
  126. @param[in] DispatchHandle Handle of dispatch function to deregister.
  127. @retval EFI_UNSUPPORTED The function is unsupported.
  128. **/
  129. typedef
  130. EFI_STATUS
  131. (EFIAPI *IO_TRAP_EX_DISPATCH_UNREGISTER) (
  132. IN IO_TRAP_EX_DISPATCH_PROTOCOL *This,
  133. IN EFI_HANDLE DispatchHandle
  134. );
  135. /**
  136. Interface structure for the IO trap Extention protocol.
  137. This protocol exposes full IO TRAP capability for ByteEnable and ByteEnableMask setting.
  138. Platform code should fully control the ByteEnable and ByteEnableMake while using this protocol.
  139. Please consider to use EfiSmmIoTrapDispatch2Protocol as possible.
  140. This is the function to extend the IoTrap capability, and it's expected
  141. to handle the special ByteEnable and ByteEnableMask setting.
  142. The protocol is low level, It returns PSTH trapped cycle. This might not be safe for multithread
  143. if more than one thread triggers the same IOTRAP at the same time.
  144. **/
  145. struct _IO_TRAP_EX_DISPATCH_PROTOCOL {
  146. /**
  147. Register function for PCH IO TRAP EX DISPATCH PROTOCOL.
  148. The caller will provide information of IO trap setting via the context.
  149. Please consider to use EfiSmmIoTrapDispatch2Protocol as possible.
  150. This is the function to extend the IoTrap capability, and it's expected
  151. to handle the special ByteEnable and ByteEnableMask setting.
  152. This register function will occupy one IoTrap register if possible.
  153. And it only support one handler for one IoTrap event.
  154. The Address of context MUST NOT be 0, and MUST be dword alignment.
  155. The Length of context MUST not less than 4, and MUST be power of 2.
  156. The ByteEnable and ByteEnableMask MUST not be zero at the same time.
  157. if the IO Trap handler is not used. It also enable the IO Trap Range to
  158. generate SMI.
  159. **/
  160. IO_TRAP_EX_DISPATCH_REGISTER Register;
  161. /**
  162. Unregister function for PCH IO TRAP EX DISPATCH PROTOCOL.
  163. **/
  164. IO_TRAP_EX_DISPATCH_UNREGISTER UnRegister;
  165. };
  166. #endif