UEFI Framework - 9 [ Some Common EFI Functions]

Architectural Protocol
：DXE Driver 和 DXE Application 透過Archituctural Protocol跟Hardware做溝通，唯一的使用者是Core Services，也是唯一能在pre-boot時跟Hardware溝通的Protocol。

CPU Architectural Protoco：一個抽象化Processor的Protocol，裡面包含了Flushing Cache、Enable or Disable Interrupts等等

#define EFI_CPU_ARCH_PROTOCOL_GUID \
  { 0x26baccb1, 0x6f42, 0x11d4, {0xbc, 0xe7, 0x0, 0x80, 0xc7, 0x3c, 0x88, 0x81 } }

typedef struct _EFI_CPU_ARCH_PROTOCOL   EFI_CPU_ARCH_PROTOCOL;

///
/// The EFI_CPU_ARCH_PROTOCOL is used to abstract processor-specific functions from the DXE
/// Foundation. This includes flushing caches, enabling and disabling interrupts, hooking interrupt
/// vectors and exception vectors, reading internal processor timers, resetting the processor, and
/// determining the processor frequency.
///
struct _EFI_CPU_ARCH_PROTOCOL {
  EFI_CPU_FLUSH_DATA_CACHE            FlushDataCache; // Flush 一個範圍內的Processor's data cache
  EFI_CPU_ENABLE_INTERRUPT            EnableInterrupt;// Enable Interrupt (Raise TPL(),Restore TPL())
  EFI_CPU_DISABLE_INTERRUPT           DisableInterrupt;// Disable Interrupt (Raise TPL(),Restore TPL())
  EFI_CPU_GET_INTERRUPT_STATE         GetInterruptState;//得到Interrupt的status
  EFI_CPU_INIT                        Init;//透過external Hardware 產生Interrupt
  EFI_CPU_REGISTER_INTERRUPT_HANDLER  RegisterInterruptHandler;//綁定ISR至Handle
  EFI_CPU_GET_TIMER_VALUE             GetTimerValue;//Return 一個Processor內部timer的值
  EFI_CPU_SET_MEMORY_ATTRIBUTES       SetMemoryAttributes;//設定Memory region的attribute
  ///
  /// The number of timers that are available in a processor. The value in this 
  /// field is a constant that must not be modified after the CPU Architectural 
  /// Protocol is installed. All consumers must treat this as a read-only field.
  ///
  UINT32                              NumberOfTimers;//得到Processor內有效Timer的數量
  ///
  /// The size, in bytes, of the alignment required for DMA buffer allocations. 
  /// This is typically the size of the largest data cache line in the platform. 
  /// The value in this field is a constant that must not be modified after the 
  /// CPU Architectural Protocol is installed. All consumers must treat this as 
  /// a read-only field.  
  ///
  UINT32                              DmaBufferAlignment;//得到DMA 需要Alignment的Memory size，以Byte為單位
};

Real Time Clock Architectural Protocol：提供Service R/W RTC

Timer Architectural Protocol：提供Protocol可以控制Timer

///
/// This protocol provides the services to initialize a periodic timer 
/// interrupt, and to register a handler that is called each time the timer
/// interrupt fires.  It may also provide a service to adjust the rate of the
/// periodic timer interrupt.  When a timer interrupt occurs, the handler is 
/// passed the amount of time that has passed since the previous timer 
/// interrupt.
///
struct _EFI_TIMER_ARCH_PROTOCOL {
  EFI_TIMER_REGISTER_HANDLER          RegisterHandler; //Register Handle
  EFI_TIMER_SET_TIMER_PERIOD          SetTimerPeriod;
  EFI_TIMER_GET_TIMER_PERIOD          GetTimerPeriod;
  EFI_TIMER_GENERATE_SOFT_INTERRUPT   GenerateSoftInterrupt;//產生Interrupt 可以模擬Timer Interrupt被觸發的時後
};

Reset Architectural Protocol：產生Service用來Reseet Platform。必需是runtime DXE Driver產生出來的才行，且只能被DXE Foundation使用。

Boot Device Selection Architectural Protocol：能將DXE轉換到OS

///
/// Global ID for the BDS Architectural Protocol
///
#define EFI_BDS_ARCH_PROTOCOL_GUID \
  { 0x665E3FF6, 0x46CC, 0x11d4, {0x9A, 0x38, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0x4D } }

///
/// Declare forward reference for the BDS Architectural Protocol
///
typedef struct _EFI_BDS_ARCH_PROTOCOL   EFI_BDS_ARCH_PROTOCOL;

typedef
VOID
(EFIAPI *EFI_BDS_ENTRY)(
  IN EFI_BDS_ARCH_PROTOCOL  *This
  );

