PHOENIX SMM CPU PAGE PROTOCOL

From PhoenixWiki

Jump to: navigation, search

Provide translation and copying services using non-SMM linear addresses.

Contents

Protocol Interface Structure

#include EFI_PROTOCOL_CONSUMER(PhoenixSmmCpuPage)

typedef struct _PHOENIX_SMM_CPU_PAGE_PROTOCOL {
  PHOENIX_SMM_CPU_CONVERT_SEGOFFREG_TO_LINEAR ConvertSegOffsetRegToLinear;
  PHOENIX_SMM_CPU_CONVERT_SEGOFF_TO_LINEAR    ConvertSegOffsetToLinear;
  PHOENIX_SMM_CPU_CONVERT_LINEAR_TO_PHYSICAL  ConvertLinearToPhysical;
  PHOENIX_SMM_CPU_COPY_FROM_LINEAR            CopyFromLinear;
  PHOENIX_SMM_CPU_COPY_TO_LINEAR              CopyToLinear;
} PHOENIX_SMM_CPU_PAGE_PROTOCOL, *PPHOENIX_SMM_CPU_PAGE_PROTOCOL;

Members

Member Description
ConvertSegOffsetRegToLinear A pointer to a function that converts the segment/selector register and an offset register to a linear address.
ConvertSegOffsetToLinear A pointer to a function that converts the segment/selector and an offset to a linear address.
ConvertLinearToPhysical Convert a linear address to a physical address.
CopyFromLinear A pointer to a function that copies data from a buffer specified by a linear address to a buffer specified by a physical address.
CopyToLinear A pointer to a function that copies data to a buffer specified by a linear address from a buffer specified by a physical address.

Description

This protocol converts segment/selector and offset values into linear addresses. It also copies data to and from buffers specified with linear addresses.

ConvertSegOffsetRegToLinear()

Convert a segment/offset register to a linear address.

Prototype

typedef 
EFI_STATUS
(EFIAPI *PHOENIX_SMM_CPU_CONVERT_SEGOFFREG_TO_LINEAR)(
    IN  UINTN                       CpuIndex, OPTIONAL
    IN  EFI_SMM_SAVE_STATE_REGISTER SegmentRegister, OPTIONAL
    IN  EFI_SMM_SAVE_STATE_REGISTER OffsetRegister,  OPTIONAL
    OUT EFI_VIRTUAL_ADDRESS         *LinearAddress
    );

Parameters

Parameter Description
CpuIndex A zero-based index associated with the the CPU to read the SegmentRegister and OffsetRegister registers from. The maximum value is calculated as EFI_SMM_SYSTEM_TABLE.NumberOfCpus – 1 (as described in the Tiano SMM CIS).
SegmentRegister The CPU Register Enumerator specifying the segment/selector register to use. A value of zero indicates that this parameter will be ignored.
OffsetRegister The CPU Register Enumerator specifying the offset register to use. A value of zero indicates that this parameter will be ignored. The zero-extended 32-bit register will be used if the CPU was running in real-mode, virtual 8086 mode or 32-bit protected mode outside of SMM. The 64-bit register will be used if the CPU was running in 64-bit mode outside of SMM.
LinearAddress A pointer to the returned calculated linear address.

Description
This function finds the base address of the segment or selector register specified by SegmentRegister and adds it to the value of the register specified by OffsetRegister and updates the value pointed to by Linear, using register values from the CPU specified by CpuIndex.

If SegmentRegister is zero, then only the value of the register specified by OffsetRegister value will be returned in LinearAddress.

If OffsetRegister is zero, then only the base address of the segment/selector specified by SegmentRegister will be returned in LinearAddress.

If both SegmentRegister and OffsetRegister are zero then zero will be returned in LinearAddress.

Status Codes Returned

Status Code Description
EFI_SUCCESS Offset value calculated successfully. Offset points to the offset.
EFI_NOT_FOUND The SegmentRegister or OffsetRegister register was non-zero but could not be read from the CPU save state.
EFI_NO_MAPPING The value specified by SegmentRegister was not a valid offset into the GDT or LDT.
EFI_INVALID_PARAMETER LinearAddress is NULL.
EFI_INVALID_PARAMETER The CpuIndex specified is invalid.

ConvertSegOffsetToLinear()

Convert a segment/offset address to a linear address.

Prototype

typedef 
EFI_STATUS
(EFIAPI *PHOENIX_SMM_CPU_CONVERT_SEGOFF_TO_LINEAR)(
  IN  UINTN                       CpuIndex, OPTIONAL
  IN  UINT16                      Segment, OPTIONAL
  IN  UINT64                      Offset,  OPTIONAL
  OUT EFI_VIRTUAL_ADDRESS        *LinearAddress
  );

Parameters

Parameter Description
CpuIndex A zero-based index associated with the CPU to retrieve the base address of the segment or selector from. The maximum value is calculated as EFI_SMM_SYSTEM_TABLE.NumberOfCpus – 1 (as described in the Tiano SMM CIS).
Segment A 16-bit unsigned integer specifying the segment or selector value to be converted.
Offset A 64-bit unsigned integer specifying offset to be added to the converted Segment value.
LinearAddress A pointer to the returned calculated linear address.

Description
This function finds the base address of the segment or selector specified by Segment and adds it to the value of the offset specified by Offset and updates the value pointed to by Linear, getting the base address values of the segment or selector from the CPU specified by CpuIndex.

If Segment is zero, then only the value of the register specified by Offset value will be returned in LinearAddress.

