/** @file
|
PCH IO TrapEx Dispatch Protocol
|
|
Copyright (c) 2021, Intel Corporation. All rights reserved.<BR>
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
**/
|
#ifndef _IO_TRAP_EX_DISPATCH_H_
|
#define _IO_TRAP_EX_DISPATCH_H_
|
|
//
|
// Extern the GUID for protocol users.
|
//
|
extern EFI_GUID gIoTrapExDispatchProtocolGuid;
|
|
typedef struct _IO_TRAP_EX_DISPATCH_PROTOCOL IO_TRAP_EX_DISPATCH_PROTOCOL;
|
|
/**
|
IO Trap Ex valid types
|
**/
|
typedef enum {
|
IoTrapExTypeWrite,
|
IoTrapExTypeRead,
|
IoTrapExTypeReadWrite,
|
IoTrapExTypeMaximum
|
} IO_TRAP_EX_DISPATCH_TYPE;
|
|
/**
|
IO Trap Ex context structure containing information about the
|
IO trap Ex event that should invoke the handler.
|
ByteEnableMask bitwise to ignore the ByteEnable setting. E.g. 1111b for any byte access.
|
|
Here are some examples for the usage.
|
1. To trigger the TRAP for the IO address from 0x2000 to 0x20FF with BYTE/WORD/DWORD read/write access:
|
Address = 0x2000
|
Length = 0x100
|
Type = IoTrapExTypeReadWrite
|
ByteEnable = 0x00 (BE is not matter)
|
ByteEnableMask = 0x0F (BEM 0xF for any BYTE/WORD/DWORD access)
|
2. To trigger the TRAP for port 0x61 with BYTE read access:
|
Address = 0x60
|
Length = 4
|
Type = IoTrapExTypeRead
|
ByteEnable = 0x02 (BE is 0010b to trap only second byte of every DWORD)
|
ByteEnableMask = 0x00 (BEM doesn't mask any BE bit)
|
3. To trigger the TRAP for port 0x60 and 0x64 with BYTE write access:
|
Address = 0x60
|
Length = 8
|
Type = IoTrapExTypeWrite
|
ByteEnable = 0x01 (BE is 0001b to trap only first byte of every DWORD)
|
ByteEnableMask = 0x00 (BEM doesn't mask any BE bit)
|
**/
|
typedef struct {
|
/**
|
The Address must be dword alignment.
|
**/
|
UINT16 Address;
|
UINT16 Length;
|
IO_TRAP_EX_DISPATCH_TYPE Type;
|
/**
|
Bitmap to enable trap for each byte of every dword alignment address.
|
The Io Trap Address must be dword alignment for ByteEnable.
|
E.g. 0001b for first byte, 0010b for second byte, 1100b for third and fourth byte.
|
**/
|
UINT8 ByteEnable;
|
/**
|
ByteEnableMask bitwise to ignore the ByteEnable setting. E.g. 1111b for any byte access.
|
The Io Trap Address must be dword alignment for ByteEnableMask.
|
**/
|
UINT8 ByteEnableMask;
|
} IO_TRAP_EX_REGISTER_CONTEXT;
|
|
/**
|
Callback function for an PCH IO TRAP EX handler dispatch.
|
|
@param[in] Address DWord-aligned address of the trapped cycle.
|
@param[in] ByteEnable This is the DWord-aligned byte enables associated with the trapped cycle.
|
A 1 in any bit location indicates that the corresponding byte is enabled in the cycle.
|
@param[in] WriteCycle TRUE = Write cycle; FALSE = Read cycle
|
@param[in] WriteData DWord of I/O write data. This field is undefined after trapping a read cycle.
|
The byte of WriteData is only valid if the corresponding bits in ByteEnable is 1.
|
E.g.
|
If ByteEnable is 0001b, then only first byte of WriteData is valid.
|
If ByteEnable is 0010b, then only second byte of WriteData is valid.
|
**/
|
typedef
|
VOID
|
(EFIAPI *IO_TRAP_EX_DISPATCH_CALLBACK) (
|
IN UINT16 Address,
|
IN UINT8 ByteEnable,
|
IN BOOLEAN WriteCycle,
|
IN UINT32 WriteData
|
);
|
|
/**
|
Register a new IO Trap Ex SMI dispatch function.
|
The caller will provide information of IO trap setting via the context.
|
Please consider to use EfiSmmIoTrapDispatch2Protocol as possible.
|
This is the function to extend the IoTrap capability, and it's expected
|
to handle the special ByteEnable and ByteEnableMask setting.
|
This register function will occupy one IoTrap register if possible.
|
And it only support one handler for one IoTrap event.
|
The Address of context MUST NOT be 0, and MUST be dword alignment.
|
The Length of context MUST not less than 4, and MUST be power of 2.
|
The ByteEnable and ByteEnableMask MUST not be zero at the same time.
|
if the IO Trap handler is not used. It also enable the IO Trap Range to generate
|
SMI.
|
Caller must take care of reserving the IO addresses in ACPI.
|
|
@param[in] This Pointer to the IO_TRAP_EX_DISPATCH_PROTOCOL instance.
|
@param[in] DispatchFunction Pointer to dispatch function to be invoked for
|
this SMI source.
|
@param[in] RegisterContext Pointer to the dispatch function's context.
|
The caller fills this context in before calling
|
the register function to indicate to the register
|
function the IO trap Ex SMI source for which the dispatch
|
function should be invoked. This MUST not be NULL.
|
@param[out] DispatchHandle Handle of dispatch function.
|
|
@retval EFI_SUCCESS The dispatch function has been successfully
|
registered and the SMI source has been enabled.
|
@retval EFI_OUT_OF_RESOURCES Insufficient resources are available
|
@retval EFI_INVALID_PARAMETER Address requested is already in use.
|
@retval EFI_ACCESS_DENIED Return access denied if the SmmReadyToLock event has been triggered
|
**/
|
typedef
|
EFI_STATUS
|
(EFIAPI *IO_TRAP_EX_DISPATCH_REGISTER) (
|
IN IO_TRAP_EX_DISPATCH_PROTOCOL *This,
|
IN IO_TRAP_EX_DISPATCH_CALLBACK DispatchFunction,
|
IN IO_TRAP_EX_REGISTER_CONTEXT *RegisterContext,
|
OUT EFI_HANDLE *DispatchHandle
|
);
|
|
/**
|
Unregister a SMI source dispatch function.
|
This function is unsupported.
|
|
@param[in] This Pointer to the IO_TRAP_EX_DISPATCH_PROTOCOL instance.
|
@param[in] DispatchHandle Handle of dispatch function to deregister.
|
|
@retval EFI_UNSUPPORTED The function is unsupported.
|
**/
|
typedef
|
EFI_STATUS
|
(EFIAPI *IO_TRAP_EX_DISPATCH_UNREGISTER) (
|
IN IO_TRAP_EX_DISPATCH_PROTOCOL *This,
|
IN EFI_HANDLE DispatchHandle
|
);
|
|
/**
|
Interface structure for the IO trap Extention protocol.
|
This protocol exposes full IO TRAP capability for ByteEnable and ByteEnableMask setting.
|
Platform code should fully control the ByteEnable and ByteEnableMake while using this protocol.
|
|
Please consider to use EfiSmmIoTrapDispatch2Protocol as possible.
|
This is the function to extend the IoTrap capability, and it's expected
|
to handle the special ByteEnable and ByteEnableMask setting.
|
|
The protocol is low level, It returns PSTH trapped cycle. This might not be safe for multithread
|
if more than one thread triggers the same IOTRAP at the same time.
|
**/
|
struct _IO_TRAP_EX_DISPATCH_PROTOCOL {
|
/**
|
Register function for PCH IO TRAP EX DISPATCH PROTOCOL.
|
The caller will provide information of IO trap setting via the context.
|
Please consider to use EfiSmmIoTrapDispatch2Protocol as possible.
|
This is the function to extend the IoTrap capability, and it's expected
|
to handle the special ByteEnable and ByteEnableMask setting.
|
This register function will occupy one IoTrap register if possible.
|
And it only support one handler for one IoTrap event.
|
The Address of context MUST NOT be 0, and MUST be dword alignment.
|
The Length of context MUST not less than 4, and MUST be power of 2.
|
The ByteEnable and ByteEnableMask MUST not be zero at the same time.
|
if the IO Trap handler is not used. It also enable the IO Trap Range to
|
generate SMI.
|
**/
|
IO_TRAP_EX_DISPATCH_REGISTER Register;
|
/**
|
Unregister function for PCH IO TRAP EX DISPATCH PROTOCOL.
|
**/
|
IO_TRAP_EX_DISPATCH_UNREGISTER UnRegister;
|
};
|
|
#endif
|
