16. Legacy Region Protocol

This section describes the legacy region protocol that abstracts the platform capability for the BIOS memory region from 0xC0000 to 0xFFFFF. The Legacy Region Protocol is used to abstract the hardware control of the Option ROM and Compatibility 16-bit code region shadowing.

16.1. Legacy Region Protocol

The Legacy Region Protocol controls the read, write and boot-lock attributes for the region 0xC0000 to 0xFFFFF. The table below lists the functions that are included in the Legacy Region Protocol. See EFI_LEGACY_REGION2_PROTOCOL in Code Definitions for the definitions of these functions.

Table 16.1 Functions in Legacy Region Protocol
Function	Description
Decode	Programs the chipset to decode or not decode regions in the 0xC0000 to 0xFFFFF range Governs the read attribute
Lock	Programs the chipset to lock write protect regions in the 0xC0000 to 0xFFFFF range Disables the write attribute
BootLock	Programs the chipset to boot lock regions in the 0xC0000 to 0xFFFFF range Enables the boot lock attribute
Unlock	Programs the chipset to unlock regions in the 0xC0000 to 0xFFFFF range Enables the write attribute
GetInfo	Get information about the granularity of the regions for each attribute

16.2. Code Definitions

16.2.1. Legacy Region Protocol

16.2.2. EFI_LEGACY_REGION2_PROTOCOL

Summary

Abstracts the hardware control of the physical address region 0xC0000-0xFFFFF.

GUID

#define EFI_LEGACY_REGION2_PROTOCOL_GUID \
  { 0x70101eaf, 0x85, 0x440c, 0xb3, 0x56, 0x8e, 0xe3, 0x6f,\
  0xef, 0x24, 0xf0 }

Protocol Interface Structure

typedef struct _EFI_LEGACY_REGION2_PROTOCOL {
  EFI_LEGACY_REGION2_DECODE                 Decode;
  EFI_LEGACY_REGION2_LOCK                   Lock;
  EFI_LEGACY_REGION2_BOOT_LOCK              BootLock;
  EFI_LEGACY_REGION2_UNLOCK                 UnLock;
  EFI_LEGACY_REGION_GET_INFO                GetInfo;
} EFI_LEGACY_REGION2_PROTOCOL;

Parameters

Decode: Modify the read attribute of a memory region. See the Decode() function description.
Lock: Modify the write attribute of a memory region to prevent writes. See the Lock() function description.
BootLock: Modify the boot-lock attribute of a memory region to prevent future changes to the memory attributes for this region. See the BootLock() function description.
Unlock: Modify the write attribute of a memory region to allow writes. See the Unlock() function description.
GetInfo: Modify the write attribute of a memory region to allow writes. See the GetInfo() function description.

Description

The EFI_LEGACY_REGION2_PROTOCOL is used to abstract the hardware control of the memory attributes of the Option ROM shadowing region, 0xC0000 to 0xFFFFF.

There are three memory attributes that can be modified through this protocol: read, write and boot-lock. These protocols may be set in any combination.

16.2.3. EFI_LEGACY_REGION2_PROTOCOL.Decode()

Summary

Modify the hardware to allow (decode) or disallow (not decode) memory reads in a region.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_LEGACY_REGION2_DECODE) (
  IN EFI_LEGACY_REGION2_PROTOCOL   *This,
  IN UINT32                        Start,
  IN UINT32                        Length,
  OUT UINT32                       *Granularity,
  IN BOOLEAN                       *On
  );

Parameters

This: Indicates the EFI_LEGACY_REGION2_PROTOCOL instance.
Start: The beginning of the physical address of the region whose attributes should be modified.
Length: The number of bytes of memory whose attributes should be modified. The actual number of bytes modified may be greater than the number specified.
Granularity: The number of bytes in the last region affected. This may be less than the total number of bytes affected if the starting address was not aligned to a region’s starting address or if the length was greater than the number of bytes in the first region.
On: Decode / Non-Decode flag.

Description

If the On parameter evaluates to TRUE , this function enables memory reads in the address range Start to (Start + Length - 1).

If the On parameter evaluates to FALSE , this function disables memory reads in the address range Start to (Start + Length - 1).

Status Codes Returned

EFI_SUCCESS	The region s attributes were successfully modified
EFI_INVALID_PARAMETER	If Start or Length describe an address not in the Legacy Region

16.2.4. EFI_LEGACY_REGION2_PROTOCOL.Lock()

Summary

Modify the hardware to disallow memory writes in a region.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_REGION2_LOCK) (
  IN EFI_LEGACY_REGION2_PROTOCOL    *This,
  IN UINT32                         Start,
  IN UINT32                         Length,
  OUT UINT32                        *Granularity
);

Parameters

This: Indicates the EFI_LEGACY_REGION2_PROTOCOL instance.
Start: The beginning of the physical address of the region whose attributes should be modified.
Length: The number of bytes of memory whose attributes should be modified. The actual number of bytes modified may be greater than the number specified.
Granularity: The number of bytes in the last region affected. This may be less than the total number of bytes affected if the starting address was not aligned to a region’s starting address or if the length was greater than the number of bytes in the first region.