If Offset is zero, then only the base address of the segment/selector specified by Segment will be returned in LinearAddress.

If both Segment and Offset are zero then zero will be returned in LinearAddress.

Status Codes Returned

Status Code Description
EFI_SUCCESS Offset value calculated successfully. Offset points to the offset.
EFI_NOT_FOUND The Segment was non-zero but could not be retrieved the base address of the segment or selector.
EFI_NO_MAPPING The value specified by Segment was not a valid offset into the GDT or LDT.
EFI_INVALID_PARAMETER LinearAddress is NULL.
EFI_INVALID_PARAMETER The CpuIndex specified is invalid.

ConvertLinearToPhysical()

Convert a linear address to a physical address.

Prototype

typedef 
EFI_STATUS
(EFIAPI *PHOENIX_SMM_CPU_CONVERT_LINEAR_TO_SEGOFF)(
  IN  UINTN                CpuIndex,
  IN  EFI_VIRTUAL_ADDRESS   LinearAddress
  OUT EFI_PHYSICAL_ADDRESS *PhysicalAddress,
  OUT UINTN                *NumBytesBeforeConversion OPTIONAL
  );

Parameters

Parameter Description
CpuIndex The zero-based index associated with the CPU to read the register from. The maximum value is calculated as EFI_SMM_SYSTEM_TABLE.NumberOfCpus – 1 (as described in the Tiano SMM CIS).
LinearAddress The linear address specifying a 64-bit address to be converted.
PhysicalAddress A pointer to the returned physical address.
NumBytesBeforeConversion A pointer to an unsigned integer. On return, it holds the number of bytes after LinearAddress when another conversion will be required due to crossing a page table boundary.

Description
This function converts the linear address LinearAddress to the physical address PhysicalAddress.

If the CPU associated with CpuIndex was in a paging mode, then the page table will be used to make the conversion from linear to physical. In addition, NumBytesBeforeConversion will be updated to point to the number of bytes left in the current page.

For example, if the page size was 4KB and the address was 0x3FFFF, NumBytesBeforeConversion would be set to 1. If the CPU associated with CpuIndex was not in paging mode, then the page table will not be used and the physical address will be the same as the linear address. NumBytesBeforeConversion will be calculated as 0 – LinearAddress.

Status Codes Returned

Status Code Description
EFI_SUCCESS The function completed successfully.
EFI_INVALID_PARAMETER PhysicalAddress is NULL.
EFI_INVALID_PARAMETER The CpuIndex specified is invalid.

CopyToLinear()

Copy data from a buffer specified by a physical address to a buffer specified by a linear address, taking page boundaries into consideration.

Prototype

typedef
EFI_STATUS
(EFIAPI *PHOENIX_SMM_CPU_COPY_TO_LINEAR)(
  IN EFI_PHYSICAL_ADDRESS Src,
  IN UINTN                CpuIndex,
  IN EFI_VIRTUAL_ADDRESS  Dest,
  IN UINTN                Size
  );

Parameters

Parameter Description
Src The physical address of the source data.
CpuIndex A zero-based index associated with the CPU whose page tables will be used. The maximum value is calculated as EFI_SMM_SYSTEM_TABLE.NumberOfCpus – 1 (as described in the Tiano SMM CIS).
Dest The linear address of the destination for the data.
Size The number of bytes to copy.

Description
This function copies Size bytes of data from the buffer at the physical address specified by Src to the buffer at the linear address specified by Dest, using the page tables from the CPU specified by CpuIndex. If the destination crosses a page table boundary, this is handled correctly. If there is no valid page for some or all of the destination, EFI_DEVICE_ERROR is returned, in which case some of the data may have been copied.

Status Codes Returned

Status Code Description
EFI_SUCCESS The function completed successfully.
EFI_DATA_ERROR Some of all of linear addresses from Dest to Dest + Size – 1 had no valid page table entry.
EFI_INVALID_PARAMETER The CpuIndex specified is invalid.

CopyFromLinear()

Copy data from a buffer specified by a linear address to a buffer specified by a physical address, taking page boundaries into consideration.

Prototype

typedef
EFI_STATUS
(EFIAPI *PHOENIX_SMM_CPU_COPY_FROM_LINEAR)(
  IN EFI_VIRTUAL_ADDRESS  Src,
  IN UINTN                CpuIndex,
  IN EFI_PHYSICAL_ADDRESS Dest,
  IN UINTN                Size
  );

Parameters

Parameter Description
Src The linear address of the source data buffer.
CpuIndex A zero-based index associated with the CPU whose page tables will be used. The maximum value is calculated as EFI_SMM_SYSTEM_TABLE.NumberOfCpus – 1 (as described in the Tiano SMM CIS).
Dest The physical address of the destination data buffer.
Size The number of bytes to copy.

Description
This function copies Size bytes of data from the buffer at the linear address specified by Src to the buffer at the physical address specified by Dest, using the page tables from the CPU specified by CpuIndex. If the source crosses a page table boundary, this is handled correctly. If there is no valid page for some or all of the source data, EFI_DEVICE_ERROR is returned, in which case some of the data may have been copied.

Status Codes Returned

Status Code Description
EFI_SUCCESS The function completed successfully.
EFI_DATA_ERROR Some of all of linear addresses from Src to Src + Size – 1 had no valid page table entry.
EFI_INVALID_PARAMETER The CpuIndex specified is invalid.

Copyright (C) 2008 Phoenix Technologies Ltd. All Rights Reserved.

Personal tools