1/** @file
2  This file declares the SMM SMRAM Access abstraction protocol, which is used to control
3  the visibility of the SMRAM on the platform. The expectation is
4  that the north bridge or memory controller would publish this protocol.
5  For example, the Memory Controller Hub (MCH) has the hardware provision for this
6  type of control. Because of the protected, distinguished class of memory for IA-32
7  systems, the expectation is that this protocol would be supported only on IA-32 systems.
8
9Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR>
10This program and the accompanying materials are licensed and made available under
11the terms and conditions of the BSD License that accompanies this distribution.
12The full text of the license may be found at
13http://opensource.org/licenses/bsd-license.php.
14
15THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
16WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
17
18  @par Revision Reference:
19  This Protocol is defined in Framework of EFI SMM Core Interface Spec
20  Version 0.9.
21**/
22
23#ifndef _SMM_ACCESS_H_
24#define _SMM_ACCESS_H_
25
26#include <Guid/SmramMemoryReserve.h>
27
28typedef struct _EFI_SMM_ACCESS_PROTOCOL  EFI_SMM_ACCESS_PROTOCOL;
29
30#define EFI_SMM_ACCESS_PROTOCOL_GUID \
31  { \
32    0x3792095a, 0xe309, 0x4c1e, {0xaa, 0x01, 0x85, 0xf5, 0x65, 0x5a, 0x17, 0xf1 } \
33  }
34
35//
36// SMM Access specification Member Function
37//
38/**
39  Opens the SMRAM area to be accessible by a boot-service driver.
40
41  @param  This                  The EFI_SMM_ACCESS_PROTOCOL instance.
42  @param  DescriptorIndex       Indicates that the driver wishes to open
43                                the memory tagged by this index.
44
45  @retval EFI_SUCCESS           The operation was successful.
46  @retval EFI_INVALID_PARAMETER The given DescriptorIndex is not supported.
47  @retval EFI_NOT_STARTED       The SMM base service has not been initialized.
48
49**/
50typedef
51EFI_STATUS
52(EFIAPI *EFI_SMM_OPEN)(
53  IN EFI_SMM_ACCESS_PROTOCOL         *This,
54  UINTN                              DescriptorIndex
55  );
56
57/**
58  Inhibits access to the SMRAM.
59
60  @param  This                  The EFI_SMM_ACCESS_PROTOCOL instance.
61  @param  DescriptorIndex       Indicates that the driver wishes to close
62                                the memory tagged by this index.
63
64  @retval EFI_SUCCESS           The operation was successful.
65  @retval EFI_DEVICE_ERROR      The given DescriptorIndex is not open.
66  @retval EFI_INVALID_PARAMETER The given DescriptorIndex is not supported.
67  @retval EFI_NOT_STARTED       The SMM base service has not been initialized.
68
69**/
70typedef
71EFI_STATUS
72(EFIAPI *EFI_SMM_CLOSE)(
73  IN EFI_SMM_ACCESS_PROTOCOL          *This,
74  UINTN                               DescriptorIndex
75  );
76
77/**
78  Inhibits access to the SMRAM.
79
80  @param  This                  The EFI_SMM_ACCESS_PROTOCOL instance.
81  @param  DescriptorIndex       Indicates that the driver wishes to lock
82                                the memory tagged by this index.
83
84  @retval EFI_SUCCESS           The operation was successful.
85  @retval EFI_DEVICE_ERROR      The given DescriptorIndex is not open.
86  @retval EFI_INVALID_PARAMETER The given DescriptorIndex is not supported.
87  @retval EFI_NOT_STARTED       The SMM base service has not been initialized.
88
89**/
90typedef
91EFI_STATUS
92(EFIAPI *EFI_SMM_LOCK)(
93  IN EFI_SMM_ACCESS_PROTOCOL         *This,
94  UINTN                              DescriptorIndex
95  );
96
97/**
98  Queries the memory controller for the possible regions that will support SMRAM.
99
100  @param  This                  The EFI_SMM_ACCESS_PROTOCOL instance.
101  @param  SmramMapSize          A pointer to the size, in bytes, of the SmramMemoryMap buffer.
102  @param  SmramMap              A pointer to the buffer in which firmware places the current memory map.
103
104  @retval EFI_SUCCESS           The chipset supported the given resource.
105  @retval EFI_BUFFER_TOO_SMALL  The SmramMap parameter was too small.
106
107**/
108typedef
109EFI_STATUS
110(EFIAPI *EFI_SMM_CAPABILITIES)(
111  IN EFI_SMM_ACCESS_PROTOCOL             *This,
112  IN OUT UINTN                           *SmramMapSize,
113  IN OUT EFI_SMRAM_DESCRIPTOR            *SmramMap
114  );
115
116/**
117  This protocol is used to control the visibility of the SMRAM on the platform.
118**/
119struct _EFI_SMM_ACCESS_PROTOCOL {
120  EFI_SMM_OPEN          Open;             ///< Opens the SMRAM.
121  EFI_SMM_CLOSE         Close;            ///< Closes the SMRAM.
122  EFI_SMM_LOCK          Lock;             ///< Locks the SMRAM.
123  EFI_SMM_CAPABILITIES  GetCapabilities;  ///< Gets information on possible SMRAM regions.
124  BOOLEAN               LockState;        ///< Indicates the current state of the SMRAM. Set to TRUE if any region is locked.
125  BOOLEAN               OpenState;        ///< Indicates the current state of the SMRAM. Set to TRUE if any region is open.
126};
127
128extern EFI_GUID gEfiSmmAccessProtocolGuid;
129
130#endif
131