Description

This function changes the attributes of a memory range to not allow writes.

Status Codes Returned

EFI_SUCCESS	The region s attributes were successfully modified
EFI_INVALID_PARAMETER	If Start or Length describe an address not in the Legacy Region

16.2.5. EFI_LEGACY_REGION2_PROTOCOL.BootLock()

Summary

Modify the hardware to disallow memory attribute changes in a region.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_REGION2_BOOT_LOCK) (
  IN EFI_LEGACY_REGION2_PROTOCOL     *This,
  IN UINT32                          Start,
  IN UINT32                          Length,
  OUT UINT32                         *Granularity
);

Parameters

This: Indicates the EFI_LEGACY_REGION2_PROTOCOL instance.
Start: The beginning of the physical address of the region whose attributes should be modified.
Length: The number of bytes of memory whose attributes should be modified. The actual number of bytes modified may be greater than the number specified.
Granularity: The number of bytes in the last region affected. This may be less than the total number of bytes affected if the starting address was not aligned to a region’s starting address or if the length was greater than the number of bytes in the first region.

Description

This function makes the attributes of a region read only. Once a region is boot-locked with this function, the read and write attributes of that region cannot be changed until a power cycle has reset the boot-lock attribute. Calls to Decode() , Lock() and Unlock() will have no effect.

Status Codes Returned

EFI_SUCCESS	The region s attributes were successfully locked
EFI_INVALID_PARAMETER	If Start or Length describe an address not in the Legacy Region
EFI_UNSUPPORTED	The chipset does not support locking the configuration registers in a way that will not affect memory regions outside the legacy memory region

16.2.6. EFI_LEGACY_REGION2_PROTOCOL.UnLock()

Summary

Modify the hardware to allow memory writes in a region.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_LEGACY_REGION2_UNLOCK) (
  IN EFI_LEGACY_REGION2_PROTOCOL    *This,
  IN UINT32                         Start,
  IN UINT32                         Length,
  OUT UINT32                        *Granularity
);

Parameters

This: Indicates the EFI_LEGACY_REGION2_PROTOCOL instance.
Start: The beginning of the physical address of the region whose attributes should be modified.
Length: The number of bytes of memory whose attributes should be modified. The actual number of bytes modified may be greater than the number specified.
Granularity: The number of bytes in the last region affected. This may be less than the total number of bytes affected if the starting address was not aligned to a region’s starting address or if the length was greater than the number of bytes in the first region.

Description

This function changes the attributes of a memory range to allow writes.

Status Codes Returned

EFI_SUCCESS	The region s attributes were successfully modified
EFI_INVALID_PARAMETER	If Start or Length describe an address not in the Legacy Region

16.2.7. EFI_LEGACY_REGION2_PROTOCOL.GetInfo()

Summary

Get region information for the attributes of the Legacy Region.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_LEGACY_REGION_GET_INFO) (
  IN EFI_LEGACY_REGION2_PROTOCOL     *This,
  OUT UINT32                         *DescriptorCount,
  OUT EFI_LEGACY_REGION_DESCRIPTOR   **Descriptor
  );

Parameters

This: Indicates the EFI_LEGACY_REGION2_PROTOCOL instance.
DescriptorCount: The number of region descriptor entries returned in the Descriptor buffer. Type EFI_LEGACY_REGION_DESCRIPTOR is defined in the “Related Definitions” section.
Descriptor: A pointer to a pointer used to return a buffer where the legacy region information is deposited. This buffer will contain a list of DescriptorCount number of region descriptors. This function will provide the memory for the buffer.

Description

This function is used to discover the granularity of the attributes for the memory in the legacy region. Each attribute may have a different granularity and the granularity may not be the same for all memory ranges in the legacy region.

Status Codes Returned

EFI_SUCCESS	The information structure was returned.
EFI_UNSUPPORTED	This funtion is not supported.

typedef enum {
  LegacyRegionDecoded,
  LegacyRegionNotDecoded,
  LegacyRegionWriteEnabled,
  LegacyRegionWriteDisabled,
  LegacyRegionBootLocked,
  LegacyRegionNotLocked
} EFI_LEGACY_REGION_ATTRIBUTE;

LegacyRegionDecoded: This region is currently set to allow reads.
LegacyRegionNotDecoded: This region is currently set to not allow reads.
LegacyRegionWriteEnabled: This region is currently set to allow writes.
LegacyRegionWriteDisabled: This region is currently set to write protected.
LegacyRegionBootLocked: This region’s attributes are locked, cannot be modified until after a power cycle.
LegacyRegionNotLocked: This region’s attributes are not locked.

typedef struct {
  UINT32                          Start;
  UINT32                          Length;
  EFI_LEGACY_REGION_ATTRIBUTE     Attribute;
  UINT32                          Granularity;
} EFI_LEGACY_REGION_DESCRIPTOR;

Start: The beginning of the physical address of this region.
Length: The number of bytes in this region.
Attribute: Attribute of the Legacy Region Descriptor that describes the capabilities for that memory region.
Granularity: Describes the byte length programmability associated with the Start address and the specified Attribute setting.