///
/// The EFI_BDS_ARCH_PROTOCOL transfers control from DXE to an operating 
/// system or a system utility.  If there are not enough drivers initialized 
/// when this protocol is used to access the required boot device(s), then 
/// this protocol should add drivers to the dispatch queue and return control 
/// back to the dispatcher.  Once the required boot devices are available, then 
/// the boot device can be used to load and invoke an OS or a system utility.
///
struct _EFI_BDS_ARCH_PROTOCOL {
  EFI_BDS_ENTRY Entry; //Entry不帶任何參數，會忽略return回來的值，如果這個呼叫有return的話，需要再次啟動Dispatch，如下圖所示
};

Variable Architectural Protocol：提供Service去Get or Set Environment Variable
```
GetVariable()
GetNextVariableName()
SetVariable()
```

Watchdog Timer Architectural Protocol：用來Program watchdog timer，也可以選擇要不要register Handle用來看watchdog timer 被觸發時。

///
/// Global ID for the Watchdog Timer Architectural Protocol
///
#define EFI_WATCHDOG_TIMER_ARCH_PROTOCOL_GUID \
  { 0x665E3FF5, 0x46CC, 0x11d4, {0x9A, 0x38, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0x4D } }

///
/// Declare forward reference for the Timer Architectural Protocol
///
typedef struct _EFI_WATCHDOG_TIMER_ARCH_PROTOCOL  EFI_WATCHDOG_TIMER_ARCH_PROTOCOL;


///
/// This protocol provides the services required to implement the Boot Service 
/// SetWatchdogTimer().  It provides a service to set the amount of time to wait 
/// before firing the watchdog timer, and it also provides a service to register 
/// a handler that is invoked when the watchdog timer fires.  This protocol can 
/// implement the watchdog timer by using the event and timer Boot Services, or 
/// it can make use of custom hardware.  When the watchdog timer fires, control 
/// will be passed to a handler if one has been registered.  If no handler has 
/// been registered, or the registered handler returns, then the system will be 
/// reset by calling the Runtime Service ResetSystem().
///
struct _EFI_WATCHDOG_TIMER_ARCH_PROTOCOL {
  EFI_WATCHDOG_TIMER_REGISTER_HANDLER  RegisterHandler;//當watchdog timer的Handle，Register後在觸發後可控制
  EFI_WATCHDOG_TIMER_SET_TIMER_PERIOD  SetTimerPeriod;
  EFI_WATCHDOG_TIMER_GET_TIMER_PERIOD  GetTimerPeriod;
};

PCI Protocol

：與PCI有關的Protocol

