1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
/** @file
PCH SMM IO Trap Dispatch Protocol
@copyright
Copyright (c) 2005 - 2012 Intel Corporation. All rights reserved
This software and associated documentation (if any) is furnished
under a license and may only be used or copied in accordance
with the terms of the license. Except as permitted by such
license, no part of this software or documentation may be
reproduced, stored in a retrieval system, or transmitted in any
form or by any means without the express written consent of
Intel Corporation.
This file contains a 'Sample Driver' and is licensed as such
under the terms of your license agreement with Intel or your
vendor. This file may be modified by the user, subject to
the additional terms of the license agreement
**/
#ifndef _EFI_SMM_IO_TRAP_DISPATCH_H_
#define _EFI_SMM_IO_TRAP_DISPATCH_H_
///
/// GUID for the SMM IO Trap Dispatch Protocol
///
/// EDK and EDKII have different GUID formats
///
#if !defined(EDK_RELEASE_VERSION) || (EDK_RELEASE_VERSION < 0x00020000)
#define EFI_SMM_IO_TRAP_DISPATCH_PROTOCOL_GUID \
{ \
0xdb7f536b, 0xede4, 0x4714, 0xa5, 0xc8, 0xe3, 0x46, 0xeb, 0xaa, 0x20, 0x1d \
}
#else
#define EFI_SMM_IO_TRAP_DISPATCH_PROTOCOL_GUID \
{ \
0xdb7f536b, 0xede4, 0x4714, \
{ \
0xa5, 0xc8, 0xe3, 0x46, 0xeb, 0xaa, 0x20, 0x1d \
} \
}
#endif
//
// Extern the GUID for protocol users.
//
extern EFI_GUID gEfiSmmIoTrapDispatchProtocolGuid;
//
// Forward reference for ANSI C compatibility
//
typedef struct _EFI_SMM_IO_TRAP_DISPATCH_PROTOCOL EFI_SMM_IO_TRAP_DISPATCH_PROTOCOL;
//
// Related Definitions
//
///
/// IO Trap valid types
///
typedef enum {
WriteTrap,
ReadTrap,
ReadWriteTrap,
IoTrapTypeMaximum
} EFI_SMM_IO_TRAP_DISPATCH_TYPE;
///
/// IO Trap context structure containing information about the IO trap event that should invoke the callback
///
typedef struct {
UINT16 Address; ///< IO Trap range base address (NULL means allocate)
UINT16 Length; ///< IO Trap range length
EFI_SMM_IO_TRAP_DISPATCH_TYPE Type; ///< Access types to trap on
VOID *Context; ///< Callback function context
BOOLEAN MergeDisable; ///< Determine if IoTrap needs to be merged with other registered IoTrap
} EFI_SMM_IO_TRAP_DISPATCH_REGISTER_CONTEXT;
///
/// IO Trap context structure containing information about the IO trap that occurred
///
typedef struct {
UINT16 Address; ///< IO address trapped
EFI_SMM_IO_TRAP_DISPATCH_TYPE Type; ///< IO access type
UINT32 WriteData; ///< Data written (contents undefined for read trap)
VOID *Context; ///< Callback function context
} EFI_SMM_IO_TRAP_DISPATCH_CALLBACK_CONTEXT;
//
// Member functions
//
/**
Dispatch function for an IO Trap specific SMI handler.
@param[in] DispatchHandle Handle of this dispatch function.
@param[in] CallbackContext Pointer to the dispatched function's context.
The CallbackContext fields are updated
by the dispatching driver prior to
invoking this callback function.
@retval None
**/
typedef
VOID
(EFIAPI *EFI_SMM_IO_TRAP_DISPATCH_CALLBACK) (
IN EFI_HANDLE DispatchHandle,
IN EFI_SMM_IO_TRAP_DISPATCH_CALLBACK_CONTEXT * CallbackContext
);
/**
Register an IO trap SMI child handler for a specified SMI.
This service will register a child for a given SMI source.
The caller will provide information about the IO trap characteristics via the context.
This includes base address, length, and type (read, write, read/write).
The service will allocate the IO range if the base address is 0, and the RegisterContext
Address field will be updated and returned to the caller.
The service will allocate system resources via GCD services for the requested IO trap range and type.
An error will be returned if insufficient resources are available to fulfill the request.
The service will not perform GCD allocation if the base address is non-zero. In this case,
the caller is responsible for the existence and allocation of the specific IO range.
An error may be returned if some or all of the requested resources conflict with an existing IO trap child handler.
It is not required that implementations will allow multiple children for a single IO trap SMI source.
Some implementations may support multiple children.
@param[in] This Pointer to the EFI_SMM_IO_TRAP_DISPATCH_PROTOCOL instance.
@param[in] DispatchFunction Pointer to the dispatch function to be invoked for this SMI source.
@param[in, out] 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 SMI source for which the dispatch function should be invoked.
This may not be NULL.
@param[out] DispatchHandle Handle of the dispatch function, for when interfacing with the parent SMM driver.
Type EFI_HANDLE is defined in InstallProtocolInterface() in the EFI 1.10 Specification.
This may not be NULL.
@retval EFI_SUCCESS The dispatch function has been successfully registered.
@retval EFI_DEVICE_ERROR The driver was unable to complete due to hardware error.
@retval EFI_OUT_OF_RESOURCES Insufficient resources are available to fulfill
the IO trap range request.
@retval EFI_INVALID_PARAMETER RegisterContext is invalid. The input value is not within a valid range.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_SMM_IO_TRAP_DISPATCH_REGISTER) (
IN EFI_SMM_IO_TRAP_DISPATCH_PROTOCOL * This,
IN EFI_SMM_IO_TRAP_DISPATCH_CALLBACK DispatchFunction,
IN OUT EFI_SMM_IO_TRAP_DISPATCH_REGISTER_CONTEXT * RegisterContext,
OUT EFI_HANDLE * DispatchHandle
);
/**
Unregister a child SMI source dispatch function with a parent SMM driver
This service removes a previously installed child dispatch handler.
This does not guarantee that the system resources will be freed from the GCD.
@param[in] This Pointer to the EFI_SMM_IO_TRAP_DISPATCH_PROTOCOL instance.
@param[in] DispatchHandle Handle of the child service to remove.
Type EFI_HANDLE is defined in InstallProtocolInterface() in the EFI 1.10 Specification.
@retval EFI_SUCCESS The dispatch function has been successfully
unregistered.
@retval EFI_INVALID_PARAMETER Handle is invalid.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_SMM_IO_TRAP_DISPATCH_UNREGISTER) (
IN EFI_SMM_IO_TRAP_DISPATCH_PROTOCOL * This,
IN EFI_HANDLE * DispatchHandle
);
///
/// Interface structure for the SMM IO trap specific SMI Dispatch Protocol
///
/// This protocol provides the ability to install child handlers for IO trap SMI.
/// These handlers will be invoked to respond to specific IO trap SMI. IO trap SMI
/// would typically be generated on reads or writes to specific processor IO space
/// addresses or ranges. This protocol will typically abstract a limited hardware
/// resource, so callers should handle errors gracefully.
///
struct _EFI_SMM_IO_TRAP_DISPATCH_PROTOCOL {
EFI_SMM_IO_TRAP_DISPATCH_REGISTER Register; ///< Installs a child service to be dispatched when the requested IO trap SMI occurs.
EFI_SMM_IO_TRAP_DISPATCH_UNREGISTER UnRegister; ///< Removes a previously registered child service.
};
#endif
|