#define EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GUID \
  { \
    0x2f707ebb, 0x4a1a, 0x11d4, {0x9a, 0x38, 0x00, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \
  }

typedef struct _EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL;

///
/// Provides the basic Memory, I/O, PCI configuration, and DMA interfaces that are 
/// used to abstract accesses to PCI controllers behind a PCI Root Bridge Controller. 
///
struct _EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL {
  ///
  /// The EFI_HANDLE of the PCI Host Bridge of which this PCI Root Bridge is a member.
  ///
  EFI_HANDLE                                      ParentHandle;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_POLL_IO_MEM     PollMem;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_POLL_IO_MEM     PollIo;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS          Mem;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS          Io;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS          Pci;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_COPY_MEM        CopyMem;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_MAP             Map;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_UNMAP           Unmap;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ALLOCATE_BUFFER AllocateBuffer;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_FREE_BUFFER     FreeBuffer;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_FLUSH           Flush;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GET_ATTRIBUTES  GetAttributes;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_SET_ATTRIBUTES  SetAttributes;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_CONFIGURATION   Configuration;
  
  ///
  /// The segment number that this PCI root bridge resides.
  ///
  UINT32                                          SegmentNumber;
};

Block I/O

：抽象化Mass Storage Device，在Boot Service Environment 時能直接存取它們，不需要再有特別的knowledge(ex:Disk or Controller)

#define EFI_BLOCK_IO_PROTOCOL_GUID \
  { \
    0x964e5b21, 0x6459, 0x11d2, {0x8e, 0x39, 0x0, 0xa0, 0xc9, 0x69, 0x72, 0x3b } \
  }

typedef struct _EFI_BLOCK_IO_PROTOCOL  EFI_BLOCK_IO_PROTOCOL;


///
///  This protocol provides control over block devices.
///
struct _EFI_BLOCK_IO_PROTOCOL {
  ///
  /// The revision to which the block IO interface adheres. All future
  /// revisions must be backwards compatible. If a future version is not
  /// back wards compatible, it is not the same GUID.
  ///
  UINT64              Revision; 
  ///
  /// Pointer to the EFI_BLOCK_IO_MEDIA data for this device.
  ///
  EFI_BLOCK_IO_MEDIA  *Media;

  EFI_BLOCK_RESET     Reset;
  EFI_BLOCK_READ      ReadBlocks;
  EFI_BLOCK_WRITE     WriteBlocks;
  EFI_BLOCK_FLUSH     FlushBlocks;

};


/**
  Block IO read only mode data and updated only via members of BlockIO
**/
typedef struct {
  ///
  /// The curent media Id. If the media changes, this value is changed.
  ///
  UINT32  MediaId;         
   
  ///
  /// TRUE if the media is removable; otherwise, FALSE.
  ///    
  BOOLEAN RemovableMedia;
  
  ///
  /// TRUE if there is a media currently present in the device;
  /// othersise, FALSE. THis field shows the media present status
  /// as of the most recent ReadBlocks() or WriteBlocks() call.  
  ///
  BOOLEAN MediaPresent;

  ///
  /// TRUE if LBA 0 is the first block of a partition; otherwise
  /// FALSE. For media with only one partition this would be TRUE.
  ///
  BOOLEAN LogicalPartition;
  
  ///
  /// TRUE if the media is marked read-only otherwise, FALSE.
  /// This field shows the read-only status as of the most recent WriteBlocks () call.
  ///
  BOOLEAN ReadOnly;
  
  ///
  /// TRUE if the WriteBlock () function caches write data.
  ///
  BOOLEAN WriteCaching; 
  
  ///
  /// The intrinsic block size of the device. If the media changes, then
  /// this field is updated.  
  ///
  UINT32  BlockSize; 
  
  ///
  /// Supplies the alignment requirement for any buffer to read or write block(s).
  ///
  UINT32  IoAlign; 
  
  ///
  /// The last logical block address on the device.
  /// If the media changes, then this field is updated. 
  ///
  EFI_LBA LastBlock; 

  ///
  /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to
  /// EFI_BLOCK_IO_PROTOCOL_REVISION2. Returns the first LBA is aligned to 
  /// a physical block boundary. 
  ///
  EFI_LBA LowestAlignedLba;

  ///
  /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to
  /// EFI_BLOCK_IO_PROTOCOL_REVISION2. Returns the number of logical blocks 
  /// per physical block.
  ///
  UINT32 LogicalBlocksPerPhysicalBlock;
} EFI_BLOCK_IO_MEDIA;

Simple File System

：允許code跑在EFI Boot Service environment，用來開啟Device Volume並回傳File Handle。EFI_FILE_PROTOCOL是用來對File做open r/w的

#define EFI_SIMPLE_FILE_SYSTEM_PROTOCOL_GUID \
  { \
    0x964e5b22, 0x6459, 0x11d2, {0x8e, 0x39, 0x0, 0xa0, 0xc9, 0x69, 0x72, 0x3b } \
  }

typedef struct _EFI_SIMPLE_FILE_SYSTEM_PROTOCOL  EFI_SIMPLE_FILE_SYSTEM_PROTOCOL;


///
/// Revision defined in EFI1.1
/// 
#define EFI_FILE_IO_INTERFACE_REVISION  EFI_SIMPLE_FILE_SYSTEM_PROTOCOL_REVISION

struct _EFI_SIMPLE_FILE_SYSTEM_PROTOCOL {
  ///
  /// The version of the EFI_SIMPLE_FILE_SYSTEM_PROTOCOL. The version
  /// specified by this specification is 0x00010000. All future revisions
  /// must be backwards compatible.
  ///
  UINT64                                      Revision;
  EFI_SIMPLE_FILE_SYSTEM_PROTOCOL_OPEN_VOLUME OpenVolume;
};


///
/// The EFI_FILE_PROTOCOL provides file IO access to supported file systems.
/// An EFI_FILE_PROTOCOL provides access to a file's or directory's contents, 
/// and is also a reference to a location in the directory tree of the file system 
/// in which the file resides. With any given file handle, other files may be opened 
/// relative to this file's location, yielding new file handles.
///
struct _EFI_FILE_PROTOCOL {
  ///
  /// The version of the EFI_FILE_PROTOCOL interface. The version specified 
  /// by this specification is 0x00010000. Future versions are required 
  /// to be backward compatible to version 1.0.
  ///
  UINT64                Revision;
  EFI_FILE_OPEN         Open;
  EFI_FILE_CLOSE        Close;
  EFI_FILE_DELETE       Delete;
  EFI_FILE_READ         Read;
  EFI_FILE_WRITE        Write;
  EFI_FILE_GET_POSITION GetPosition;
  EFI_FILE_SET_POSITION SetPosition;
  EFI_FILE_GET_INFO     GetInfo;
  EFI_FILE_SET_INFO     SetInfo;
  EFI_FILE_FLUSH        Flush;
};

William的記事

搜尋此網誌