American Megatrends, Inc.

CmosManager

Copyright

Release Notes

© American Megatrends, Inc.


Copyright

American Megatrends, Inc.
5555 Oakbrook Parkway
Suite 200
Norcross, GA 30093 (USA)

Copyright (c) 1999-2011 American Megatrends, Inc. All Rights Reserved.

This publication contains proprietary information, which is protected by copyright. No part of this publication may be reproduced, transcribed, stored in a retrieval system, translated into any language or computer language, or transmitted in any form whatsoever without the prior written consent of the publisher, American Megatrends, Inc.

American Megatrends, Inc. retains the right to update, change, modify this publication at any time, without notice.

For Additional Information

Call American Megatrends BIOS Sales Department at 1-800-828-9264 for additional information.

Limitations of Liability

In no event shall American Megatrends be held liable for any loss, expenses, or damages of any kind whatsoever, whether direct, indirect, incidental, or consequential, arising from the design or use of this product or the support materials provided with the product.

Limited Warranty

No warranties are made, either expressed or implied, with regard to the contents of this work, its merchantability, or fitness for a particular use. American Megatrends assumes no responsibility for errors and omissions or for the uses made of the material contained herein or reader decisions based on such use.

Trademark and Copyright Acknowledgments

All product names used in this publication are for identification purposes only and are trademarks of their respective Companies.


Release Notes - NDA Required

Component Information:
Component Title: CMOS Manager
Component Reference Name: CmosManager
Component Type: eModule
Release Date: 2012-01-27
Source Control Label: 4.6.3_CMOSMGR_11_BETA12
Source Control Location: SS: $/Alaska;$/Alaska/SOURCE/Modules/CMOS Manager;

Dependencies
N0NE
Non-Compiled BIN and LIB File(s) within this Component:
N0NE
Component Description:
The CMOS Manager module provides a "bit"-level, general purpose, API to access all physical non-volatile RAM locations. These NVRAM locations are herein referred to as CMOS locations (or physical CMOS, or CMOS registers) and are in no way related to the NVRAM provided by any flash memory technology. In order to disambiguate CMOS addresses and provide protection from unauthorized writing, CMOS Manager enforces several constraints and policies, which are essentially transparent to the user. CMOS Manager also provides error detection and recovery mechanisms, and provides a default recovery policy. For additional, information and implementation notes please follow these links:
ModulePart/Filename | Path/Description
CMOS Manager | Core\em\CmosManager
CmosManager.cif | Main module CIF
CmosManager.sdl | module part CIF
CmosManager.chm | module's help file
CMOS Board | Core\em\CmosManager
CmosManagerBoard.cif | board module part
CmosBoard.sdl | platform porting AMISDL build parameters
CmosBoard.ssp | platform-specific internal CMOS Tokens
CmosBoard.c | default porting functions
CmosBoard.h | default porting functions' prototypes
CmosSetup.sd | setup page definition file
CmosSetup.uni | setup page strings
CMOS Messages | Core\em\CmosManager
CmosManagerMessages.cif | boot messages source
CmosMessages.sdl | boot messages AMDSDL build parameters
CmosMessages.mak | boot messages make file
CmosMessages.c | boot messages source
CmosMessages.uni | boot messages strings
CMOS SEC | Core\em\CmosManager
CmosManagerSec.cif | SEC phase module part
CmosManagerSec.asm | SEC phase code
CMOS PEI | Core\em\CmosManager
CmosManagerPei.cif | PEI phase modules part
CmosManagerPei.c | PEI phase entrypoint
CmosManagerPei.h | PEI phase includes files, types and constants
CMOS DXE | Core\em\CmosManager
CmosManagerDxe.cif | DXE phase module part
CmosManagerDxe.c | DXE phase entry point
CmosManagerDxe.h | DXE phase include files, types and constants
CMOS SMM | Core\em\CmosManager
CmosManagerSmm.cif | SMM module part
CmosManagerSmm.c | SMM entry point
CmosManagerSmm.h | SMM include files, types and constants
CmosManagerSmm.dxs | SMM dependency expression
CmosAccess.asl | ASL source for CMOS access
CMOS Core | Core\em\CmosManager
CmosManagerCore.cif | core module part
CMOS Interfaces | Include
CmosManagerInterfaces.cif | CMOS Manager interfaces module part
CmosAccess.h | PPI and Protocol interface declarations
CmosAccess32.inc | includes for CMOS access in 32-bit assembly code
CmosAccessSec.inc | include for CMOS access in SEC phase code
CMOS Source | Core\em\CmosManager
CmosManagerSource.cif | core source module part
CmosManager.c | module management initialization subsystem source
CmosAccess.c | CMOS access subsystem source
CmosTables.c | AMISSP2.exe tables "glue" source
CmosManagerHob.c | HOB related source
CMOS Includes | Core\em\CmosManager
CmosManagerIncludes.cif | internal includes
CmosManager.h | internal manager interface types and constants
CmosManagerHob.h | HOB related types and constants
CmosTypes.h | CMOS Manager internal types
CMOS Build | Core\em\CmosManager
CmosManagerBuild.cif | BUID tool module part
CmosManager.mak | main module make file
Template.ssp | AMISSP2.exe SSP file

AMI Build Tools:
    Tools Label: 4.5.5_TOOLS_36  Dated: 2011-06
    Visual eBios: RSS.5.70.0171   Dated: 2010-10-04
    Compiler Tool(s): Microsoft’s Windows Driver Kit (WDK) Ver. 7600.16385.1
Features added/changed in this label:
  1.  Support for setup customization as defined by the Aptio Setup
      Customization Guide.

  2.  Support for ASL CMOS access method

      I.e., use \CMOS.ACCE(1, 0x1232, BYTE) to read the '
      CMOS_MGR_DEFAULTS_LOADED CMOS token, where
      CMOS_MGR_DEFAULTS_LOADED = 0x1232.
EIPs resolved and files changed:
--------------------------------------------------------------------------
[TAG]         EIP56197
[Category]    Spec Update
[Severity]    Normal
[Description] CMOS Manager Support in Runtime Code
[Files]       CmosManager.sdl
              CmosSetup.uni
              CmosMessages.uni
              CmosManagerSmm.cif
              CmosAccess.h
              CmosManagerSmm.c
              CmosAccess.asl

--------------------------------------------------------------------------
[TAG]         EIP75889
[Category]    Spec Update
[Severity]    Normal
[Description] Support Setup Customization
[Files]       CmosManager.sdl
              CmosSetup.sd
              CmosSetup.uni
              CmosMessages.uni
Known issues and limitations:
    None
Tests and validation:
    This module is tested on the multiple Intel and AMD platforms.
Release History:
See Revision History

© American Megatrends Inc.


eModule Release Notes

Aptio 4.x Component Release Notes

Contents

Component Information

Component Description

Fixes

New Features in Latest Release

Errata & Known Issues

Files

Future Releases

Component Information

Component Name | CMOS Manager
Component Type | eModule
Release Date | June 15th, 2010
Source Control Label | 4.6.3_CMOSMGR_11_BETA11
Source Control Location | Alaska/SOURCE/Modules/CMOS Manager

Component Description

The CMOS Manager module provides a "bit"-level, general purpose, API to access all physical non-volatile RAM locations. These NVRAM locations are herein referred to as CMOS locations (or physical CMOS, or CMOS registers) and are in no way related to the NVRAM provided by any flash memory technology. In order to disambiguate CMOS addresses and provide protection from unauthorized writing, CMOS Manager enforces several constraints and policies, which are essentially transparent to the user. CMOS Manager also provides error detection and recovery mechanisms, and provides a default recovery policy. For additional, information and implementation notes please follow these links:
  • Terminology
  • CMOS Access Throughout the Boot Phases
  • Recovery and First Boot Mechanisms/Policies
  • Usage Examples
    • Protocol/PPI Usage in C-Source Code
    • CMOS Access in SEC-phase Assembly Source Code
    • CMOS Access in PEI-phase Assembly Source Code
    • CMOS-Based API Pointer in C-Source Code
  • General Implementation Notes
Back to Contents

Fixes

  • N/A
Back to Contents

Latest Release Features

The list below provides a overview of the changes in label 4.6.3_CMOSMGR_11. For a more detailed listing of the latest changes, please read 4.6.3_CMOSMGR_11_BETA11.htm.

  • Added Setup page support. (Requires TSE label 4.6.2_TSE_2_01_1204 or later.)
  • Added support for CMOS Manager power-on messages. (Requires TSE label 4.6.2_TSE_2_01_1204 or later.)
  • Support for latest AmiSsp2.exe, which natively supports "unmanaged" token declarations.
  • A new porting function is added to distinguish between a dead battery and usable CMOS hardware. (For some systems the CMOS hardware is usable even if the battery is dead.)
  • Support for "unmanaged" locations, where a default value is never written and the location is not included in the checksum.
  • CMOS recovery initiated in PEI by default, and bad checksum bit is not cleared until DXE phase.
  • Additional recovery configuration settings/tokens are provided.
  • Added SMM mode support for the CMOS Access interface.
  • Fixed issue in Template.ssp where TokenInclude must be an empty string.
  • Fixed jump macro issues related to projects that use PE32 SEC binaries.
  • Fixed build issue related to CSP library name conflict with ReadCmosToken and WriteCmosToken.
  • Fixed build issue related to LAST_ADDRESS and SEC object files requiring /coff flag for CPU revisions that require PE32 SEC object files.
  • now supports access to all physical CMOS locations, including the real-time clock (RTC) region.
  • no longer requires the RomUpdate.exe utility.
  • no longer requires AmiSsp2.exe to be included with the module. (Use the latest label of AmiSsp2.exe in AMI tools.)
  • to ensure the CMOS access service is seamlessly available to all modules, the CMOS Manager's module entry points are executed via INIT list (PeiCoreInitialize, PeiCoreMemoryInstalled and DxeCoreInitialize).
    • It is no longer a requirement to place a dependency on EFI_CMOS_DATA_HOB_INSTALLED_GUID when a dependency on EFI_PEI_PERMANENT_MEMORY_INSTALLED_PPI is required.
  • default CMOS values are loaded in PEI (prior to the PEI dispatch loop), and no system reset is initiated after loading the default values.
    • The CMOS Manager no longer uses the ResetSystem runtime service.
  • for real-time clock (RTC) access, GetTime and SetTime services are provided, as well as support for direct reading/writing of RTC registers.
  • replacement of several default functions is supported by defining their replacement in the CSP library and using certain SDL Tokens and eLinks to link them into the CMOS Manager module.
Back to Contents

Errata & Known Issues

  • For power-on messages and setup page support, TSE label 4.6.2_TSE_2_01_1204 or later is required.
  • Please get the latest version of AmiSsp2.exe, which natively supports unmanaged CMOS tokens. (See Template.ssp for example declarations for unmanaged tokens.) (Aside from the declaration, there is no difference in usage between an unmanaged token and any other token.)
  • Patched support (from previous release) for unmanaged CMOS locations is no longer available. Please update token declarations to include the Managed = NO field if an unmanaged location is required. (CmosBoad.c will need to be updated if this file is private for the purposes of patched unmanaged locations.)
Back to Contents

Files

Source code in the CMOS Manager module is organized into to six general categories, which are the module parts: CMOS Core, CMOS Board, CMOS SEC, CMOS PEI and CMOS DXE and CMOS SMM.
  1. The CMOS Core module part contains the code that implements the bulk of the CMOS Manager module. Generally speaking, this code is common in all boot phases and contains both intenal and external interface implementation code.
  2. The CMOS Board module part contains code that may require porting work, depending upon platform-specific CMOS access requirements. Setup-related code is also contained in this module part.
  3. The CMOS SEC module part contains code that provides CMOS access support in the SEC phase. This stand-alone code is linked into Startup32.ffs.
  4. The CMOS PEI module part contains code that is required to be executed in the PEI phase to perform early CMOS Manager configuration and error detection tasks as well as initialize and install the CMOS Access PPI.
  5. The CMOS DXE module part contains code that is required to be executed in the DXE phase, such as initialize/install the CMOS Access Protocol.
  6. The CMOS SMM module part contains code to perform tasks required to provide SMM CMOS Access support, such as initialize/install the SMM CMOS Access Protocol. (The executable code associated with the SMM CMOS Access Protocol resides in SMRAM.)
Filename | Description
CmosManager.sdl | This file contains SDL Token and SDL eLink definitions to facilitate core-level configuration settings. (Typically, this file in not modified.)

CMOS Core

This section provides a brief summary of the files that compose the CMOS Core module part. These files are organized into additional module sub-parts in order to provide logical organization of the source code. CMOS Core code is classified as CMOS Interfaces, CMOS Source, CMOS Includes, CMOS Build and CMOS Tools.

CMOS Interfaces

The CMOS Interfaces sub-part contains the prototypes, macros and constant declarations, including the EFI_CMOS_ACCESS_INTERFACE, which constitute the published/installed external interface to CMOS Manager's services.
Filename | Description
CmosAccess.h | This header file contains the prototype for EFI_CMOS_ACCESS_INTERFACE, which is the published/installed external interface to CMOS Manager's services. Additional macros and types related to using this interface are also defined in this file.
CmosAccess32.inc | This file contains macros, constants and procedures to support the CMOS Access interface from assembly source code in the PEI phase.
CmosAccessSec.inc | This file contains macros and constants to support CMOS Access from assembly source code in the SEC phase.

CMOS Source

The CMOS Source sub-part contains the code to implement CMOS Managers's internal and external interfaces as well as the core subsystems.
Filename | Description
CmosManager.c | This file contains code that related to the Manager's internal interface management services, such as allocating/initializing data structures and maintaining state information. Generally speaking, no hardware access code and no external interface code is contained in this file.
CmosAccess.c | This file contains code that implements the CMOS Access Interface (PPI/Protocol). Generally speaking, this is the low-level code that interacts with the physical CMOS hardware.
CmosTables.c | This file contains definitions for global data tables that will be initialized from AmiSsp2.exe output files during the build process.
CmosManagerHob.c | This file contains code related to publishing the HOB that will pass the global data tables and internal CMOS Manager state information from the PEI phase to the DXE phase.

CMOS Includes

The CMOS Includes sub-part is a general repository for the CMOS Manager's header files, which contain prototypes for data structures as well as constant definitions. The code within these header files is organized according the requirements of CMOS Manager's internal subsystems.
Filename | Description
CmosManager.h | This file contains the prototype for the Manager's internal interface. This file exports a single function that returns a pointer to a new allocated/initialized internal Manager interface, which is not to be part of any published/installed external interface.
CmosManagerHob.h | This file contains the prototype and constant definitions for a HOB that will pass the global data tables and internal state information from the PEI phase to the DXE phase.
CmosTypes.h | This file contains the prototypes and constant definitions that are module-scope accessible. These types may be used within any of the Manager's general subsystems or Core subsystems.

CMOS Build

The CMOS Build sub-part contains code related to generating the module's binary files, which will be linked into the final firmware device ROM image.
Filename | Description
CmosManager.mak | This file contains Nmake targets and build environment variable definitions used to control the generation of the required SSP output files and the module's binary files.
Template.ssp | This file contains low-level configuration information that will be used by AmiSsp2.exe during the SSP output file generation build phase.

CMOS Tools

Currently, there are no CMOS Manager-specific tools. However, the following discussion explains the input/output for AmiSsp2.exe, which is an external tool in the AMI tools directory. (AmiSsp2.exe is exclusively used by CMOS Manager.)

Filename Description
AmiSsp2.exe This is a time-tested, quality-assured AMI utility designed to parse SSP files, allocate/manage CMOS register location assignments and generate required output files to be used during the build process. This utility was originally developed in 1995 for legacy AMI BIOS projects (currently maintained and used in AMI Core8 projects) and recently adapted for Aptio projects to generate C-header files and additional assembly source information. (The core implementation of AmiSsp2.exe is unchanged and only output files and file formats have been modified for Aptio.) The following table briefly explains the output files generated by (or related to) AmiSsp2.exe.

Output File | Description
SspTokens.h | This file contains CMOS Token definitions and is included by CMOS Client modules to access CMOS locations using CMOS Manager's CMOS Access Interface. (This is a new AmiSsp2.exe output file.)
SspData.h | This file contains constant and macro definitions used to initialize the global tables used by CMOS Manager. (This is a new AmiSsp2.exe output file.)
SspFilesList.txt | This file is generated by Nmake and contains the list of CMOS Token declaration files (SSP files) to be processed by AmiSsp2.exe.
Ssp.rep | This file contains a textual summary of the CMOS allocation map. The content of this file has not been modified for Aptio, which means some information here is extraneous. (The most notable extraneous information is the Failsafe Value, which is not used in Aptio.)
TokenEqu.equ | This file is the assembly language equivalent to SspTokens.h. The content of this file has additional information for Aptio, but is largely identical to the original AmiSsp2.exe output.
TokTbl2.asm | This file is extraneous and may be used or depreciated for Aptio in future CMOS Manager implementations.

CMOS Board

This module part contains code related to platform-specific customization of CMOS Manager.
Filename | Description
CmosBoard.sdl | This file contains SDL Tokens and SDL eLinks that are used for platform-specific porting.
CmosBoard.ssp | This file contains a list of pre-defined CMOS Tokens for known CMOS locations used by CMOS Manager.
CmosBoard.c | This file contains default functions for tasks that may be considered platform-specific.
CmosBoard.h | This file contains prototypes for exporting the default functions to CMOS Core.
CmosSetup.sd | This file contains setup page definition information.
CmosSetup.uni | This file contains the setup page-related string definitions.

CMOS Messages

The CMOS Messages sub-part contains the code required to support power-on messages. These messages will be displayed when CMOS Manager needs to inform the user that some critical action was taken (i.e., default CMOS values were loaded) or a serious problem was discovered (i.e., bad battery) during the boot process.
Filename | Description
CmosMessages.sdl | This file contains information used during the build process for linking and building the appropriate setup database information.
CmosMessages.mak | This file contains build targets for bulding the required binaries to support power-on messages.
CmosMessages.c | This file contains the source code to display power-on messages.
CmosMessages.uni | This file contains string declarations to support power-on messages.

CMOS SEC

This section describes the files that comprise CMOS Manager's SEC phase-specific code.
Filename | Description
CmosManagerSec.asm | This file contains code to initialize the CMOS Manager for the SEC phase.

CMOS PEI

This section describes the files that comprise CMOS Manager's PEI phase-specific support code.
Filename | Description
CmosManagerPei.c | This file contains code to initialize the CMOS Manager for the PEI phase and install the CMOS Access PPI.
CmosManagerPei.h | This file contains declarations required for the CMOS Manager PEI phase code.

CMOS DXE

This section describes the files that comprise CMOS Manager's DXE phase-specific support code.
Filename | Description
CmosManagerDxe.c | This file contains code to initialize the CMOS Manager for the DXE phase and install the CMOS Access Protocol.
CmosManagerDxe.h | This file contains declarations required for the CMOS Manager DXE phase code.

CMOS SMM

This section describes the files that comprise CMOS Manager's support code for SMM, which provides a mechanism for Runtime-phase access to CMOS.
Filename | Description
CmosManagerSmm.c | This file contains code to initialize the CMOS Manager for the Runtime phase and install the SMM CMOS Access Protocol.
CmosManagerSmm.h | This file contains declarations required for the CMOS Manager Runtime phase code.
CmosManagerSmm.dxs | This file contains the dependency expression for CMOS Manager's SMM DXE Driver.
Back to Contents

Future Releases

This section contains information about current development and features expected to be in future releases of CMOS Manager.
  • No information about future releases is available at this time.
Back to Contents

© American Megatrends Inc.


CmosManager

AMIBIOS Document References

Usage Examples

BootFlowUsageDiagram.htm

UsageExamples.htm

Built on 11:30:59 01/27/12


Boot Flow Usage Diagram

CMOS Access Throughout the Boot Phases

Usage During the Various Boot Phases

The following diagram depicts the CMOS Manager's tasks through the various boot phase environments and how the CMOS Access PPI/Protocol and CMOS-based API pointer are used by client modules.


Usage Examples

Code Examples

This document contains general notes for using CMOS Manager's PPI, Protocol and CMOS-based API pointer in a Client module. Also, several examples are provided. It is very important to understand the issues discussed here when implementing code that uses CMOS Manager’s services.

General Usage Notes

The following is a list of general usage notes and issues to consider when using CMOS Manager’s services.

  • CMOS accesses in the SEC phase are assumed to be read-only and limited to the standard CMOS range (0xf to 0x7f).
    • There is no recovery mechanism for the SEC phase.
  • To ensure CMOS memory integrity/coherency and to ensure predictable reads/writes, all CMOS accesses should be made as follows:
    • SEC phase -- use the CmosReadWrite procedure
    • PEI Phase -- use the CMOS Access PPI or CMOS-based API Pointer
    • DXE phase -- use the CMOS Access Protocol
    • Runtime phase -- use the SMRAM-based CMOS Access protocol
  • Code that uses the CMOS-based API pointer must check the results of the operation to make sure it was successful.
    • If the battery is bad, an error will be returned.
  • TokenEqu.equ and SspTokens.h (in the build directory) define additional constants for each CMOS token.
    • These constants provide extra information about the Token’s value.
    • SspTokens.h is automatically included with CmosAccess.h.
    • TokenEqu.equ is automatically included with CmosAccessSec.inc and CmosAccess32.inc.

Client Code Organization

If CMOS is accessed multiple times within a Client module's code, it may be beneficial to implement a CMOS Access interface wrapper function. The CMOS Manager provides prototypes and macros (in CmosAccess.h) to simplify the implementing of a wrapper function to make client module code easier to understand, use, debug and/or maintain. The following sections provide examples for implementing client wrapper functions.

Protocol/PPI Usage in C-Source Code

The CMOS access semantics are nearly identical for Protocol and PPI. For example, in the PEI phase, you will simply locate a PPI instead of a Protocol. The following is an example of a DXE phase wrapper function for reading or writing a CMOS Token value.

#include <CmosAccess.h>

...

// example CMOS Access interface wrapper
EFI_STATUS CmosAccess(
    UINT16            CmosToken,
    CMOS_ACCESS_TYPE  AccessType, // typedef in CmosAccess.h
    UINT8             *Value )
{
    static EFI_CMOS_ACCESS_INTERFACE *Cmos = NULL;
    EFI_STATUS Status = EFI_SUCCESS;    if (Cmos == NULL)
      LOCATE_CMOS_ACCESS_PROTOCOL(Status, Cmos)    if (!EFI_ERROR(Status)){
        if (AccessType == ReadType)
            return Cmos->Read( Cmos, CmosToken, Value );
        else
            return Cmos->Write( Cmos, CmosToken, *Value );
    }
    return Status;
}// example call
VOID MyFunction( VOID ){
    UINT8 CmosValue;

    // read a particular token
    if (EFI_ERROR(CmosAccess( CMOS_MY_TOKEN, ReadType, &CmosValue))
        HandleCmosError(ReadType, CMOS_MY_TOKEN);

    ...

    // increment and write back
    ++CmosValue;
    if (EFI_ERROR(CmosAccess( CMOS_MY_TOKEN, WriteType, &CmosValue))
        HandleCmosError(WriteType, CMOS_MY_TOKEN);
}

Notes:

  • The LOCATE_CMOS_ACCESS_PROTOCOL and LOCATE_CMOS_ACCESS_PPI macros simplify locating the CMOS Access Interface Protocol/PPI.

  • Using static local variables can have unpredictable results in code that executes before permanent memory is installed in PEI.

  • HandleCmosError() in the example above is a client-supplied error handling routine given only for example purposes.

CMOS-Based API Pointer in C-Source Code

While the LocatePpi() function provided by the PEI Services table is strongly recommended to be the ONLY means of obtaining a pointer to the CMOS Access interface during the PEI phase, there may be portions of code within a particular module where the PEI Services Table is not available. In this case, the Access interface pointer may be obtained directly from a predefined location in standard CMOS (in the range 0xf to 0x7f).

  • The main caveat in using the CMOS-based API pointer is for the case when the battery is bad. In this case, there is no way to access the API pointer, which means the Optimal Defaults Table is not available for default values and for writing CMOS values as a temporary buffer. Generally, it should be relatively simple to deal with a bad battery, as an identifiable error code is returned upon battery failure and the default value is readily available as a constant in TokenEqu.equ and SspTokens.h.

The following is an example of using the CMOS-based API pointer in C-source code.

#include <CmosAccess.h>
...
// example CMOS Access interface API pointer wrapper
EFI_STATUS CmosAccess (
    UINT16            CmosToken,
    CMOS_ACCESS_TYPE  AccessType, // typedef in CmosAccess.h
    UINT8             *Value )
{
    EFI_CMOS_ACCESS_INTERFACE *Cmos;
    LOCATE_CMOS_ACCESS_API_POINTER( Cmos );
    if (Cmos == NULL)
        return EFI_UNSUPPORTED;
    if (AccessType == ReadType)
        return Cmos->Read( Cmos, CmosToken, Value );
    else
        return Cmos->Write( Cmos, CmosToken, *Value );
}
// example call
VOID MyFunction( VOID ){
    UINT8 CmosValue;
    if (EFI_ERROR(CmosAccess( CMOS_MY_TOKEN, ReadType, &CmosValue)))
        CmosValue = CMOS_MY_TOKEN_OPT;
}

Notes:

  • When using the LOCATE_CMOS_ACCESS_API_POINTER , the EFI_CMOS_ACCESS_INTERFACE pointer will be initialized to NULL if the battery is dead.

  • The CMOS-based API pointer is not valid in DXE.

CMOS Access in SEC-phase Assembly Source Code

In the SEC phase, CMOS Manager defines a public procedure named CmosReadWrite. All procedures in the STARTUP_SEG (SEC) segment can use this procedure by first including CmosAccessSec.inc. The following is an example of calling the CmosReadWrite procedure from an SEC procedure.

include CmosAccessSec.inc
...
MY_VALUE EQU 0FFH  ; byte value to write to CMOS
SEC_MySecProcedure PROC PUBLIC
        mov dl, CMOS_WRITE_ACCESS
        mov dh, MY_VALUE
        mov ax, CMOS_MY_TOKEN
        jmp_edi CmosReadWrite
        jnc @F
        .if (ax == CMOS_BATTERY_ERR)
            mov al, CMOS_MY_TOKEN_OPT
        .elseif (ax == CMOS_OVERFLOW_ERR)
            ; attempted to write to
            ; another token's bits
        .else
            ; invalid token value
        .endif
@@:
SEC_MySecProcedure ENDP

Notes:

  • For convenience, two macros (jmp_edi and jmp_edx) are defined in the CmosAccessSec.inc file for the purpose of implementing a register-based jump to/from algorithm.

  • CmosReadWrite procedure inputs are registers DL, DH and AX.

    • DL contains the access type flag: CMOS_WRITE_ACCESS or CMOS_READ_ACCESS.

    • DH contains the value to write (for write accesses).

    • AX contains the token name for the CMOS location to be accessed.

  • Upon unsuccessful return from CmosReadWrite, the carry flag will be set and register AX will contain an error code: CMOS_BATTERY_ERR, CMOS_OVERFLOW_ERR or CMOS_BITSIZE_ERR.

  • Upon successful return from CmosReadWrite (carry flag is NOT set), and on a read access, register AL will contain the byte value of the CMOS location.

  • CmosAccessSec.inc provides the necessary extern declaration for the CMOS Manager's CmosReadWrite procedure.

CMOS Access in PEI-phase Assembly Source Code

The recommended algorithm for CMOS access in PEI-phase assembly source code is to directly use the CMOS Access PPI pointer. The following are a couple of examples of using the Access PPI-related assembly macros, where the first example is the preferred method.

  • For cases where direct usage of the PPI cannot be implemented or the PEI Services table pointer is not available, the CMOS Manager provides alternative access macros in CmosAccess32.inc, which utilize the CMOS-based API pointer.

Preferred Method: CMOS Access PPI

include CmosAccess32.inc
...
;-------------------------------------------------------------------
; Example: Directly call CMOS Access PPI using the READ_CMOS_PPI and
;          WRITE_CMOS_PPI macros.
; Input:
;        Cmos – pointer to the PPI
;        AccessType – either CMOS_READ_ACCESS or CMOS_WRITE_ACCESS
;        Token – valid token as defined in TokenEqu.equ
;        ValuePtr – address of value to read/or write
; Output:
;        EAX – EFI_STATUS
;-------------------------------------------------------------------

CmosPpiWrapper PROTO NEAR32 C,  Cmos:PTR EFI_CMOS_ACCESS_INTERFACE,
                                AccessType:BYTE,
                                Token:WORD,
                                ValuePtr:BYTE PTR
CmosPpiWrapper PROC  NEAR32 C,  Cmos:PTR EFI_CMOS_ACCESS_INTERFACE,
                                AccessType:BYTE,
                                Token:WORD,
                                ValuePtr:BYTE PTR
    mov  al, AccessType
    .if (al == CMOS_READ_ACCESS)
        READ_CMOS_PPI   Cmos, Token, ValuePtr
        .if (eax != 0)
            jmp CmosPpiWrapperExit
        .endif
    .else
        mov eax, ValuePtr
        WRITE_CMOS_PPI  Cmos, Token, BYTE PTR [eax]
    .endif
CmosPpiWrapperExit:
        ret
CmosPpiWrapper	ENDP

;-------------------------------------------------------------------
; example call (CMOS Access interface pointer is passed in)
;-------------------------------------------------------------------

MyFunction  PROC    NEAR32 C,   Cmos:PTR EFI_CMOS_ACCESS_INTERFACE
    LOCAL Value:BYTE, ValuePtr:PTR BYTE

    lea eax, Value
    mov ValuePtr, eax
    INVOKE CmosPpiWrapper, Cmos, CMOS_READ_ACCESS, CMOS_MY_TOKEN, ValuePtr
    .if (eax != 0)
        jmp CmosAccessPpiExit
    .endif

    inc Value
    INVOKE CmosPpiWrapper, Cmos, CMOS_WRITE_ACCESS, CMOS_MY_TOKEN, ValuePtr
MyFunction  ENDP

Alternative Method: CMOS-Based API Pointer

include CmosAccess32.inc
...
;-------------------------------------------------------------------
; example: CMOS Access interface call via CMOS-based API pointer
;          using READ_CMOS_TOKEN/WRITE_CMOS_TOKEN
; Input:
;     Token - CMOS Token name constant
; Output:
;     ValuePtr – the byte at this address is updated from the
;                value in the CMOS register
;     EAX – EFI_STATUS,
;           CMOS_BATTERY_ERR,
;           CMOS_OVERFLOW_ERR or
;           CMOS_BITSIZE_ERR
;-------------------------------------------------------------------

CmosUpdateToken PROC  NEAR32 C,   Token:WORD,
                                  ValuePtr:PTR BYTE
; read CMOS Token
        READ_CMOS_TOKEN   Token, ValuePtr
        .if (eax != 0)
            jmp CmosTestTokenAsmExit
        .endif
; increment Token's value and write it back
        mov     eax, ValuePtr       ; increment output parameter
        inc     BYTE PTR [eax]
        WRITE_CMOS_TOKEN  Token, BYTE PTR [eax]
CmosTestTokenAsmExit:
        ret
CmosUpdateToken  ENDP

Notes:

  • Upon READ_CMOS_TOKEN/READ_CMOS_TOKEN macro termination, EAX contains CMOS_BATTERY_ERR error code if the battery is bad or EFI_STATUS error code if other access failure occurred.
  • READ_CMOS_REGISTER and WRITE_CMOS_REGISTER can only be used with 8-bit register locations that have been properly/explicitly defined in SSP.


CmosManager

AMIBIOS Document References

Recovery

Recovery Policy.htm


Recovery Policy

Introduction

This page describes the sequence of events that takes place during the boot process when a bad CMOS battery has been detected, a bad checksum is detected or the first boot (after the boot firmware device is programmed) is detected by the CMOS Manager. First, a brief discussion is provided concerning the issues to consider when developing the recover policy.

Bad Battery Issues

Bad Battery Recovery Policy Issues to Consider
  • For some chipsets, CMOS will be readable and writeable (perhaps with undefined initial values) if the battery is bad, but for other chipsets this is not true.
  • For some systems, writes to CMOS are not preserved through a warm reboot when the battery is bad. In this case, care must be taken to ensure that an infinite reboot sequence is not encountered.
  • It may be desirable to issue a warning to the end-user when the CMOS battery is bad, as the system may not be bootable for some chipsets. Thus, the system should progress through the boot process to a point where a mechanism (typically console output) is available to notify the user.
  • The CMOS Manager module should implement a recovery mechanism that can generically resolve chipset-specific issues when dealing with a dead or missing battery.
  • The Real Time Clock (RTC) region is typically valid when the battery is bad, so accesses to registers below physical address 0xF are always directly accessed.
  • When the battery is dead, the checksum is also bad, but not vice versa.

Bad Checksum Issues

Bad Checksum Recovery Policy Issues to Consider
  • It may be desirable to issue a warning to the end-user when the CMOS checksum is bad, as the system may not be bootable. In this case, the system should progress through the boot process to a point where a mechanism (typically console output) is available to notify the user.
  • The CMOS Manager module should implement a recovery mechanism that can generically resolve chipset-specific issues when dealing with a bad checksum.
  • Typically the detection of a bad battery also implies the checksum is bad. Thus, the bad battery recovery policy will generally have precedence over the bad checksum recovery policy.
  • Clearing the CMOS will generally result in a bad checksum but typically will not result in bad battery detection. (See platform documentation for the CMOS clearing procedure).

First Boot Issues

First Boot Issues to Consider
  • On the first boot after programming the boot firmware device, it is generally advisable to write the default values to CMOS, as default values could have changed for certain locations and new tokens could have been added.

Recovery Path

The following figures illustrates to flow of logic during the PEI phase, where the recovery policy is initialized.

Notes
  • In the case of a bad battery, the Optimal Default values (as specified in SSP CMOS Token declarations) are available in a read/write, in-memory buffer, and access to CMOS registers is virtualized for SSP Tokens. In this case, the user of the CMOS Access PPI/Protocol, interface does not need to make any changes for read/write accesses. For successful read/write of CMOS values in the buffer, EFI_SUCCESS is returned.
  • The default behavior in the case of a bad checksum is to write all the Managed Region default values to physical CMOS in the PEI phase prior to dispatching PEIMs. (See CMOS_MGR_RECOVER_IN_PEI SDL token for more details.)
    • Normally, all default values are written to CMOS in the case of a bad checksum, including non-checksummed locations. (See CMOS_MGR_RECOVER_ONLY_CHECKUMMED SDL token for more details.)
  • In the case of a bad battery, attempting to access values outside the Managed Region (above 0xe) returns EFI_DEVICE_ERROR.
  • The status of the CMOS battery is available through the CMOS Access interface's ReadCmosStatusBytes function.
    • Client modules can also the ReadCmosStatusBytes function to determine whether or not virtualization is in effect.

Porting Notes/Links

The following table provides a brief list of functions, SDL eLinks and/or SDL Tokens that should be considered for porting for platform specific requirements related to the recovery policy configuration.

Name
CMOS_BATTERY_TEST_MAPPING
CMOS_IS_FIRST_BOOT_MAPPING
CMOS_IS_BSP_MAPPING
CMOS_IS_COLD_BOOT_MAPPING
CMOS_MGR_RECOVER_IN_PEI
CMOS_MGR_RECOVER_ONLY_CHECKUMMED
CMOS_PEI_BEFORE_NVRAM_PEI


CmosManager

AMIBIOS Document References

Revision History

4.6.3_CMOSMGR_01.htm

4.6.3_CMOSMGR_02.htm

4.6.3_CMOSMGR_03.htm

4.6.3_CMOSMGR_04.htm

4.6.3_CMOSMGR_05.htm

4.6.3_CMOSMGR_06.htm

4.6.3_CMOSMGR_07.htm

4.6.3_CMOSMGR_08.htm

4.6.3_CMOSMGR_09.htm

4.6.3_CMOSMGR_10.htm

4.6.3_CMOSMGR_11_BETA.htm

4.6.3_CMOSMGR_11_BETA2.htm

4.6.3_CMOSMGR_11_BETA3.htm

4.6.3_CMOSMGR_11_BETA4.htm

4.6.3_CMOSMGR_11_BETA5.htm

4.6.3_CMOSMGR_11_BETA6.htm

4.6.3_CMOSMGR_11_BETA7.htm

4.6.3_CMOSMGR_11_BETA8.htm

4.6.3_CMOSMGR_11_BETA9.htm

4.6.3_CMOSMGR_11_BETA10.htm

4.6.3_CMOSMGR_11_BETA11.htm

4.6.3_CMOSMGR_11_BETA12.htm


Revision History

==========================================
4.6.3_CMOSMGR_01 (February 22, 2008)
==========================================

Module created.


Revision History

==========================================
4.6.3_CMOSMGR_02 (February 26, 2008)
==========================================

- Modified build dependencies
- Added documentation


Revision History

==========================================
4.6.3_CMOSMGR_03 (February 27, 2008)
==========================================

Modified CmosManager.mak to fix buld errors that may occur
under certain conditions


Revision History

==========================================
4.6.3_CMOSMGR_04 (February 29, 2008)
==========================================

-  Added default recovery path policy
-  fixed several bugs


Revision History

==========================================
4.6.3_CMOSMGR_05 (March 7, 2008)
==========================================

This label  fixes:
-- write errors to Optimal Defaults buffer before memory detection
-- CMOS Token table corruption when name strings are disabled


Revision History

==========================================
4.6.3_CMOSMGR_06 (March 25, 2008)
==========================================

-- This label contains changes for
   conditionally predefining CMOS tokens
-- CmosManager.ssp is now forced to be first in the list of SSP files
-- Improved updating of legacy status registers

  (See help documentation for more information)


Revision History

==========================================
4.6.3_CMOSMGR_07 (November 17, 2008)
==========================================

There are major changes in architecture in this Label.  Please read
CmosManager.chm release notes for a better understanding.  The following is
a brief description of some of the changes:

1) EFI_CMOS_ACCESS_INTERFACE is now installed as an intrinsic service
    in both PEI and DXE phases.
2) A public procedure is now available in SEC phase via CmosAccessSec.inc
3) CMOS access in 32-bit assembly (when the PEI Services table is not accessible)
    is provided through CmosAccess32.inc


Revision History

==========================================
4.6.3_CMOSMGR_08 (November 25, 2008)
==========================================

- Added assembly macros
- Moved loading CMOS default values to DXE phase
- Added SEC module part
- Separated project specific SDL Tokens and CMOS Tokens into
  board module part
- fixed a few bugs


Revision History

==========================================
4.6.3_CMOSMGR_09 (January 8, 2009)
==========================================

Core/EM/CmosManager/CmosAccess.c
  CmosReadWrite()
   >Non-checksummed locations are written directly
    when the Optimal defaults buffer is active due to bad checksum, if
    the battery is not bad
  NotChecksummed()
   >Added to determine whether or not a location
    is checksummed
  CalculateChecksum()
   >Use Manager interface to determine first &  last
    register location
  LoadOptimalDefaults()
   >Change name of Manager to Mgr
   >Ignore non-checksummed locations when loading
    optimal defaults due to bad checksum

Include/CmosManagerInterfaces.cif
Core/EM/CmosManager/CmosAccess32.inc
Core/EM/CmosManager/CmosAccessSec.inc
  >The *.inc files are moved to the Include directory

Core/EM/CmosManager/CmosBoard.c
Core/EM/CmosManager/CmosBoard.h
Core/EM/CmosManager/CmosBoard.sdl
Core/EM/CmosManager/CmosBoard.ssp
Core/EM/CmosManager/CmosManager.ssp
Core/EM/CmosManager/CmosManagerBoard.sdl
  >Added function headers
  >Updated function parameter modifiers
  >renamed and updated to CmosBoard module part
  >Core/Board SDL Tokens and CMOS Tokens are separated

Core/EM/CmosManager/CmosManager.c
  CmosManagerCheckAnyStatus()
   >Added to return TRUE if any Manager status bit is set
    as specified by the BitMap input parameter

Core/EM/CmosManager/CmosManager.mak
  >removed COPY_INCLUDES target because CmosAccess32.inc and CmosAccessSec.inc
   are now in the INCLUDE directory

Core/EM/CmosManager/CmosManagerDxe.c
  CmosResetSystem()
   >Added to call Runtime Services ResetSystem() or
    install a callback to execute ResetSystem() if it
    is not available.
  CmosManagerDxeEntry()
   >Added code to check Manager Status to determine if this
    is the first boot and the battery is not bad. If this
    is true, then the Optimal defaults are loaded and
    a reset is executed

Core/EM/CmosManager/CmosManagerPei.c
  CmosManagerPeiEntry()
   >Reseting the system after loading optimal defaults
    is moved to DXE and the CMOS_FIRST_BOOT_DETECTED
    Manager Status is added to indicate that first boot
    has been detected

Core/EM/CmosManager/CmosManagerSec.asm
Core/EM/CmosManager/CmosSec.asm
Core/EM/CmosManager/CmosManagerSec.cif
   >Added CMOS SEC module part
   >moved (renamed CmosSec.asm to CmosManagerSec.asm)
    CmosManagerSec.asm into SEC part

Core/EM/CmosManager/CmosTypes.h
   >force all structure declarations to be byte packed
    as they may be used from Assembly code


Revision History

==========================================
4.6.3_CMOSMGR_10 (January 8, 2009)
==========================================

Documentation update


Revision History

==========================================
4.6.3_CMOSMGR_11_BETA (February 24, 2009)
==========================================

Pre-label integration test version


Revision History

==========================================
4.6.3_CMOSMGR_11_BETA2 (March 11, 2009)
==========================================

*Removed dependency on UpdateRom.exe
*Using updated AmiSsp2.exe


Revision History

==========================================
4.6.3_CMOSMGR_11_BETA3 (June 2, 2009)
==========================================

New/Upated features:
--------------------------------------------------------------------
    o now supports access to all physical CMOS locations, including the real-time
      clock (RTC) region.
    o no longer requires the RomUpdate.exe utility.
    o no longer requires AmiSsp2.exe to be included with the module.
      (Use the latest label of AmiSsp2.exe in AMI tools.)
    o to ensure the CMOS access service is seamlessly available to all modules,
      the CMOS Manager's module entry points are executed via INIT list
      (PeiCoreInitialize, PeiCoreMemoryInstalled and DxeCoreInitialize).
        * It is no longer a requirement to place a dependency on
          EFI_CMOS_DATA_HOB_INSTALLED_GUID when a dependency
          on EFI_PEI_PERMANENT_MEMORY_INSTALLED_PPI is required.
    o default CMOS values are loaded in PEI (prior to the PEI dispatch loop),
      and no system reset is initiated after loading the default values.
        * The CMOS Manager no longer uses the ResetSystem runtime service.
    o for real-time clock (RTC) access, GetTime and SetTime services are
      provided, as well as support for direct reading/writing of RTC registers.
    o replacement of several default functions is supported by defining their
      replacement in the CSP library and using certain SDL Tokens and eLinks to
      link them into the CMOS Manager module.

Bug fixes:
--------------------------------------------------------------------
- None

Known Issues
--------------------------------------------------------------------
- None

Module Changes:
--------------------------------------------------------------------
CmosAccess.c
    o gCmosBatteryIsGood
        * added this EFI_CMOS_BATTERY_TEST function pointer
        * address is initialized by the CMOS_BATTERY_TEST_MAPPING SDL eLink
    o CmosBankReadWrite
        * modified to have one return statement.
    o CmosPhysicalReadWrite
        * modified to add console messages.
    o CmosBufferReadWrite
        * modified to add console messages.
    o CmosRead
        * support for direct reading of all physical CMOS registers, including
          RTC registers
        * proper status returned for case where the CMOS Token is not found
    o ReadCmosStatusBytes
        * rename certain variables
        * added support for updating CMOS_STATUS_BYTES.CmosAccess
    o WriteChecksum
        * added console debug message
    o UpdateBatteryStatus
        * modified to call gCmosBatteryIsGood
        * renamed certain variables
        * added support for CMOS Test module for dumping the CMOS registers
          to console output
    o SynchronizeLegacyStatusRegisters
        * modified to call CmosBankReadWrite when reading/writing legacy
          registers
        * added console debug messages
    o CalculateChecksum
        * added console debug message
    o CmosWrite
        * support for explicit/direct writing of all physical CMOS registers
          (except for those in the Managed CMOS region)
        * support for directly writing RTC registers
        * proper status returned for case where the CMOS Token is not found
    o LoadOptimalDefaults
        * support for loading defaults on first boot to all locations,
          including non-checksummed locations
        * added console messages
    o StopTime/StopTime
        * added these functions to stop/start the RTC clock to support
          EFI_CMOS_ACCESS_INTERFACE.SetTime
    o CmosGetDateTime/CmosSetDateTime
        * added these functions to support new CMOS Access Interface
          functions EFI_CMOS_ACCESS_INTERFACE.GetTime and
          EFI_CMOS_ACCESS_INTERFACE.SetTime.
    o ReadRtcIndex/WriteRtcIndex
        * added these functions to support CmosGetDateTime/CmosSetDateTime
    o DecToBCD/BCDToDec
        * added these functions to support ReadRtcIndex/WriteRtcIndex

CmosBoard.c/h
    o ReadWriteClockRange
        * this function is replaced by  ReadWriteStandardRange (see below)
    o ReadWriteStandardRange
        * this function is the default function for access to CMOS registers
          below 0x7f.
        * the NMI bit is set, as specified by the CMOS_NMI_BIT_VALUE SDL token
        * if reading the clock registers, then the update in progress status
          bit is checked first to ensure validity
    o ReadWriteSecondBankTranslated
        * added this commented example on how to access additional banks of
          CMOS.
        * access to CMOS locations above 0x7f requires porting in
          SBGeneric.c/SBCsplib.h, as well as the addition of a
          CMOS_PORT_MAPPING SDL eLink for each additional access function.
    o CmosMgrBatteryIsGood
        * added this function as the default method for determination of
          whether or not the CMOS battery is good.
    o CmosMgrIsFirstBoot
        * added this function as the default method for determination of
          whether or not the current boot is the first boot after building
          the project and programming the boot device (flash part,
          ROM emulator, ...).
    o CmosMgrIsBsp
        * added this function as the default method for determination of
          whether or not the the currently executing CPU is the boot strap
          processor (BSP).  (For some platforms, application processors
          (APs) may also execute the PEI entrypoint.)

CmosBoard.sdl
    o CMOS_CLOCK_RANGE_INDEX, CMOS_CLOCK_RANGE_DATA, CMOS_STD_INDEX and
      CMOS_STD_DATA
        * these SDL Tokens are removed
        * the only I/O port-related tokens defined by CMOS Manager are
          CMOS_BANK0_INDEX, CMOS_BANK0_DATA to specify the I/O ports
          associated with the first bank of CMOS (range 0x0-0x7F)
        * all access to locations above 0x7F is supported through
          SBGeneric.c/SBCsplib.h
    o CMOS_MGR_SET_NMI_BIT and CMOS_NMI_BIT_VALUE
        * CMOS_MGR_SET_NMI_BIT SDL Token specifies whether or not to set
          the NMI bit for access to the 0x0 to 0x7f region
        * The value of CMOS_NMI_BIT_VALUE will be one of two values, one for
          each case (TRUE or FALSE) of CMOS_MGR_SET_NMI_BIT.  This value will
          be OR'ed with the index port value for access to the 0x0 to 0x7f
          region
    o CMOS_PORT_MAPPING
        * this eLink specifies the access function ReadWriteStandardRange(),
          which is used to access the 0x0 to 0x7f region
    o FIRST_MANAGED_CMOS_ADDRESS and MAX_MANAGED_CMOS_ADDRESS
        * these SDL Tokens specify the range of physical CMOS addresses
          to be managed by CMOS Manager
        * MAX_MANAGED_CMOS_ADDRESS = last CMOS address + 1, with a default
          value of 128
    o CMOS_USES_STANDARD_RANGE_ACCESS
        * this SDL Token specifies whether or not to use CMOS Manager's
          default access function for the 0-0x7f range
        * if the access to this range is defined elsewhere (typically,
          SBGeneric.c/SBCsplib.h), this token should be FALSE (0) and a
          CMOS_PORT_MAPPING SDL eLink should be defined.
    o CMOS_USES_STANDARD_BATTERY_TEST and CMOS_BATTERY_TEST_MAPPING
        * this SDL Token and eLink combination allows redefinition of the
          default function for validating whether or not the CMOS battery is
          good
    o  CMOS_USES_STANDARD_IS_FIRST_BOOT and CMOS_IS_FIRST_BOOT_MAPPING
        * this SDL Token and eLink combination allows redefinition of the
          default function for validating whether or not the platform is
          executing a first boot
    o CMOS_USES_STANDARD_IS_BSP and CMOS_IS_BSP_MAPPING
        * this SDL Token and eLink combination allows redefinition of the
          default function for validating whether or not the currently
          executing CPU core is the boot strap processor (BSP)
    o DEFINE_TCG_CMOS_REGISTERS, DEFINE_NB_CMOS_REGISTERS and
      DEFINE_CPU_CMOS_REGISTERS
        * removed these SDL Tokens as CMOS Manager no longer pre-defines
          SSP Tokens

* CmosBoard.ssp
    o Removed pre-defined SSP Tokens

* CmosManager.c/CmosManager.h
    o CmosGetDateTime/CmosSetDateTime
        * added external declarations for these new CMOS Access interface functions
    o gIsFirstBoot
        * added this EFI_CMOS_IS_FIRST_BOOT function pointer
        * address is initialized by the CMOS_IS_FIRST_BOOT_MAPPING SDL eLink
    o CmosManagerSetClearStatus
        * variable renaming
    o CmosUpdateMemoryStatus
        * added console message
    o SaveApiPointerToCmos
        * Allow call to this function with a null pointer to save the CMOS
          Manager's internal pointer
        * A check is added to ensure the battery is good before saving the
          pointer
    o GetApiPointerFromCmos
        * A check is added to ensure the battery is good before saving the
          pointer
    o CmosManagerAsm/gCmosManagerAsm
        * this global is removed
    o InitializeCmosManagerInterface
        * added code to update EFI_CMOS_ACCESS_INTERFACE.GetTime,
          EFI_CMOS_ACCESS_INTERFACE.SetTime and
          EFI_CMOS_ACCESS_INTERFACE.PeiServices pointers.
    o NewCmosManagerInterface
        * added code to call gIsFirstBoot to determine whether or not the
          first boot has been detected.
        * removed call to SaveCmosDataTablesToHob() as the HOB is created
          using the PeiCoreMemoryInstalled INIT list to call
          CmosManagerAfterMemoryEntry().
    o EFI_CMOS_MANAGER_INTERFACE
        * updated field descriptions in the structure header notes

CmosManager.mak
    o added /D complier flags to pass SDL eLinks (CMOS_IS_BSP_MAPPING,
      CMOS_IS_FIRST_BOOT_MAPPING and CMOS_BATTERY_TEST_MAPPING) to the
      compiler environment for PEI and DXE binaries.
    o added AMICSPLib dependencies for PEI and DXE binaries
    o removed AFTER_ROM target, as dependency on RomUpdate.exe has been
      depreciated

CmosManager.sdl
    o added file header
    o CMOS_BATTERY_TEST_MAPPING, CMOS_IS_FIRST_BOOT_MAPPING and
      CMOS_IS_BSP_MAPPING SDL parent eLink are added to facilitate overriding
      of certain functions that may be platform dependent
    o PeiCoreMemoryInstalled
        * added this eLink to invoke the entry point
          CmosManagerAfterMemoryEntry() after memory detection

CmosManagerBuild.cif
    o removed Token.ssp

CmosManagerDxe.c
    o now loading default values on the first boot is performed in PEI
    o console messages are now added
    o removed code to test for the monotonic counter and reset the system on
      the first boot

CmosManagerHob.c
    o CreateCmosDataHobPpiCallback
        * renamed to CmosManagerAfterMemoryEntry
    o SaveCmosDataTablesToHob
        * removed this function as the callback is no longer required
          (CreateCmosDataHob is called from CmosManagerAfterMemoryEntry)

CmosManagerPei.c
    o IsFirstBoot
        * this functionality is moved to CmosManager.c
    o IsBsp
        * replaced by gIsBsp, which is an EFI_CMOS_IS_BSP function pointer
          initialized by the CMOS_IS_BSP_MAPPING SDL eLink
    o CmosManagerPeiEntry
        * added support for CMOS Test module and console messages
        * For bad battery:
            * use the read/write optimal defaults buffer for all CMOS access
            * do not attempt to save the CMOS-based API pointer to physical CMOS
            * do not load optimal defaults on first boot
        * For bad checksum:
            * use the read/write optimal defaults buffer for checksummed location
              access

CmosManagerSec.asm
    o CmosReadWrite procedure modified to OR the index value with the
      CMOS_NMI_BIT_VALUE SDL token value.
    o The global bcmos_addr_port/bcmos_data_port equates are updated to use
      CMOS_BANK0_INDEX/CMOS_BANK0_DATA SDL tokens.
    o SEC_CmosManagerApiPointer
        * removed this global pointer as dependency on RomUpdate.exe has been
          depreciated
    o SEC_CmosManager
        * removed code to update the CMOS-based API pointer with the value
          stored in SEC_CmosManagerApiPointer

CmosAccess.h
    o LOCATE_CMOS_ACCESS_API_POINTER
        * this macro is modified to OR the index value with CMOS_NMI_BIT_VALUE
          and use the CMOS_BANK0_INDEX/CMOS_BANK0_DATA SDL tokens to specify the
          I/O index/data ports
    o STATUS_REGISTER_A_BYTE
        * added this structure to model CMOS status register A.
    o CMOS_ACCESS_STATUS
        * added this structure to support the new CMOS_STATUS_BYTES field
          (CmosAccess), which specifies whether or not CMOS access is
          virtualized.
    o EFI_CMOS_ACCESS_INTERFACE
        * Added support for two new time-related function pointers
          (GetTime and SetTime) and their associated prototypes

CmosAccess32.inc
    o CMOS_BANK0_INDEX/CMOS_BANK0_DATA SDL tokens are now used instead of
      CMOS_CLOCK_RANGE_INDEX/CMOS_CLOCK_RANGE_INDEX for file equates.
    o BCMOS_ADDR_PORT/BCMOS_DATA_PORT
        * these constants are no longer used, because only bank 0 is allowed
          to store the CMOS-based API pointer.
    o MaReadCmosByte and GetPointerCmos32
        * now specifiy the value of the NMI bit using the CMOS_NMI_BIT_VALUE
          SDL token.
    o EFI_CMOS_ACCESS_INTERFACE
        * removed Signature field from the structure and added
          GetTime/SetTime pointers

CmosManagerTools.cif
    o AmiSsp2.exe
        * This utility is no longer kept local by CMOS Manager
    o RomUpdate.exe
        * this utility has been depreciated by CMOS Manager

CmosTables.c
    o gFirstManagedRegister
        * this global constant is now initialized with FIRST_CMOS_REGISTER,
          which is now generated by AmiSsp2.exe during the build process

CmosTypes.h
    o FIRST_CMOS_REGISTER
        * removed this explicit constant definition as it is now generated by
          AmiSsp2.exe.
    o MIN_TOKEN_VALUE
        * added this constant to specified the lowest valid token value
    o CMOS_STATUS_BYTES_COUNT
        * usage of this value is depreciated
    o CMOS_DEFAULTS_LOADED and CMOS_DEFAULTS_STATUS_TYPE
        * added these enums to specify whether or not CMOS Manager is using
          the default CMOS values, where the latter is part of the
          CMOS_MANAGER_STATUS status structure
    o DEFINE_PEI_SERVICES
        * updated this macro to remove support for RomUpdate.exe
    o CMOS_TRACE, CMOS_TRACE_FULL and CMOS_TRACE_ALWAYS
        * added these macros to facilitate console messages based upon the
          project and module debug levels

CmosManager.chm
    o updated to support this label.

RomUpdate.exe
    o this utility is removed

Template.ssp
    o FirstRegister
        * added this new keyword to specify to AmiSsp2.exe where to start
          allocating CMOS locations

Tests and Validation:
--------------------------------------------------------------------
    o AMD Shiner
    o Intel Montevina


Revision History

==========================================
4.6.3_CMOSMGR_11_BETA4 (June 15, 2009)
==========================================

Update file headers


Revision History

==========================================
4.6.3_CMOSMGR_11_BETA5 (July 23, 2009)
==========================================

CmosAccess.c
    o CmosMgrReadRtcIndex/CmosMgrWriteRtcIndex
        * renamed these functions to fix CSP library name conflicts
          in certain projects.

CmosManager.mak
    o added /coff complier flag for CPU modules that require PE32 object files

CmosAccessSec.inc
    o LAST_ADDRESS is only valid when the CPU module does not require PE32
      object files.

CmosManagerSec.asm
    o LAST_ADDRESS is only valid when the CPU module does not require PE32
      object files.

CmosManager.chm
    o updated to support this label.


Revision History

==========================================
4.6.3_CMOSMGR_11_BETA6 (July 29, 2009)
==========================================

updates Aptio Enhancement EIP 22205
(no code changes)


Revision History

==========================================
4.6.3_CMOSMGR_11_BETA7 (September 17, 2009)
==========================================

Template.ssp
    o TokenInclude is initialized with an empty string
        * This keyword is required for compatibility with Core8 projects, but
          for Aptio it must be an empty string.

CmosAccessSec.inc
    o Added versions of jump macros for PE32 SEC binaries.


Revision History

==========================================
4.6.3_CMOSMGR_11_BETA8 (November 10, 2009)
==========================================

Aptio Tools
    Version: 4.5.5_Tools_28
       Date: July, 2009

Visual eBios
    Version: RSS 5.67.0054
       Date: June 19, 2009

Section I: Features Added With This Release
    * SMM Support for CMOS Access Interface

Section II: Files Changed/Added With This Release
    CmosBoard.sdl
        * Updated help file headers for SDL tokens/elinks
        * Added CMOS_SMM_SUPPORT token for enabling/disabling
          SMM CMOS Access support.
    CmosManagerPei.c
        * Removed depreciated debug code
    CmosManagerDxe.c
        * Fixed text string
    CmosManager.sdl
        * Updated help file headers for SDL tokens/elinks
        * Added $(BUILD_DIR)\CmosManagerSmm.ffs elink
    CmosAccess.h
        * Moved MIN_TOKEN_VALUE constant to this file
        * Added EFI_SMM_CMOS_ACCESS_GUID definition for the SMRAM-based
          CMOS Access protocol
        * Added LOCATE_CMOS_ACCESS_SMM_PROTOCOL macro for locating
          the SMRAM-based protocol
    CmosManager.c
        * Implemented support for SMM CMOS Access Interface
          initialization (allocating SMRAM and new GUID for
          the SMM protocol)
    CmosAccess.c
        * Removed depreciated debug code
    CmosTables.c
        * Removed "CONST" specifier for gCmosTokenTable
    CmosTypes.h
        * Removed depreciated debug code
        * Moved MIN_TOKEN_VALUE to CMOS Interface header
    CmosManager.mak
        * Added CMOS_MANAGER_SMM target with a dependency on
          CMOS_SMM_SUPPORT

Section II: Bugs Fixed/EIPs Resolved With This Release
    EIP 29759 - CMOS Manager Interface can't use in SMM Runtime.

Section III: Known issues and limitations in this release
    None

Section IV: Tests and Validation
    * Shiner platform
    * CMOS Manager Test Module


Revision History

==========================================
4.6.3_CMOSMGR_11_BETA9 (December 4, 2009)
==========================================

Aptio Tools
    Version: 4.5.5_Tools_28
       Date: July, 2009

Visual eBios
    Version: RSS 5.67.0054
       Date: June 19, 2009

Section I: Features Added With This Release

  1.  When a bad checksum is detected, the Optimal Defaults
      buffer is written to physical CMOS in PEI instead of DXE.
      This should resolve the issue where resets in PEI phase
      lose CMOS updates due to the buffer being destroyed.

      (By default all locations in the Managed Region are written
      when the Optimal Defaults buffer is written to CMOS. See
      CMOS_MGR_RECOVER_ONLY_CHECKUMMED SDL token for additional
      options.)

  2.  The bad checksum status is not cleared until DXE, even though
      CMOS is recovered in PEI, so the other PEIMs can be notified
      of the loading of CMOS defaults.

  3.  Added CMOS_PEI_BEFORE_NVRAM_PEI for platforms that require
      CMOS Manager to execute before NVRAM PEI code. By default,
      ordering is not enforced.

  4.  Added additional porting function to determine whether or
      not the platform is executing a cold boot.  The default
      function always returns TRUE and is expected to work for
      most platforms.  (The Optimal defaults buffer is written
      to CMOS only on a cold boot, for the BSP and if the
      checksum is bad.)

Section II: Files Changed/Added With This Release

    CmosManager.cif
        1. Removed duplicate instance of the CmosSmm module part.
    CmosBoard.sdl
        1. Updated help information for all tokens with respect to the
           the changes in the recovery policy for this label.
        2. Added new tokens:
             CMOS_MGR_RECOVER_ONLY_CHECKUMMED
             CMOS_MGR_RECOVER_IN_PEI
             CMOS_PEI_BEFORE_NVRAM_PEI
             CMOS_USES_STANDARD_IS_COLD_BOOT
        3. Added new eLink:
           CMOS_IS_COLD_BOOT_MAPPING
    CmosBoard.c/h
        1. Updated functions headers to reflect changed in recovery policy.
        2. Minor changes to comply with coding standards.
        3. Added new function: CmosMgrIsColdBoot()
        4. Modified input parameters to CmosMgrIsBsp()
    CmosManagerSec.asm
        1. Minor changes to comply with coding standards.
    CmosManagerPei.c
        1. CMOS_BSP_IS_EXECUTING status bit
           is used instead of directly calling gIsBsp()
        2. Loading of Optimal Defaults on bad checksum
           is done earlier by default and is enabled/disabled
           by CMOS_RECOVER_IN_PEI SDL token.
           (Note: the bad checksum bit is not cleared until DXE.)
        3. The CMOS_USE_OPTIMAL_DEFAULTS enum is replaced with
           CMOS_OPTIMAL_DEFAULTS_ON.
        4. Minor changes to comply with coding standards.
    CmosManagerDxe.c
        1. CMOS_DISCONTINUE_OPTIMAL_DEFAULTS is replace with
           CMOS_OPTIMAL_DEFAULTS_OFF.
        2. Loading of Optimal Defaults depends only on
           wether or not the buffer is enabled.
    CmosManager.sdl
        1. CMOS_PEI_BEFORE_NVRAM_PEI token is added to control whether
           or not CMOS PEI code executes before NVRAM PEI
           code. (default is off)
        2. If DEBUG_MODE is on, INIT_LIST ordering is changed
           so that Status Codes initialization is done
           before CMOS code.
        3. CMOS_IS_COLD_BOOT_MAPPING eLink added to allow
           overriding of the default cold boot detection
           code.
    CmosAccess.h
        1. Minor changes to comply with coding standards.
    CmosAccess32.inc
        1. Minor changes to comply with coding standards.
    CmosAccessSec.inc
        1. Minor changes to comply with coding standards.
    CmosManager.c/h
        1. Moved gIsBsp here and added gIsColdBoot definition
        2. Updated CmosConfigureManager() to force calculation of
           checksum after enabling the Optimal Defaults buffer.
        3. Updated NewCmosManagerInterface() to update first boot,
           BSP detected and incoherency policy settings bits prior to
           calculating the checksum and getting the battery status.
        4. Minor changes for help file.
    CmosAccess.c
        1. Updated CmosReadWrite() to use physical access to
           non-checksummed locations within the Managed Region
           only if CMOS_RECOVER_ONLY_CHECKSUMMED is TRUE.
           (controlled via CMOS_MGR_RECOVER_ONLY_CHECKUMMED
           SDL token)
        2. Added CanClearLegacyStatusBits() to determine
           whether or not the legacy status bits can be
           clear to a non-failure status.
        3. SynchronizeLegacyStatusRegisters() is updated to
           only clear the bad checksum failure status in
           the legacy status registers in the DXE phase
           or on the first boot after flashing the firmware.
    CmosManagerHob.c
        1. changed CmosManagerAfterMemoryEntry() to update
        the PEI Services table earlier.
    CmosTypes.h
        1. Added/updated typdefs for BSP test and
           cold boot test functions.
        2. Added additional Manager Status bits to
           support recovery policy configuration changes.
    CmosManager.mak
        1. Clean-up the SEC target code
        2. Define CMOS_IS_COLD_BOOT_MAPPING environment
           variable passed to C-source for cold boot
           detection function overriding.

Section II: Bugs Fixed/EIPs Resolved With This Release
    The following EIP are addressed:
      EIP 30585 - CMOS Checksum Doesn't Update
      EIP 31988 - load the default setup values if the CMOS bad bit is set
      EIP 24449 - Variable load default when RTC power failure

Section III: Known issues and limitations in this release
    None

Section IV: Tests and Validation
    * Shiner platform
    * CMOS Manager Test Module


Revision History

==========================================
4.6.3_CMOSMGR_11_BETA10 (March 5, 2010)
==========================================

Aptio Tools
    Version: 4.5.5_Tools_29
       Date: November, 2009

Visual eBios
    Version: RSS 5.68.0087
       Date: October 30, 2009

Section I: Features Added With This Release

  1.  A new porting funtion is added to distinguish between a dead
      battery and usable CMOS hardware.  (For some systems the
      CMOS hardware is usable even if the battery is dead.)

  2.  Support for "unmanaged" locations, where a default value
      is never written and the location is not included in the
      checksum.

Section II: Files Changed/Added With This Release

    "CMOS Board"
        Core\EM\CmosManager\CmosBoard.sdl
            1. Added CMOS_USES_STANDARD_IS_CMOS_USABLE token
               to specify whether or not to use the default
               function for testing the usability of CMOS.
            2. Added CMOS_IS_USABLE_MAPPING elink to specify
               the default function for testing the
               usability of CMOS.
        Core\EM\CmosManager\CmosBoard.c
            1. Added CmosIsUsable() as the default function
               for determining the usability of CMOS.
            2. Added global array (gUnmanagedTable) for
               specifying which register locations are
               unmanaged. (This is a patch.  Future releases
               will have a different mechanism for this
               new feature.)
        Core\EM\CmosManager\CmosBoard.h
            1. Declaration for CmosIsUsable
    "CMOS PEI"
        Core\EM\CmosManager\CmosManagerPei.c
            1. Using the CMOS_IS_USABLE status for deciding
               when to load defaults, save API pointer and/or
               cofigure to use a memory-based buffer for
               CMOS values.
    "CMOS DXE"
        Core\EM\CmosManager\CmosManagerDxe.c
            1. Using the CMOS_IS_USABLE status for deciding
               when how to handle disabling the memory-based
               buffer for CMOS values.
    "CMOS SMM"
        Core\EM\CmosManager\CmosManagerSmm.c
            1. Removed debug code.
    "CMOS Core"
        Core\EM\CmosManager\CmosManager.sdl
            1. Added parent declaration for the
               CMOS_IS_USABLE_MAPPING elink.
    "CMOS Interfaces"
        Include\CmosAccess.h
            1. Changed the CMOS_ACCESS_STATUS structure
               and renamed it to CMOS_CONFIGURATION_STATUS
    "CMOS Source"
        Core\EM\CmosManager\CmosManager.c
            1. Added gCmosIsUsable initialized by the
               CMOS_IS_USABLE_MAPPING sdl token.
            2. Code now tests CMOS_IS_USABLE
               instead of CMOS_BAD_BATTERY.
        Core\EM\CmosManager\CmosAccess.c
            1. Modified usage of CMOS_STATUS_BYTES.
            2. Modified SynchronizeLegacyStatusRegisters
               to call CanClearLegacyStatusBits before
               clearing register 0xE status bits.
            3. Code now tests CMOS_IS_USABLE
               instead of CMOS_BAD_BATTERY.
            4. LoadOptimalDefaults now ignores locations
               specified in the global gUnmanagedTable
               structure.
    "CMOS Includes"
        Core\EM\CmosManager\CmosTypes.h
            1. Added CMOS_IS_USABLE bit to the
               CMOS_MANAGER_STATUS enumerated type.
            2. Added EFI_CMOS_IS_CMOS_USABLE declaration
               for the function that test for CMOS
               usability.
    "CMOS Build"
        Core\EM\CmosManager\CmosManager.mak
            1. Use \D to pass the CMOS_IS_USABLE_MAPPING
               elink value during build-time

Section II: Bugs Fixed/EIPs Resolved With This Release
    The following EIP are addressed:
      EIP 35259 - FORCE_USER_TO_SETUP_IF_CMOS_BAD on Calpella not working?

Section III: Known issues and limitations in this release
    None

Section IV: Tests and Validation
    * Calpella (Red Fort) platform


Revision History

==========================================
4.6.3_CMOSMGR_11_BETA11 (June 15, 2010)
==========================================

Aptio Tools
    Version: 4.5.5_Tools_29
       Date: November, 2009

Visual eBios
    Version: RSS 5.68.0087
       Date: October 30, 2009

Section I: Features Added With This Release

  1.  CMOS-related setup page is supported. (Requires TSE
      label 4.6.2_TSE_2_01_1204 or later.)

  2.  Support for CMOS Manager messages during power-on.
      (Requires TSE label 4.6.2_TSE_2_01_1204 or later.)

  3.  Support for native "unmanaged" CMOS tokens in the
      latest AmiSsp2.exe utility.  (Please note that this
      label of CMOS Manager requires the latest label of
      AmiSsp2.exe.)

Section II: Files Changed/Added With This Release

  "CMOS Manager"
    CmosManager.cif
        - moved CmosManager.sdl here
    CmosManager.sdl
        - removed CMOS_PEI_BEFORE_NVRAM_PEI token support
          (not supported by latest architecture)
        - added CMOS_MGR_CFLAGS to allow adding CMOS Manager's
          build flags
  "CMOS Board"
    CmosManagerBoard.cif
        - added CmosSetup.sd and CmosSetup.uni to support
          CMOS Manager's setup page
        - added CmosMessages module part to support CMOS Manager
          power-on messages
    CmosBoard.sdl
        - removed CMOS_PEI_BEFORE_NVRAM_PEI token
        - added CMOS_SETUP_SUPPORT token to enable/disable setup support
        - added CMOS_MESSAGES_SUPPORT token to enable/disable power-on
          messages support
        - added SETUP_SDBS & SETUP_DEFINITIONS elinks to support the
          required setup database information
    CmosBoard.ssp
        - CMOS API pointer bytes are now declared as Managed = NO
    CmosBoard.c
        - removed patch for "unmanaged" tokens
    CmosSetup.sd
        - added this file for setup page support
    CmosSetup.uni
        - added this file for setup page support
  "CMOS PEI"
    CmosManagerPei.c
        - modified CmosManagerPeiEntry() to load defaults only upon
          both cold boot and first boot detection to ensure defaults
          only get loaded one time (requires platform porting)
        - modified console message display
  "CMOS DXE"
    CmosManagerDxe.c
        - added boot event handler, UpdateCmosSetupVariable(), for setup
          entry to update CMOS Manager's setup variable
        - added boot event handler, ClearCmosBasedStatus(), to clear
          CMOS-based status bits prior to OS boot.
        - modified CmosManagerDxeEntry() to call CreateEventHandlers(),
          which registers CMOS Manager's event handlers
  "CMOS Core"
    CmosManagerCore.cif
        - moved CmosManager.sdl from this location to the main CIF file
        - removed CmosTool module part from module
  "CMOS Source"
    CmosManager.c
        - modified CmosManagerSetClearStatus() to update the new CMOS-based
          status bits
        - modified InitializeCmosManagerInterface() to update the internal
          interface pointers related to the unmanaged location CMOS table
        - modified NewCmosManagerInterface() such that gCmosIsUsable() is
          called earlier
    CmosAccess.c
        - removed patched support for "unmanaged" locations
        - modified ReadCmosStatusBytes() to read status from CMOS-based
          status bits, if CMOS is usable
        - modified UpdateBatteryStatus() to call gCmosBatteryIsGood() in
          DXE, instead of forcing the battery clear
        - modified CanClearLegacyStatusBits() to only clear status bits
          in DXE phase
        - updated CalculateUpdatedCheckSum, CalculateChecksum() and
          LoadOptimalDefaults() to natively support unmanaged CMOS locations.
          (The "unmanaged" patch is no longer supported.)
    CmosTables.c
        - added gUnmanagedTable and gUnmanagedTableSize, which will be defined
          at build time
    CmosManagerHob.c
        - added file scope extern declarations for gUnmanagedTable and
          gUnmanagedTableSize
        - modified CreateCmosDataHob() to update unmanaged information in the
          HOB
        - modified InitializeCmosTablesFromHob() to update unmanaged information
          from the HOB in DXE
  "CMOS Includes"
    CmosManager.h
        - updated the internal interface structure (EFI_CMOS_MANAGER_INTERFACE)
          to contain unmanaged table information
    CmosManagerHob.h
        - added support for UnmanagedTableCount and UnmanagedTable to pass to DXE
  "CMOS Build"
    CmosManager.mak
        - added support for platform-specific build flags (CMOS_MGR_CFLAGS)
        - added build target for setup database
    Template.ssp
        - added declarations for CMOS-based status bits (CMOS_MGR_BATTERY_BAD,
          CMOS_MGR_CHECKSUM_BAD, CMOS_MGR_DEFAULTS_LOADED and
          CMOS_MGR_FIRST_BOOT_DETECTED)

Section II: Bugs Fixed/EIPs Resolved With This Release
    None

Section III: Known issues and limitations in this release
    * For power-on messages and setup page support, TSE label
      4.6.2_TSE_2_01_1204 or later is required.
        * Please get the latest version of AmiSsp2.exe, which natively supports
      unmanaged CMOS tokens (See Template.ssp for example declarations for
      unmanaged tokens.)  (Aside from the declaration, there is no difference
      in usage between an unmanaged token and any other token.)
    * Patched support (from previous release) for unmanaged CMOS locations is
      no longer available. Please update token declarations to include the
      Managed = NO field if an unmanaged location is required.  (CmosBoad.c
      will need to be updated if this file is private for the purposes of
      patched unmanaged locations.)

Section IV: Tests and Validation
    * Calpella (Red Fort) platform


Revision History

==========================================
4.6.3_CMOSMGR_11_BETA12 (January 31, 2012)
==========================================

[SS Server]     Alaska
[SS Path]       SOURCE/Modules/CMOS Manager
[Label]         4.6.3_CMOSMGR_11_BETA12
[Module Name]   CMOS Manager
[Description]   Generic CMOS Access
[Entries]

Section I: AMI Build Tools
    Tools Label: 4.5.5_TOOLS_36  Dated: 2011-06
    Visual eBios: RSS.5.70.0171   Dated: 2010-10-04
    Compiler Tool(s): Microsoft’s Windows Driver Kit (WDK) Ver. 7600.16385.1

Section II: Third Party Code Present In Component
    N/A

Section III: Features Added/Changed with this Release

  1.  Support for setup customization as defined by the Aptio Setup
      Customization Guide.

  2.  Support for ASL CMOS access method

      I.e., use \CMOS.ACCE(1, 0x1232, BYTE) to read the '
      CMOS_MGR_DEFAULTS_LOADED CMOS token, where
      CMOS_MGR_DEFAULTS_LOADED = 0x1232.

Section IV: Files

--------------------------------------------------------------------------
[TAG]         EIP56197
[Category]    Spec Update
[Severity]    Normal
[Description] CMOS Manager Support in Runtime Code
[Files]       CmosManager.sdl
              CmosSetup.uni
              CmosMessages.uni
              CmosManagerSmm.cif
              CmosAccess.h
              CmosManagerSmm.c
              CmosAccess.asl

--------------------------------------------------------------------------
[TAG]         EIP75889
[Category]    Spec Update
[Severity]    Normal
[Description] Support Setup Customization
[Files]       CmosManager.sdl
              CmosSetup.sd
              CmosSetup.uni
              CmosMessages.uni

Section V: Known Issues and Limitations in this Release
    N/A

Section VI: Tests and Validation
    This module is tested on the multiple Intel and AMD platforms.


Function by File Name

AMIBIOS Function Reference

By File Name

The following is a list of the source files.
For a list in alphabetical order, see In Alphabetical Order.
For a list by segment, see By Segment.

  • CmosAccess.asl
  • CmosAccess.c
  • CmosAccess.h
  • CmosAccess32.inc
  • CmosAccessSec.inc
  • CmosBoard.c
  • CmosBoard.h
  • CmosBoard.sdl
  • CmosManager.c
  • CmosManager.h
  • CmosManager.mak
  • CmosManager.sdl
  • CmosManagerDxe.c
  • CmosManagerDxe.h
  • CmosManagerHob.c
  • CmosManagerHob.h
  • CmosManagerPei.c
  • CmosManagerPei.h
  • CmosManagerSec.asm
  • CmosManagerSmm.c
  • CmosManagerSmm.dxs
  • CmosManagerSmm.h
  • CmosMessages.c
  • CmosMessages.mak
  • CmosMessages.sdl
  • CmosSetup.sd
  • CmosTables.c
  • CmosTypes.h


CmosAccess.asl

Description:
This file contains an ASL method for accessing CMOS from
ASL code.


CmosAccess.c

Description:
Contains the routines that constitute the CMOS access
implementation.  This file contains source code that is used
for both PEI and DXE phases.

The following functions are used in the file: CmosAccess.c.

Function | Description
BCDToDec | Converts a Decimal value to a BCD value.
BitFieldOverflow | For testing whether or not a Value overflows the field size as specified in Token.
CalculateChecksum | Calculate the checksum over the entire range of managed CMOS (standard and/or extended CMOS).
CalculateUpdatedCheckSum | Computes a new "updated" CMOS checksum based on the change of value at a single address.
CanClearLegacyStatusBits | Determines whether or not the legacy status bits in CMOS_DIAGNOSTIC_STATUS_REGISTER can be cleared to a non-failure status.
CmosBankReadWrite | This function determines which structure in the global CMOS_PORT_MAP array corresponds to the provided CmosAddress and either calls the associated function or uses the associated IO ports to read/write the CMOS register value to/from the CmosParameterValue.
CmosBufferReadWrite | This function provides support for performing the actual read or write from/to a CMOS buffer location (using the Optimal Defaults Table Buffer).
CmosFindToken | Returns index of CMOS token in token table or 0 if not found.
CmosGetDateTime | Return the current date and time
CmosGetTokenFromRegister | Returns encoded token for the specified register.
CmosMgrReadRtcIndex | Read the RTC value at the given Index.
CmosMgrWriteRtcIndex | Write the RTC value at the given Index.
CmosPhysicalReadWrite | This function provides support for performing the actual read or write from/to a physical CMOS location.
CmosRead | Reads to CmosValue from the CMOS location specified by CmosToken.
CmosReadWrite | Decides which version of xxxReadWrite to call based upon the current Access Routing Logic.
CmosReadWriteEncodedToken | This is the main worker function which verifies and either reads/writes a value from/to the CMOS location as specified by the encoded token.
CmosSetDateTime | This routine simply writes the CMOS RTC registers from information provided by the EFI_TIME structure, assuming the information is correct.
CmosWrite | Writes from CmosValue to CMOS location encoded into CmosToken.
DecodeParameter | Value is shifted right and masked by the bit field's size and offset as specified in Token.
EncodeParameter | Value is shifted left by the bit field size specified in Token.
LoadOptimalDefaults | Initialize all physical CMOS registers with the default values specified in NvramField's Default value.
NotChecksummed | This function returns TRUE if the CmosAddress is NOT included in the checksum and returns FALSE otherwise.
ReadChecksum | Reads the checksum from the CMOS register(s).
ReadCmosBytes | Reads Bytes from the specified CMOS register(s).
ReadCmosStatusBytes | Initializes a CMOS_STATUS_BYTES structure and reads the associated CMOS registers.
SetClobberBits | Creates a mask with bits set corresponding to the size and offset of the bit field as specified by Token.
StartTime | Start the time on RTC clock. This is used when changing the Date and Time
StopTime | Stops the time on RTC clock.
SynchronizeLegacyStatusRegisters | Synchronizes legacy CMOS status registers with status changes.
UpdateBatteryStatus | This function is used to update the CMOS battery status. It is up to the user of the Manager interface to determine whether or ot the platform supports this feature. (If the platform does not support this feature, the battery status is indeterminate.)
WriteChecksum | Write the checksum to the CMOS register(s).


BCDToDec in the CmosAccess.c

Function : BCDToDec

File: CmosAccess.c
Description:
Converts a Decimal value to a BCD value.
Input:
IN UINT8 Dec - Decimal value
Output:
UINT8 (return value) - BCD value
Notes:
Only for 2 digit decimal.
Built on 11:30:58 01/27/12


BitFieldOverflow in the CmosAccess.c

Function : BitFieldOverflow

File: CmosAccess.c
Description:
For testing whether or not a Value overflows the field size
as specified in Token.
Input:
IN UINT8 *Value
   -- Value to be tested
IN CMOS_TOKEN *Token
   -- Token describing the bit field's size
Notes:
None
Built on 11:30:58 01/27/12


CalculateChecksum in the CmosAccess.c

Function : CalculateChecksum

File: CmosAccess.c
Description:
Calculate the checksum over the entire range of managed CMOS
(standard and/or extended CMOS).
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Manager
   -- The Manger interface pointer.
OUT UINT16 *ChecksumValue
   -- The calculated checksum.
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS or valid EFI error code
Modified:
Manager->ManagerStatus
   CMOS_BAD_CHECKSUM - set/clear after comparing with
                       the current checksum in CMOS.
Built on 11:30:58 01/27/12


CalculateUpdatedCheckSum in the CmosAccess.c

Function : CalculateUpdatedCheckSum

File: CmosAccess.c
Description:
Computes a new "updated" CMOS checksum based on the change of value
at a single address.
Input:
IN EFI_CMOS_MANAGER_INTERFACE  *Manager
   -- The Manger interface pointer.
IN UINT16 CmosAddress
   -- CMOS location to be changed
IN UINT8 OldCmosValue
   -- Current value at the CMOS location
IN UINT8 NewCmosValue
   -- New value to be written to the CMOS location
OUT UINT16 *NewChecksum
   -- Updated checksum
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS or a valid EFI error code
Notes:
After this call, Manager->CheckStatus(Manager,
CMOS_ADDRESS_IS_CHECKSUMMED) returns TRUE if the address "is"
included in the checksum.
Built on 11:30:58 01/27/12


CanClearLegacyStatusBits in the CmosAccess.c

Function : CanClearLegacyStatusBits

File: CmosAccess.c
Description:
Determines whether or not the legacy status bits in
CMOS_DIAGNOSTIC_STATUS_REGISTER can be cleared to a non-failure
status.
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Mgr
   -- Manger interface pointer
Output:
BOOLEAN (Return Value)
   = TRUE - bits can be cleared
   = FALSE - bits can be cleared
Notes:

EFI_CMOS_ACCESS_INTERFACE.PeiServices == NULL in DXE phase.
Built on 11:30:58 01/27/12


CmosBankReadWrite in the CmosAccess.c

Function : CmosBankReadWrite

File: CmosAccess.c
Description:
This function determines which structure in the global CMOS_PORT_MAP
array corresponds to the provided CmosAddress and either calls the
associated function or uses the associated IO ports to read/write the
CMOS register value to/from the CmosParameterValue.
Input:
IN      EFI_CMOS_MANAGER_INTERFACE *Manager
   --  Pointer to the CMOS Manager internal interface
IN      CMOS_ACCESS_TYPE AccessType
   --  WriteType or ReadType
IN      UINT16 CmosAddress
   --  CMOS register to for which the access is to be made
IN/OUT  UINT8 *CmosParameterValue
   --  This is the value to write for write access or the
       value that was read for read access.
Output:
EFI_STATUS (Return Value)
   EFI_SUCCESS or valid EFI error code
Notes:
N/A
Built on 11:30:58 01/27/12


CmosBufferReadWrite in the CmosAccess.c

Function : CmosBufferReadWrite

File: CmosAccess.c
Description:
This function provides support for performing the actual
read or write from/to a CMOS buffer location (using the
Optimal Defaults Table Buffer).
Input:
IN EFI_CMOS_MANAGER_INTERFACE  *Manager
   -- Manager interface pointer
IN CMOS_ACCESS_TYPE AccessType
   -- Specifies whether to perform a read or a write
IN UINT8 CmosAddress
   -- Actual CMOS address/offset
IN UINT8 BitsToWrite
   -- Mask specifying the bits to be written (these
      bits will be cleared first)
IN OUT UINT8 *CmosParameterValue
   -- CMOS value to be written or, on successful exit, will
      contain the value that was read
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS if successful
   = or other valid EFI error code
Notes:

Control comes here because of one of two reasons:

1) The checksum is bad

   All writes/read are to/from the
   Manager->OptimalDefaultTable only for locations not found
   in the Manager->NoChecksumTable until DXE phase.

2) The battery is bad

   All writes/read are to/from the
   Manager->OptimalDefaultTable for all locations.


CmosFindToken in the CmosAccess.c

Function : CmosFindToken

File: CmosAccess.c
Description:
Returns index of CMOS token in token table or 0 if not found.
Input:
IN  EFI_CMOS_MANAGER_INTERFACE *Manager
   -- This is the CMOS Manager interface pointer.
IN  UINT16 CmosToken
   -- Encoded CMOS token for which to locate an index into
      the CMOS token table
Output:
UINT16 (Return Value)
   = Index of the CmosToken in the token table, or
   = 0, if the CmosToken was not found
Notes:
None


CmosGetDateTime in the CmosAccess.c

Function : CmosGetDateTime

File: CmosAccess.c
Description:
Return the current date and time
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Manager
   -- The Manger interface pointer.
OUT EFI_TIME *Time
   -- EFI Time structure
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS or valid EFI error code


CmosGetTokenFromRegister in the CmosAccess.c

Function : CmosGetTokenFromRegister

File: CmosAccess.c
Description:
Returns encoded token for the specified register.
Input:
IN  EFI_CMOS_MANAGER_INTERFACE *Manager
   -- This is the CMOS Manager interface pointer.
IN  UINT8 CmosRegister
   -- CMOS register to for which to search
Output:
UINT16 (Return Value)
   = Token found in the token table, or
   = 0, if the Register was not found
Notes:

Caller must ensure the register has been reserved properly
in SSP.

This should be considered a risky function call and extra care
should be taken to ensure the proper CmosRegister is specified.

This function has the potential for problems, as it is possible that
a specified CmosRegister has not been defined in SSP and/or may
be used by another CmosToken.

All verification of parameters must be done by the caller.


CmosMgrReadRtcIndex in the CmosAccess.c

Function : CmosMgrReadRtcIndex

File: CmosAccess.c
Description:
Read the RTC value at the given Index.
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Mgr
   -- The Manger interface pointer.
IN UINT8 Index
Output:
UINT8 (return value) --
   = RTC Value read from the provided Index
Notes:
Here is the control flow of this function:
1. Read port 0x70 (RTC Index Register) to get bit 7.
   Bit 7 is the NMI bit-it should not be changed.
2. Output 0x70 with the Index and NMI bit setting.
3. Read 0x71 for Data. Getting Dec when appropriate.
4. Return the Data.


CmosMgrWriteRtcIndex in the CmosAccess.c

Function : CmosMgrWriteRtcIndex

File: CmosAccess.c
Description:
Write the RTC value at the given Index.
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Mgr
   -- The Manger interface pointer.
IN UINT8 Index
   -- Index to write
IN UINT8 Value
   -- Value to write
Output:
None
Notes:
Here is the control flow of this function:
1. Read port 0x70 (RTC Index Register) to get bit 7.
  Bit 7 is the NMI bit-it should not be changed.
2. Output 0x70 with the Index. Switch to BCD when needed.
3. Write the data to 0x71.


CmosPhysicalReadWrite in the CmosAccess.c

Function : CmosPhysicalReadWrite

File: CmosAccess.c
Description:
This function provides support for performing the actual
read or write from/to a physical CMOS location.
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Manager
   -- Manager interface pointer
IN CMOS_ACCESS_TYPE AccessType
   -- Specifies whether to perform a read or a write
IN UINT8 CmosAddress
   -- Actual CMOS address/offset
IN UINT8 BitsToWrite
   -- Mask specifying the bits to be written (these
       bits will be cleared first)
IN OUT  UINT8 *CmosParameterValue
   -- CMOS value to be written or, on successful exit, will
       contain the value that was read
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS if successful
   = or other valid EFI error code
Notes:
None


CmosRead in the CmosAccess.c

Function : CmosRead

File: CmosAccess.c
Description:
Reads to CmosValue from the CMOS location specified by CmosToken.
Input:
IN  EFI_CMOS_ACCESS_INTERFACE *Cmos
   -- This is the access interface pointer.
IN  UINT16 CmosToken
   -- This is the encoded CMOS location.
OUT UINT8 *CmosValue
   -- On success, this will contain the value at
       the specified CMOS location.
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS if successful
   = EFI_NOT_FOUND, if the token is not in the token table
   = or other valid EFI error code
Notes:
None


CmosReadWrite in the CmosAccess.c

Function : CmosReadWrite

File: CmosAccess.c
Description:
Decides which version of xxxReadWrite to call based upon the
current Access Routing Logic.
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Manager
   -- Manager interface pointer
IN CMOS_ACCESS_TYPE AccessType
   -- Specifies whether to perform a read or a write
IN UINT8 CmosAddress
   -- Actual CMOS address/offset
IN UINT8 BitsToWrite
   -- Mask specifying the bits to be written (these
       bits will be cleared first)
IN OUT  UINT8 *CmosParameter
   -- CMOS value to be written or, on successful exit, will
       contain the value that was read
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS or valid EFI error code
Notes:
None


CmosReadWriteEncodedToken in the CmosAccess.c

Function : CmosReadWriteEncodedToken

File: CmosAccess.c
Description:
This is the main worker function which verifies and either
reads/writes a value from/to the CMOS location as specified by the
encoded token.
Input:
IN      EFI_CMOS_MANAGER_INTERFACE *Manager
   -- This is the CMOS Manager interface pointer.
IN      CMOS_ACCESS_TYPE AccessType
   -- Specifies whether to perform a read or a write
IN      UINT16 TokenTableIndex
   -- Index into the token table
IN OUT  UINT8 *CmosParameter
   -- CMOS value to be written or, on successful exit, will
       contain the value that was read
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS if successful
   = EFI_INVALID_PARAMETER, if the CmosParameter does
       not comply with the expected size
   = or other valid EFI error code
Notes:
   1) Gets the CMOS token from the global table
   2) If writing, the value is error-checked for size and
       up-shifted to the correct bit position. Also, the
       BitsToWrite mask is used to specify
       which bits to clear in the destination before
       writing.
   3) This token is decoded to get the CMOS index,
   4) The read/write is performed
   5) If reading, the value is down-shifted and masked to
       return the expected value.


CmosSetDateTime in the CmosAccess.c

Function : CmosSetDateTime

File: CmosAccess.c
Description:
This routine simply writes the CMOS RTC registers from information
provided by the EFI_TIME structure, assuming the information is
correct.
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Manager
   -- The Manger interface pointer.
IN EFI_TIME *Time
   -- EFI Time structure
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS or valid EFI error code
Modified:
N/A
Notes:
Data is assumed to be valid.  Only a simple check for NULL pointer
is done.


CmosWrite in the CmosAccess.c

Function : CmosWrite

File: CmosAccess.c
Description:
Writes from CmosValue to CMOS location encoded into CmosToken.
Input:
IN  EFI_CMOS_ACCESS_INTERFACE *Cmos
   -- This is the access interface pointer.
IN  UINT16 CmosToken
   -- This is the encoded CMOS location.
IN  UINT8 CmosValue
   -- On success, this value will be written to
       the specified CMOS location.
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS if successful
   = EFI_NOT_FOUND, if the token is not in the token table
   = or other valid EFI error code
Notes:
None


DecodeParameter in the CmosAccess.c

Function : DecodeParameter

File: CmosAccess.c
Description:
Value is shifted right and masked by the bit field's size and offset
as specified in Token.
Input:
OUT UINT8 *Value
   -- Address of value to be decoded
IN CMOS_TOKEN *Token
   -- Token describing the bit field's size and offset
Notes:
None


EncodeParameter in the CmosAccess.c

Function : EncodeParameter

File: CmosAccess.c
Description:
Value is shifted left by the bit field size specified in Token.
Input:
OUT UINT8 *Value
   -- Address of value to be encoded
IN CMOS_TOKEN *Token
   -- Token describing the bit field size
Notes:
None


LoadOptimalDefaults in the CmosAccess.c

Function : LoadOptimalDefaults

File: CmosAccess.c
Description:
Initialize all physical CMOS registers with the default values
specified in NvramField's Default value.
Input:
IN  EFI_CMOS_MANAGER_INTERFACE *Manager
   -- The Manger interface pointer.
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS or valid EFI error code
Modified:
Manager->ManagerStatus bits:
          CMOS_BAD_CHECKSUM - cleared on success
CMOS_ERROR_LOADING_DEFAULTS - set on error
Notes:
LoadOptimalDefaults will be called for one of two reasons:

1) On the first boot after flashing the ROM, the default
values will be written to all CMOS registers, regardless
of whether or not they are listed in the NoChecksumTable.

2) If a bad checksum is reported in PEI, the
OptimalDefaultTable will be used as a read/write buffer
until DXE, where (by default) the CMOS_BAD_CHECKSUM status bit will
signal to write the buffer to physical CMOS.

* The optimal defaults buffer may be modified from the original
version if CMOS_OPTIMAL_DEFAULTS_ENABLED status bit is set.

* If the CMOS_BAD_CHECKSUM status is set, then only those values
included in the checksum are written to physical CMOS.


NotChecksummed in the CmosAccess.c

Function : NotChecksummed

File: CmosAccess.c
Description:
This function returns TRUE if the CmosAddress is NOT included in the
checksum and returns FALSE otherwise.
Input:
IN EFI_CMOS_MANAGER_INTERFACE  *Manager
   -- Manager interface pointer
IN UINT8 CmosAddress
   -- Actual CMOS address/offset
Output:
BOOLEAN (Return Value)
   = TRUE if CmosAddress is NOT included in the checksum
   = FALSE if CmosAddress IS included in the checksum


ReadChecksum in the CmosAccess.c

Function : ReadChecksum

File: CmosAccess.c
Description:
Reads the checksum from the CMOS register(s).
Input:
IN  EFI_CMOS_MANAGER_INTERFACE *Manager
   -- Manger interface pointer.
OUT UINT16 *ChecksumValue
   -- The returned checksum value
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS or valid EFI error code
Notes:
None


ReadCmosBytes in the CmosAccess.c

Function : ReadCmosBytes

File: CmosAccess.c
Description:
Reads Bytes from the specified CMOS register(s).
Input:
IN  EFI_CMOS_MANAGER_INTERFACE *Manager
   -- Manger interface pointer.
IN UINT8 Count
   -- Count of CMOS_BYTEs to read
OUT CMOS_BYTE *Bytes
   -- An array of CMOS_BYTE structures
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS or valid EFI error code
Notes:
None


ReadCmosStatusBytes in the CmosAccess.c

Function : ReadCmosStatusBytes

File: CmosAccess.c
Description:
Initializes a CMOS_STATUS_BYTES structure and reads the associated
CMOS registers.
Input:
IN  EFI_CMOS_ACCESS_INTERFACE *Cmos
   --  Manger interface pointer.
OUT CMOS_STATUS_BYTES *StatusBytes
   --  Address of a valid, uninitialized, CMOS_STATUS_BYTES
       structure.
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS or valid EFI error code
Notes:


SetClobberBits in the CmosAccess.c

Function : SetClobberBits

File: CmosAccess.c
Description:
Creates a mask with bits set corresponding to the size and offset
of the bit field as specified by Token.
Input:
OUT UINT8 *Mask
   -- Mask to be created
IN CMOS_TOKEN *Token
   -- Token describing the bit field's size and offset
Notes:
None


StartTime in the CmosAccess.c

Function : StartTime

File: CmosAccess.c
Description:
Start the time on RTC clock. This is used when changing the
Date and Time
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Mgr
   -- The Manger interface pointer.
Output:
None
Notes:
Here is the control flow of this function:
1. Start the time by clearing bit 7 on RTC register 0xb.


StopTime in the CmosAccess.c

Function : StopTime

File: CmosAccess.c
Description:
Stops the time on RTC clock.
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Mgr
   -- The Manger interface pointer.
Output:
None
Notes:
Here is the control flow of this function:
1. Stop the time by setting bit 7 on RTC register 0xb.


SynchronizeLegacyStatusRegisters in the CmosAccess.c

Function : SynchronizeLegacyStatusRegisters

File: CmosAccess.c
Description:
Synchronizes legacy CMOS status registers with status changes.
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Manager
   -- Manger interface pointer
IN CMOS_MANAGER_STATUS BitMap
   -- The status bits to be modified
IN CMOS_BIT_ACCESS_TYPE AccessType
   -- Specifies whether to set or clear the bits
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS or valid EFI error code
Notes:
The BitMap contains all the bits to be modified in the legacy
status registers.

If CMOS_LEGACY_STATUS_ENABLED is off, or is being turned off, this
function will not modify CMOS registers.

Failure status bits in CMOS_DIAGNOSTIC_STATUS_REGISTER can only be
cleared if this is the first boot or if executing in the DXE phase.


UpdateBatteryStatus in the CmosAccess.c

Function : UpdateBatteryStatus

File: CmosAccess.c
Description:
This function is used to update the CMOS battery status.  It is up
to the user of the Manager interface to determine whether or ot
the platform supports this feature.  (If the platform does not
support this feature, the battery status is indeterminate.)
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Manager
   -- Pointer to the Manager's interface
Output:
EFI_STATUS (Return value)
   = EFI_SUCCESS or valid EFI error code
Notes:


WriteChecksum in the CmosAccess.c

Function : WriteChecksum

File: CmosAccess.c
Description:
Write the checksum to the CMOS register(s).
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Manager
   -- Manger interface pointer.
IN UINT16 ChecksumValue
   -- Value to write to the checksum location.
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS or valid EFI error code
Notes:
None


CmosAccess.h

Description:
This file provides declarations for CMOS access functions
for reading CMOS memory.

The following functions are used in the file: CmosAccess.h.

Function | Description
LOCATE_CMOS_ACCESS_API_POINTER | This Macro initializes InterfacePtr = NULL if the battery is bad. Otherwise, read the four bytes of the CMOS-based API pointer into InterfacePtr, starting at CMOS_ACCESS_API_BYTE3.
LOCATE_CMOS_ACCESS_PPI | This Macro calls (*PeiServices)->LocatePpi() to locate the CMOS access PPI.
LOCATE_CMOS_ACCESS_PROTOCOL | This Macro calls pBS->LocateProtocol() to locate the CMOS access Protocol.
LOCATE_CMOS_ACCESS_SMM_PROTOCOL | This Macro calls pBS->LocateProtocol() to locate the CMOS access Protocol for SMM access to CMOS.

The following data structures are used in the file: CmosAccess.h.

Variable | Description
CMOS_STATUS_BYTES | This structure type is used to define particular CMOS status bytes.
EFI_CMOS_ACCESS_INTERFACE | This is the external interface to all the functionality provided by the CMOS Manager to external modules.

The following descriptions are used in the file: CmosAccess.h.

Header | Description
CMOS_Manager_Initialization_and_Usage | This page provides an outline of the steps required for CMOS Manager initialization and services usage.
Macros | The page provides links to Macros that can be used by CMOS Manager client modules.
Protocols_and_PPI | This page provides links to the Protocols and PPI installed by this module. These are the external interfaces to the CMOS Manager module's services.
Terms | This page defines/clarifies the implied/intended meaning for the terminology used in the CMOS Manager module's documentation.


CMOS_Manager_Initialization_and_Usage in the CmosAccess.h

General : CMOS_Manager_Initialization_and_Usage

File: CmosAccess.h
Description:
This page provides an outline of the steps required for CMOS Manager
initialization and services usage.
Notes:
Overview of CMOS Manager usage:

   1)  Include CmosAccess.h.

   2)  Declare a pointer to EFI_CMOS_ACCESS_INTERFACE.

   3)  Use the appropriate macro to locate the interface,
         LOCATE_CMOS_ACCESS_PPI(),
         LOCATE_CMOS_ACCESS_API_POINTER(),
         LOCATE_CMOS_ACCESS_PROTOCOL() or
         LOCATE_CMOS_ACCESS_SMM_PROTOCOL()

   4)  Use the interface to access CMOS.

   Note:   Be sure to check the return value of each call!
Built on 11:30:58 01/27/12


CMOS_STATUS_BYTES in the CmosAccess.h

Variable : CMOS_STATUS_BYTES

File: CmosAccess.h
Fields:

Type | Name | Description
UINT8 | DiagnosticStatusRegister | Address of the diagnostic status register
DIAGNOSTIC_STATUS_BYTE | Diagnostic | CMOS register that contains clock & checksum information
UINT8 | BatteryStatusRegister | Address of the battery status register
BATTERY_STATUS_BYTE | Battery | CMOS register that contains CMOS battery information
CMOS_STATUS_BYTES | ConfigurationStatus | State information for the CMOS manager's access mechanisms

Description:
This structure type is used to define particular CMOS status bytes.
Notes:
The bit-field naming convention affirms the bit-set condition, so that TRUE
conditions can be tested.  For example, here is one possible usage
scenario:

   CMOS_STATUS_BYTES CmosStatus;
   MyGetStatusBytes(&CmosStatus);

   if (CmosStatus.Diagnostic.Field.ChecksumIsBad)
       MyInitiateRecovery();

The union provides access to all the bits of the CMOS byte or to
a specific data field within the byte:

Battery.AllBits                  All bits of the battery status byte
Battery.Field.IsGood             Bit is set if battery is good

Diagnostic.AllBits               All bits of the diagnostics status byte
Diagnostic.Field.TimeIsInvalid   Bit is set if time is invalid
Diagnostic.Field.ChecksumIsBad   Bit is set if checksum is bad
Diagnostic.Field.RtcPowerIsBad   Bit is set if real time clock has lost power

ConfigurationStatus.IsVirtualized Bit is set if the optimal defaults buffer is in use
Built on 11:30:58 01/27/12


EFI_CMOS_ACCESS_INTERFACE in the CmosAccess.h

Variable : EFI_CMOS_ACCESS_INTERFACE

File: CmosAccess.h
Fields:

Type | Name | Description
EFI_PEI_SERVICES | **PeiServices | pointer to the PEI services table
EFI_CMOS_READ | Read | read a value from a CMOS register (see CmosRead)
EFI_CMOS_WRITE | Write | write a value to a CMOS register (see CmosWrite)
EFI_CMOS_GET_TOKEN_FROM_REGISTER | GetTokenFromRegister | returns the token from the register address (see CmosGetTokenFromRegister)
EFI_CMOS_READ_STATUS_BYTES | ReadCmosStatusBytes | updates a CMOS_STATUS_BYTES structure
EFI_CMOS_GET_DATE_TIME | GetTime | Reads the RTC CMOS registers and updates the EFI_TIME structure output parameter (see CmosGetDateTime)
EFI_CMOS_SET_DATE_TIME | SetTime | Writes the RTC CMOS registers from information in the EFI_TIME input parameter (see CmosSetDateTime)
EFI_HANDLE | *Oem | provide interface extensibility

Description:
This is the external interface to all the functionality provided by
the CMOS Manager to external modules.
Notes:
The user of this interface should check the returns of all functions
and take the appropriate action if an error is returned.

Important!! changes in this structure must also be implemented in
   CmosAccess32.inc (EFI_CMOS_ACCESS_INTERFACE struct).


LOCATE_CMOS_ACCESS_API_POINTER in the CmosAccess.h

Function : LOCATE_CMOS_ACCESS_API_POINTER

File: CmosAccess.h
Description:
This Macro initializes InterfacePtr = NULL if the battery is bad.
Otherwise, read the four bytes of the CMOS-based API pointer into
InterfacePtr, starting at CMOS_ACCESS_API_BYTE3.
Input:
IN OUT InterfacePtr - Pointer whose value will be updated
Output:
Modified:
Notes:

Referrals:

IoRead8, IoWrite8


LOCATE_CMOS_ACCESS_PPI in the CmosAccess.h

Function : LOCATE_CMOS_ACCESS_PPI

File: CmosAccess.h
Description:
This Macro calls (*PeiServices)->LocatePpi() to locate the CMOS
access PPI.
Input:
IN OUT  InterfacePtr - Pointer whose value will be updated
OUT     Status - Return value from LocatePpi()
Output:
Modified:
Notes:
This macro assumes PeiServices is defined.
Referrals:
(*PeiServices)->LocatePpi


LOCATE_CMOS_ACCESS_PROTOCOL in the CmosAccess.h

Function : LOCATE_CMOS_ACCESS_PROTOCOL

File: CmosAccess.h
Description:
This Macro calls pBS->LocateProtocol() to locate the CMOS access
Protocol.
Input:
IN OUT  InterfacePtr - Pointer whose value will be updated
OUT     Status - Return value from LocateProtocol()
Output:
Modified:
Notes:
This macro assumes pBS is defined.
Referrals:
pBS->LocateProtocol


LOCATE_CMOS_ACCESS_SMM_PROTOCOL in the CmosAccess.h

Function : LOCATE_CMOS_ACCESS_SMM_PROTOCOL

File: CmosAccess.h
Description:
This Macro calls pBS->LocateProtocol() to locate the CMOS access
Protocol for SMM access to CMOS.
Input:
IN OUT  InterfacePtr - Pointer whose value will be updated
OUT     Status - Return value from LocateProtocol()
Output:
Modified:
Notes:
This macro assumes pBS is defined.
Referrals:
pBS->LocateProtocol


Macros in the CmosAccess.h

General : Macros

File: CmosAccess.h
Fields:

Phase | Name | Description
PEI | READ_CMOS_PPI | Use the CMOS Access PPI to read a value from CMOS using a CMOS token from assembly source
PEI | WRITE_CMOS_PPI | Use the CMOS Access PPI to write a value to CMOS using a CMOS token from assembly source
PEI | READ_CMOS_TOKEN | Use the CMOS-based API/PPI pointer to read a value from CMOS using a CMOS token from assembly source
PEI | WRITE_CMOS_TOKEN | Use the CMOS-based API/PPI pointer to write a value to CMOS using a CMOS token from assembly source
PEI | READ_CMOS_REGISTER | Use the CMOS-based API/PPI pointer to read a value from CMOS using a CMOS token from assembly source
PEI | WRITE_CMOS_REGISTER | Use the CMOS-based API/PPI pointer to write a value to CMOS using a CMOS token from assembly source
PEI | LOCATE_CMOS_ACCESS_API_POINTER | Get CMOS-based API/PPI pointer
PEI | LOCATE_CMOS_ACCESS_PPI | Get CMOS Access PPI pointer
DXE | LOCATE_CMOS_ACCESS_PROTOCOL | Get CMOS Access Protocol pointer

Description:
The page provides links to Macros that can be used by CMOS Manager
client modules.


Protocols_and_PPI in the CmosAccess.h

General : Protocols_and_PPI

File: CmosAccess.h
Fields:

Phase | Name | Description
All | EFI_CMOS_ACCESS_INTERFACE | Client interface installed by CMOS Manager

Description:
This page provides links to the Protocols and PPI installed by this
module.  These are the external interfaces to the CMOS Manager
module's services.


Terms in the CmosAccess.h

General : Terms

File: CmosAccess.h
Description:
This page defines/clarifies the implied/intended meaning for the
terminology used in the CMOS Manager module's documentation.
Notes:
Manager -
   Refers to the entire collection of subsystems that compose
   the CMOS Manager module, including internal and external
   interfaces.

Access Interface -
   The collection of public services (functions/data) provided
   by the Manager through the EFI_CMOS_ACCESS_INTERFACE
   PPI/Protocol.

API Pointer -
   A CMOS-based EFI_CMOS_ACCESS_INTERFACE pointer that is
   maintained until DXE phase.  This pointer can be utilized
   via Macros defined in an assembly include and/or C-source
   header file.

External/Internal Interface -
   The external interface is the set of functions/data
   available to other modules, via the Access Interface.
   The Internal Interface is the set of functions/data
   used by the Manager itself, specifically the
   EFI_CMOS_MANAGER_INTERFACE.  Generally speaking, the
   External Interface is a subset of the Internal Interface.

Client -
   A module that locates the Access Interface and uses the
   services provided by the CMOS Manager module via this
   external interface.

Managed CMOS -
   Describes the paradigm of using the CMOS Manager to access
   a predefined region of CMOS locations.

Managed Region -
   The region of physical CMOS locations for which CMOS
   Manager provides its allocation/access services.
   This region is represented as a contiguous region of
   locations, where the range is defined by SDL Tokens
   (FIRST_MANAGED_CMOS_ADDRESS and MAX_MANAGED_CMOS_ADDRESS).

CMOS Value -
   This is one or more bits of data that will be stored at a
   location in CMOS.  The maximum size of a CMOS value is
   8 bits.

CMOS Token -
   This is an encoded value that represents the location,
   size in bits, and offset within the CMOS byte for a
   particular CMOS value.


CmosAccess32.inc

Description:
This file contains Macros, constants, procedure definitions and structure
declarations to be used in 32-bit assembly code.

The following functions are used in the file: CmosAccess32.inc.

Function | Description
GetPointerCmos32 | This routine returns the 32-bit value stored in CMOS where the high byte starts at location specified by register AL.
MaReadCmosByte | Reads a byte from the CMOS location specified by AL.
READ_CMOS_PPI | This macro calls EFI_CMOS_ACCESS_INTERFACE.Read() to read the CMOS location associated with CmosToken into the value byte at the address specified by CmosValuePtr, after pushing the required arguments onto the stack.
READ_CMOS_REGISTER | This macro calls ReadWriteCmosRegister to read the physical CMOS register specified by CmosRegister into the value byte at the address specified by CmosValuePtr, after pushing the required arguments onto the stack.
READ_CMOS_TOKEN | This macro invokes ReadWriteCmosToken() to read the CMOS location associated with CmosToken into the value byte at the address specified by CmosValuePtr, after pushing the required arguments onto the stack.
ReadWriteCmosRegister | This function calls EFI_CMOS_ACCESS_INTERFACE.Write or EFI_CMOS_ACCESS_INTERFACE.Read to write or read a CMOS value to a CMOS register.
ReadWriteCmosToken | This function calls EFI_CMOS_ACCESS_INTERFACE.Write or EFI_CMOS_ACCESS_INTERFACE.Read to write or read a CMOS value to a CMOS register.
WRITE_CMOS_PPI | This macro calls EFI_CMOS_ACCESS_INTERFACE.Write() to write the the value specified by CmosValue to the CMOS location associated with CmosToken, after pushing the required arguments onto the stack.
WRITE_CMOS_REGISTER | This macro calls ReadWriteCmosRegister to write the value specified by CmosValue to the physical CMOS location specified by CmosRegister after pushing the required arguments onto the stack.
WRITE_CMOS_TOKEN | This macro invokes ReadWriteCmosToken() to write the byte specified by CmosValue to the CMOS location associated with CmosToken, after pushing the required arguments onto the stack.


GetPointerCmos32 in the CmosAccess32.inc

Function : GetPointerCmos32

File: CmosAccess32.inc
Description:
This routine returns the 32-bit value stored in CMOS where the high
byte starts at location specified by register AL.
Input:
AL =        Upper byte register (reads upper to lower bytes in
    increasing register addresses)
Output:
EAX = 32bit value stored in CMOS
CF = set if error (EAX = Error code)
CF = clear if success
Modified:
None
Notes:
This function is defined to be called from C or assembly.
Referrals:
MaReadCmosByte


MaReadCmosByte in the CmosAccess32.inc

Function : MaReadCmosByte

File: CmosAccess32.inc
Description:
Reads a byte from the CMOS location specified by AL.
Input:
AL - CMOS location
Output:
AH - Value at CMOS location specified by AL


READ_CMOS_PPI in the CmosAccess32.inc

Function : READ_CMOS_PPI

File: CmosAccess32.inc
Description:
This macro calls EFI_CMOS_ACCESS_INTERFACE.Read() to read the CMOS
location associated with CmosToken into the value byte at the address
specified by CmosValuePtr, after pushing the required arguments onto
the stack.
Input:
Cmos - pointer to an instance of EFI_CMOS_ACCESS_INTERFACE
CmosToken - valid CMOS Token as defined in TokenEqu.equ
Output:
CmosValuePtr
    -  the byte value at this address is updated upon
       successful execution
eax - EFI error code if bit 31 is set
Modified:
mm0 - destroyed
Notes:

Example usage:

    lea   ecx, CmosValue
    READ_CMOS_PPI   CmosPpiPtr, CMOS_S3_COUNT_LOC, ecx
    .if (eax != 0)
        ; handle error
    .endif


READ_CMOS_REGISTER in the CmosAccess32.inc

Function : READ_CMOS_REGISTER

File: CmosAccess32.inc
Description:
This macro calls ReadWriteCmosRegister to read the physical CMOS
register specified by CmosRegister into the value byte at the address
specified by CmosValuePtr, after pushing the required arguments onto
the stack.
Input:
CmosRegister - the physical CMOS register to read (not a CMOS token)
Output:
CmosValuePtr - the byte value at this address is updated upon
               successful execution
eax - EFI_STATUS
Notes:

Caller must ensure the entire 8-bits of the register have been
reserved properly/explicitly in SSP.

Example call:

    lea   ecx, CmosValue
    READ_CMOS_REGISTER   CMOS_S3_COUNT_LOC_REG, ecx
    .if (eax != 0)
        ; handle error
    .endif


READ_CMOS_TOKEN in the CmosAccess32.inc

Function : READ_CMOS_TOKEN

File: CmosAccess32.inc
Description:
This macro invokes ReadWriteCmosToken() to read the CMOS location
associated with CmosToken into the value byte at the address
specified by CmosValuePtr, after pushing the required arguments onto
the stack.
Input:
CmosToken - valid CMOS token as defined in TokenEqu.equ
Output:
CmosValuePtr -  the byte value at this address is updated upon
                successful execution
eax - CMOS_BATTERY_ERR if battery is bad
eax - EFI error code if bit 31 is set
Notes:

Example call:

    lea   ecx, CmosValue
    READ_CMOS_TOKEN   CMOS_S3_COUNT_LOC, ecx
    .if (eax != 0)
        ; handle error
    .endif


ReadWriteCmosRegister in the CmosAccess32.inc

Function : ReadWriteCmosRegister

File: CmosAccess32.inc
Description:
This function calls EFI_CMOS_ACCESS_INTERFACE.Write or
EFI_CMOS_ACCESS_INTERFACE.Read to write or read a CMOS value to
a CMOS register.
Input:
AccessType - CMOS_WRITE_ACCESS or CMOS_READ_ACCESS (equate)
CmosRegister - the CMOS register to write (this is not a CMOS token)
CmosValue - value to be written or the return value of the read
Output:
eax - CMOS_BATTERY_ERR if battery is bad
eax - EFI error code if bit 31 is set
carry flag - clear on success or set on error
Notes:

Caller must ensure the register has been reserved & specified properly
in SSP.


ReadWriteCmosToken in the CmosAccess32.inc

Function : ReadWriteCmosToken

File: CmosAccess32.inc
Description:
This function calls EFI_CMOS_ACCESS_INTERFACE.Write or
EFI_CMOS_ACCESS_INTERFACE.Read to write or read a CMOS value to
a CMOS register.
Input:
AccessType - CMOS_WRITE_ACCESS or CMOS_READ_ACCESS (equate)
CmosToken - the encoded CMOS token (not a CMOS register)
CmosValue - value to be written or the return value of the read
Output:
eax - CMOS_BATTERY_ERR if battery is bad
eax - EFI error code if bit 31 is set
Notes:

Caller must ensure the register has been reserved & specified properly
in SSP.


WRITE_CMOS_PPI in the CmosAccess32.inc

Function : WRITE_CMOS_PPI

File: CmosAccess32.inc
Description:
This macro calls EFI_CMOS_ACCESS_INTERFACE.Write() to write the
the value specified by CmosValue to the CMOS location associated with
CmosToken, after pushing the required arguments onto the stack.
Input:
Cmos - pointer to an instance of EFI_CMOS_ACCESS_INTERFACE
CmosToken - valid CMOS Token as defined in TokenEqu.equ
CmosValue - Byte value to write to the location associated with
            CmosToken
Output:
eax - EFI_STATUS
Modified:
mm0 - destroyed (used as temporary register if needed)
Notes:

Example usage:

    mov   cl, CmosTokenValue
    WRITE_CMOS_PPI   CmosPpiPtr, CMOS_S3_COUNT_LOC, cl
    .if (eax != 0)
        ; handle error
    .endif


WRITE_CMOS_REGISTER in the CmosAccess32.inc

Function : WRITE_CMOS_REGISTER

File: CmosAccess32.inc
Description:
This macro calls ReadWriteCmosRegister to write the value specified
by CmosValue to the physical CMOS location specified by CmosRegister
after pushing the required arguments onto the stack.
Input:
CmosRegister - the physical CMOS register to write (not a CMOS token)
CmosValue - byte value to write to CmosRegister
Output:
eax - EFI_STATUS
Modified:
mm0 - destroyed
Notes:
Caller must ensure the entire 8-bits of the register have been
reserved properly/explicitly in SSP.

Example usage:

    mov   cl, CmosValue
    WRITE_CMOS_REGISTER   S3_COUNT_LOC_REG, cl
    .if (eax != 0)
        ; handle error
    .endif


WRITE_CMOS_TOKEN in the CmosAccess32.inc

Function : WRITE_CMOS_TOKEN

File: CmosAccess32.inc
Description:
This macro invokes ReadWriteCmosToken() to write the byte specified
by CmosValue to the CMOS location associated with CmosToken,
after pushing the required arguments onto the stack.
Input:
CmosToken - valid CMOS Token as defined in TokenEqu.equ
CmosValue - Byte value to write to the location associated with
            CmosToken
Output:
eax - EFI_STATUS
Modified:
mm0 - destroyed (used as temporary register if needed)
Notes:

Example usage:

    mov   cl, TokenValue
    WRITE_CMOS_TOKEN   CMOS_S3_COUNT_LOC, cl
    .if (eax != 0)
        ; handle error
    .endif


CmosAccessSec.inc

Description:
This file contains Macros, constants, procedure definitions and structure
declarations to be used in SEC phase assembly code.


CmosBoard.c

Description:
Contains routines that are board-specific.

The following functions are used in the file: CmosBoard.c.

Function | Description
CmosIsUsable | This function determines whether or not the CMOS is usable. It may be possible to use the CMOS even if the battery is bad.
CmosMgrBatteryIsGood | This function is used to determing whether or not the CMOS battery is good.
CmosMgrIsBsp | This function returns TRUE if the currently executing CPU core is the boot strap processor (BSP).
CmosMgrIsColdBoot | This function returns TRUE to specify the platform is always perfoming a cold boot.
CmosMgrIsFirstBoot | This function determines whether or not this is the first boot after programming the boot device (flash part, ROM emulator, ...).
ReadWriteStandardRange | This function is used to access addresses in the Standard CMOS register range (0x0-0x7f), for PEI and DXE boot phases.


CmosIsUsable in the CmosBoard.c

Function : CmosIsUsable

File: CmosBoard.c
Description:
This function determines whether or not the CMOS is usable. It may
be possible to use the CMOS even if the battery is bad.
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Manager
   -- Pointer to the Manager's interface
Output:
BOOLEAN (Return value)
   = TRUE - CMOS is usable
   = FALSE - CMOS is not usable
Notes:
Typically, register 0xd can be used to determine whether or not
CMOS is usable.  It may be possible to use the CMOS for reads/writes
if the battery is bad.


CmosMgrBatteryIsGood in the CmosBoard.c

Function : CmosMgrBatteryIsGood

File: CmosBoard.c
Description:
This function is used to determing whether or not the CMOS battery is
good.
Input:
IN EFI_PEI_SERVICES **PeiServices
   --  Pointer to the PEI services table.  (This pointer
       is NULL in the DXE phase.)
Output:
BOOLEAN (Return Value)
   = TRUE if the battery is good
   = TRUE if the battery is bad
Modified:
None
Notes:
Some chipsets need to check a PCI configuration space
register to determine the RTC power status.
Referrals:
IoRead8, IoWrite8


CmosMgrIsBsp in the CmosBoard.c

Function : CmosMgrIsBsp

File: CmosBoard.c
Description:
This function returns TRUE if the currently executing CPU core
is the boot strap processor (BSP).
Input:
IN  EFI_PEI_SERVICES  **PeiServices
   --  Pointer to the PEI services table.  (This pointer
       is NULL in the DXE phase.)
Output:
BOOLEAN (Return Value)
   = TRUE, the BSP is executing
   = FALSE, otherwise
Notes:
For some chipsets, this functions may need to be replaced.


CmosMgrIsColdBoot in the CmosBoard.c

Function : CmosMgrIsColdBoot

File: CmosBoard.c
Description:
This function returns TRUE to specify the platform is always perfoming
a cold boot.
Input:
IN  EFI_PEI_SERVICES  **PeiServices
   --  Pointer to the PEI services table.  (This pointer
       is NULL in the DXE phase.)
Output:
BOOLEAN (Return Value)
   = TRUE
Notes:
For some chipsets, this functions may need to be replaced.


CmosMgrIsFirstBoot in the CmosBoard.c

Function : CmosMgrIsFirstBoot

File: CmosBoard.c
Description:
This function determines whether or not this is the first boot after
programming the boot device (flash part, ROM emulator, ...).
Input:
IN  EFI_PEI_SERVICES **PeiServices
   --  Pointer to the PEI services table.  (This pointer
       is NULL in the DXE phase.)
Output:
BOOLEAN (Return Value)
   = TRUE, if this is the first boot
   = FALSE, otherwise
Notes:
For some chipsets, there may be additional issues to consider,
such as warm reboot during the PEI phase, multiple processor threads
and so on.  Therefore, this function can be implemented by an external
module (typically the Southbridge module).


ReadWriteStandardRange in the CmosBoard.c

Function : ReadWriteStandardRange

File: CmosBoard.c
Description:
This function is used to access addresses in the Standard CMOS
register range (0x0-0x7f), for PEI and DXE boot phases.
Input:
IN EFI_PEI_SERVICES **PeiServices
   --  PEI Services table pointer (NULL in DXE phase)
IN CMOS_ACCESS_TYPE AccessType
   --  ReadType or WriteType to specify the type of access
IN UINT16 CmosRegister
   --  The CMOS register to access
IN OUT UINT8 *CmosParameterValue
   -- Pointer to the data variable to be accessed
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS if successful
   = or other valid EFI error code
Modified:
None
Notes:
N/A
Referrals:
IoRead8, IoWrite8


CmosBoard.h

Description:
Contains the routines that constitute the CMOS access
implementation.  This file contains source code that is used
for both PEI and DXE phases.


CmosBoard.sdl

Description:
This AMI SDL file defines porting constants used in
the CMOS Board subcomponent.

The following data structures are used in the file: CmosBoard.sdl.

Variable | Description
CMOS_BANK0_DATA | Default value is 0x71 Data I/O port to access CMOS registers in range: 0x0-0x7f.
CMOS_BANK0_INDEX | Default value is 0x70 Index I/O port to access CMOS registers in range: 0x0-0x7f.
CMOS_BATTERY_TEST_MAPPING | The default function is CmosMgrBatteryIsGood. This SDL eLink provides a mechanism to replace the default function for determining whether or not the battery is bad.
CMOS_IS_BSP_MAPPING | The default function is CmosMgrIsBsp. This SDL eLink provides a mechanism to replace the default function for determining whether or not the currently executing CPU core is the boot strap processor (BSP).
CMOS_IS_COLD_BOOT_MAPPING | The default function is CmosMgrIsColdBoot. This SDL eLink provides a mechanism to replace the default function for determining whether or not the platform is executing a cold boot.
CMOS_IS_FIRST_BOOT_MAPPING | The default function is CmosMgrIsFirstBoot. This SDL eLink provides a mechanism to replace the default function for determining whether or not the current execution is the first boot after programming the boot firmware device (flash part, ROM emulator, ...).
CMOS_IS_USABLE_MAPPING | The default function is CmosIsUsable. This SDL eLink provides a mechanism to replace the default function for determining whether or not the CMOS hardware is usable. (Note, the CMOS may be usable even if the battery is bad.)
CMOS_MESSAGES_SUPPORT | Default value is 0 (CMOS_SETUP_SUPPORT = FALSE by default) This token specifies whether or not messages are displayed to provide CMOS Manager related power-on information.
CMOS_MGR_RECOVER_IN_PEI | Default value is 1 (PEI recovery is enabled) This configures the recovery policy so that the Optimal Defaults buffer is written to CMOS in the PEI phase.
CMOS_MGR_RECOVER_ONLY_CHECKUMMED | Default value is 0 (all Managed Region locations are recovered) 1 = Do not recover non-checksummed locations in the Managed Region 0 = Recover all locations in the Managed Region This configures the recovery policy so that the Optimal Defaults buffer is only used for checksummed locations upon bad checksum detection.
CMOS_MGR_SET_NMI_BIT | Default value is 1 (NMI access is enabled for 0x0-0x7f) 1 = Set NMI bit for access to NMI region 0 = Do not set NMI bit for access to NMI region
CMOS_NMI_BIT_VALUE | Default value is 0x80 (CMOS_MGR_SET_NMI_BIT = TRUE by default) There are two possible values for this token as determined by the value of CMOS_MGR_SET_NMI_BIT: 0x80 = if CMOS_MGR_SET_NMI_BIT == TRUE 0x00 = if CMOS_MGR_SET_NMI_BIT == FALSE
CMOS_PORT_MAPPING | Default value (see Notes below) This Elink is used to associate CMOS register address ranges with an 8-bit index/data port pair or an access function. Additional ranges can be specified by adding additional eLinks. The default eLink for the 0x0-0x7f range can be replaced by first disabling the CMOS_USES_STANDARD_RANGE_ACCESS SDL token and then defining a new eLink.
CMOS_SETUP_SUPPORT | Default value is 0 (CMOS_SETUP_SUPPORT = FALSE by default) This token specifies whether or not a setup page is enabled to provide CMOS Manager related information/options.
CMOS_SMM_SUPPORT | Default value is 1 (SMM support is enabled) This token specifies whether or not the CMOS Access interface is available in SMM. 1 = Enable SMM CMOS Access 0 = Disable SMM CMOS Access
CMOS_USES_STANDARD_BATTERY_TEST | Default value is 1 (default function is used) This SDL Token specifies whether or not to use the default function to determine whether or not the CMOS battery is good.
CMOS_USES_STANDARD_IS_BSP | Default value is 1 (default function is used) This SDL Token specifies whether or not to use the default function to determine whether or not the boot strap processor is executing. If a platform provides a different function for determining the BSP, this token should be disabled.
CMOS_USES_STANDARD_IS_CMOS_USABLE | Default value is 1 (default function is used) This SDL Token specifies whether or not to use the default function to determine whether or not the CMOS hardware is usable. If a platform provides a different function, this token should be disabled.
CMOS_USES_STANDARD_IS_COLD_BOOT | Default value is 1 (default function is used) This SDL Token specifies whether or not to use the default function to determine whether or not the platform is executing a cold boot.
CMOS_USES_STANDARD_IS_FIRST_BOOT | Default value is 1 (default function is used) This SDL Token specifies whether or not to use the default function to determine whether or not the platform is executing a first boot.
CMOS_USES_STANDARD_RANGE_ACCESS | Default value is 1 (default function is enabled) Specifies whether or not to use CMOS Manager's default access function for the 0-0x7f range. If a platform provides a different access function for this region this token should be FALSE.
FIRST_MANAGED_CMOS_ADDRESS | Default value is 0x40 This is the lower limit of the CMOS register range to be managed by CMOS Manager The region starting at FIRST_MANAGED_CMOS_ADDRESS and ending at MAX_MANAGED_CMOS_ADDRESS - 1 represents the managed region.
FULL_CMOS_MANAGER_DEBUG | Default value is 0 1 = Turn on all available CMOS Manager debug messages, resulting in larger build. 0 = Only basic debugging messages are displayed, dependent upon project-level debug settings.
MAX_MANAGED_CMOS_ADDRESS | Default value is 128 (128 bytes with max address of 127) This is the upper limit (last address + 1) of CMOS address locations that are managed by CMOS Manager. (I.e., if 256 bytes of CMOS is available and is entirely managed by CMOS Manager, then the value of this token would be 256.)

The following descriptions are used in the file: CmosBoard.sdl.

Header | Description
All_Elinks_Tokens | The following files contain the SDL Tokens/Elinks used in the CMOS Manager module, which may be ported. CmosBoard.sdl -- SDL Tokens/Elinks typically used for project-specific porting CmosManager.sdl -- SDL Tokens/Elinks typically not modified


All_Elinks_Tokens in the CmosBoard.sdl

General : All_Elinks_Tokens

File: CmosBoard.sdl
Description:
The following files contain the SDL Tokens/Elinks
used in the CMOS Manager module, which may be ported.

    CmosBoard.sdl --    SDL Tokens/Elinks typically
                        used for project-specific porting

    CmosManager.sdl --  SDL Tokens/Elinks typically
                        not modified
Built on 11:30:58 01/27/12


CMOS_BANK0_DATA in the CmosBoard.sdl

Variable : CMOS_BANK0_DATA

File: CmosBoard.sdl
Description:

Default value is 0x71

Data I/O port to access CMOS registers in range: 0x0-0x7f.
Built on 11:30:58 01/27/12


CMOS_BANK0_INDEX in the CmosBoard.sdl

Variable : CMOS_BANK0_INDEX

File: CmosBoard.sdl
Description:

Default value is 0x70

Index I/O port to access CMOS registers in range: 0x0-0x7f.
Built on 11:30:58 01/27/12


CMOS_BATTERY_TEST_MAPPING in the CmosBoard.sdl

Variable : CMOS_BATTERY_TEST_MAPPING

File: CmosBoard.sdl
Description:

The default function is CmosMgrBatteryIsGood.

This SDL eLink provides a mechanism to replace the default function
for determining whether or not the battery is bad.
Notes:
To override the default function, set the
CMOS_USES_STANDARD_BATTERY_TEST SDL Token to false and define a
new eLink.
Built on 11:30:58 01/27/12


CMOS_IS_BSP_MAPPING in the CmosBoard.sdl

Variable : CMOS_IS_BSP_MAPPING

File: CmosBoard.sdl
Description:

The default function is CmosMgrIsBsp.

This SDL eLink provides a mechanism to replace the default function
for determining whether or not the currently executing CPU core is
the boot strap processor (BSP).
Notes:
To override the default function, set the
CMOS_USES_STANDARD_IS_BSP SDL Token to FALSE (0) and define a
new eLink.
Built on 11:30:58 01/27/12


CMOS_IS_COLD_BOOT_MAPPING in the CmosBoard.sdl

Variable : CMOS_IS_COLD_BOOT_MAPPING

File: CmosBoard.sdl
Description:

The default function is CmosMgrIsColdBoot.

This SDL eLink provides a mechanism to replace the default function
for determining whether or not the platform is executing a cold
boot.
Notes:
To override the default function, set the
CMOS_USES_STANDARD_IS_COLD_BOOT SDL Token to FALSE (0) and define a
new eLink.
Built on 11:30:58 01/27/12


CMOS_IS_FIRST_BOOT_MAPPING in the CmosBoard.sdl

Variable : CMOS_IS_FIRST_BOOT_MAPPING

File: CmosBoard.sdl
Description:

The default function is CmosMgrIsFirstBoot.

This SDL eLink provides a mechanism to replace the default function
for determining whether or not the current execution is the first
boot after programming the boot firmware device (flash part, ROM
emulator,  ...).
Notes:
To override the default function, set the
CMOS_USES_STANDARD_IS_FIRST_BOOT SDL Token to FALSE (0) and define a
new eLink.
Built on 11:30:58 01/27/12


CMOS_IS_USABLE_MAPPING in the CmosBoard.sdl

Variable : CMOS_IS_USABLE_MAPPING

File: CmosBoard.sdl
Description:

The default function is CmosIsUsable.

This SDL eLink provides a mechanism to replace the default function
for determining whether or not the CMOS hardware is usable. (Note,
the CMOS may be usable even if the battery is bad.)
Notes:
To override the default function, set the
CMOS_USES_STANDARD_IS_CMOS_USABLE SDL Token to FALSE (0) and define a
new eLink.
Built on 11:30:58 01/27/12


CMOS_MESSAGES_SUPPORT in the CmosBoard.sdl

Variable : CMOS_MESSAGES_SUPPORT

File: CmosBoard.sdl
Description:

Default value is 0 (CMOS_SETUP_SUPPORT = FALSE by default)

This token specifies whether or not messages are displayed
to provide CMOS Manager related power-on information.
Notes:

This feature is only supported for TSE labels only supported for
TSE versions 4.6.2_TSE_2_01_1204 and later.
Built on 11:30:58 01/27/12


CMOS_MGR_RECOVER_IN_PEI in the CmosBoard.sdl

Variable : CMOS_MGR_RECOVER_IN_PEI

File: CmosBoard.sdl
Description:

Default value is 1 (PEI recovery is enabled)

This configures the recovery policy so that the Optimal Defaults
buffer is written to CMOS in the PEI phase.
Notes:
1.  This setting may require replacement of the
    default function defined in the CMOS_IS_COLD_BOOT_MAPPING
    eLink.

2.  The bad checksum bit in the legacy status CMOS register
    will indicate bad checksum until the DXE phase, but
    physical CMOS will be used in the PEI phase.
Built on 11:30:58 01/27/12


CMOS_MGR_RECOVER_ONLY_CHECKUMMED in the CmosBoard.sdl

Variable : CMOS_MGR_RECOVER_ONLY_CHECKUMMED

File: CmosBoard.sdl
Description:

Default value is 0 (all Managed Region locations are recovered)

    1  = Do not recover non-checksummed locations in the
         Managed Region

    0  = Recover all locations in the Managed Region

This configures the recovery policy so that the Optimal Defaults
buffer is only used for checksummed locations upon bad checksum
detection.
Notes:
1.  For the bad battery condition, the Optimal Defaults buffer
    will always be used.
Built on 11:30:58 01/27/12


CMOS_MGR_SET_NMI_BIT in the CmosBoard.sdl

Variable : CMOS_MGR_SET_NMI_BIT

File: CmosBoard.sdl
Description:

Default value is 1 (NMI access is enabled for 0x0-0x7f)

1 = Set NMI bit for access to NMI region
0 = Do not set NMI bit for access to NMI region
Built on 11:30:58 01/27/12


CMOS_NMI_BIT_VALUE in the CmosBoard.sdl

Variable : CMOS_NMI_BIT_VALUE

File: CmosBoard.sdl
Description:

Default value is 0x80 (CMOS_MGR_SET_NMI_BIT = TRUE by default)

There are two possible values for this token as determined by the
value of CMOS_MGR_SET_NMI_BIT:

    0x80 = if CMOS_MGR_SET_NMI_BIT == TRUE
    0x00 = if CMOS_MGR_SET_NMI_BIT == FALSE
Notes:

This value will be OR'ed with the index value for CMOS access to
bank 0 locations. The value will be negated and AND'ed with the
index to clear the NMI bit if the original index value is to be
restored.
Built on 11:30:58 01/27/12


CMOS_PORT_MAPPING in the CmosBoard.sdl

Variable : CMOS_PORT_MAPPING

File: CmosBoard.sdl
Description:

Default value (see Notes below)

This Elink is used to associate CMOS register address ranges with
an 8-bit index/data port pair or an access function.

Additional ranges can be specified by adding additional eLinks.

The default eLink for the 0x0-0x7f range can be replaced by first
disabling the CMOS_USES_STANDARD_RANGE_ACCESS SDL token and then
defining a new eLink.
Notes:
Format:

    {IndexPort, DataPort, LowIndex, HighIndex, FunctionName},

Default:

    ELINK
        Name  = "{0, 0, 0, 127, ReadWriteStandardRange},"
        Parent  = "CMOS_PORT_MAPPING"
        Help  = "Standard NMI-capable access range"
        Token = "CMOS_USES_STANDARD_RANGE_ACCESS" "=" "1"
        InvokeOrder = AfterParent
    End

* FunctionName takes precedence over IndexPort/DataPort, if
  both are specified.

* The comma is required.
Built on 11:30:58 01/27/12


CMOS_SETUP_SUPPORT in the CmosBoard.sdl

Variable : CMOS_SETUP_SUPPORT

File: CmosBoard.sdl
Description:

Default value is 0 (CMOS_SETUP_SUPPORT = FALSE by default)

This token specifies whether or not a setup page is enabled
to provide CMOS Manager related information/options.
Notes:

This feature is only supported for TSE labels only supported for
TSE versions 4.6.2_TSE_2_01_1204 and later.
Built on 11:30:58 01/27/12


CMOS_SMM_SUPPORT in the CmosBoard.sdl

Variable : CMOS_SMM_SUPPORT

File: CmosBoard.sdl
Description:

Default value is 1 (SMM support is enabled)

This token specifies whether or not the CMOS Access interface is
available in SMM.

    1 = Enable SMM CMOS Access
    0 = Disable SMM CMOS Access
Built on 11:30:58 01/27/12


CMOS_USES_STANDARD_BATTERY_TEST in the CmosBoard.sdl

Variable : CMOS_USES_STANDARD_BATTERY_TEST

File: CmosBoard.sdl
Description:

Default value is 1 (default function is used)

This SDL Token specifies whether or not to use the default function
to determine whether or not the CMOS battery is good.
Notes:
If this SDL Token is turned off, an alternate function must be
defined and linked using the CMOS_BATTERY_TEST_MAPPING SDL eLink.

The default function eLink is CmosMgrBatteryIsGood.
Built on 11:30:58 01/27/12


CMOS_USES_STANDARD_IS_BSP in the CmosBoard.sdl

Variable : CMOS_USES_STANDARD_IS_BSP

File: CmosBoard.sdl
Description:

Default value is 1 (default function is used)

This SDL Token specifies whether or not to use the default function
to determine whether or not the boot strap processor is executing.
If a platform provides a different function for determining the BSP,
this token should be disabled.
Notes:
If this SDL Token is turned off, an alternate function must be
defined using the CMOS_IS_BSP_MAPPING SDL eLink.

The default function eLink is CmosMgrIsBsp.
Built on 11:30:58 01/27/12


CMOS_USES_STANDARD_IS_CMOS_USABLE in the CmosBoard.sdl

Variable : CMOS_USES_STANDARD_IS_CMOS_USABLE

File: CmosBoard.sdl
Description:

Default value is 1 (default function is used)

This SDL Token specifies whether or not to use the default function
to determine whether or not the CMOS hardware is usable.
If a platform provides a different function, this token should be
disabled.
Notes:
If this SDL Token is turned off, an alternate function must be
defined using the CMOS_IS_USABLE_MAPPING SDL eLink.

The default function eLink is CmosMgrIsBsp.
Built on 11:30:58 01/27/12


CMOS_USES_STANDARD_IS_COLD_BOOT in the CmosBoard.sdl

Variable : CMOS_USES_STANDARD_IS_COLD_BOOT

File: CmosBoard.sdl
Description:

Default value is 1 (default function is used)

This SDL Token specifies whether or not to use the default function
to determine whether or not the platform is executing a cold boot.
Notes:

1.  The default function eLink is CmosMgrIsColdBoot.

2.  In the case of a bad checksum, the Optimal Defaults buffer
    is written to physical CMOS in the PEI phase if:

      a. CMOS_MGR_RECOVER_IN_PEI is enabled and
      b. CmosMgrIsColdBoot returns TRUE

3.  Some platforms may execute a warm-reset in the PEI phase,
    with a dependency on some CMOS value, causing
    unpredicatable results ...possibly an infinite reboot
    sequence.

4.  A cold boot is defined as a power-on boot, as opposed
    to a warm boot where a reset is initiated through
    software.

5.  If this SDL Token is turned off, an alternate function
    must be defined using the CMOS_IS_COLD_BOOT_MAPPING
    SDL eLink.
Built on 11:30:58 01/27/12


CMOS_USES_STANDARD_IS_FIRST_BOOT in the CmosBoard.sdl

Variable : CMOS_USES_STANDARD_IS_FIRST_BOOT

File: CmosBoard.sdl
Description:

Default value is 1 (default function is used)

This SDL Token specifies whether or not to use the default function
to determine whether or not the platform is executing a first boot.
Notes:
If this SDL Token is turned off, an alternate function must be
defined using the CMOS_IS_FIRST_BOOT_MAPPING SDL eLink.

The default function eLink is CmosMgrIsFirstBoot.
Built on 11:30:58 01/27/12


CMOS_USES_STANDARD_RANGE_ACCESS in the CmosBoard.sdl

Variable : CMOS_USES_STANDARD_RANGE_ACCESS

File: CmosBoard.sdl
Description:

Default value is 1 (default function is enabled)

Specifies whether or not to use CMOS Manager's default access
function for the 0-0x7f range.  If a platform provides a different
access function for this region this token should be FALSE.
Notes:
*   If this SDL Token is turned off, an alternate
    function must be defined using the CMOS_PORT_MAPPING
    SDL eLink.
Built on 11:30:58 01/27/12


FIRST_MANAGED_CMOS_ADDRESS in the CmosBoard.sdl

Variable : FIRST_MANAGED_CMOS_ADDRESS

File: CmosBoard.sdl
Description:

Default value is 0x40

This is the lower limit of the CMOS register range to be managed
by CMOS Manager

The region starting at FIRST_MANAGED_CMOS_ADDRESS and ending at
MAX_MANAGED_CMOS_ADDRESS - 1 represents the managed region.


FULL_CMOS_MANAGER_DEBUG in the CmosBoard.sdl

Variable : FULL_CMOS_MANAGER_DEBUG

File: CmosBoard.sdl
Description:

Default value is 0

1  = Turn on all available CMOS Manager debug messages,
     resulting in larger build.
0  = Only basic debugging messages are displayed,
     dependent upon project-level debug settings.


MAX_MANAGED_CMOS_ADDRESS in the CmosBoard.sdl

Variable : MAX_MANAGED_CMOS_ADDRESS

File: CmosBoard.sdl
Description:

Default value is 128 (128 bytes with max address of 127)

This is the upper limit (last address + 1) of CMOS address locations
that are managed by CMOS Manager.

(I.e., if 256 bytes of CMOS is available and is entirely managed
by CMOS Manager, then the value of this token would be 256.)


CmosManager.c

Description:
Contains the routines that constitute the CMOS manager
implementation.  This files is used to create object code
for both PEI and DXE phases, based upon the build
macro PEI_COMPILE.

The following functions are used in the file: CmosManager.c.

Function | Description
CmosConfigureManager | This function configures the CMOS Manager.
CmosGetMangerInterface | Gets the EFI_CMOS_MANAGER_INTERFACE for the current access interface.
CmosManagerAllocatePool | This function allocates memory for all boot phases.
CmosManagerCheckAnyStatus | This function returns true if any of the status bits are set as specified by the BitMap.
CmosManagerCheckStatus | This function returns true if all the status bits are set as specified by the BitMap.
CmosManagerClearStatus | This function clears status bits according to the specified bitmap.
CmosManagerSetClearStatus | This function provides a single entry point into the code that actually updates status values.
CmosManagerSetStatus | This function sets status bits according to the specified bitmap.
CmosUpdateMemoryStatus | This function is used in the PEI phase to set/clear the CMOS_EXECUTING_IN_MEMORY depending on whether or not the manager is executing after permanent memory has been initialized.
GetApiPointerFromCmos | This function get the CMOS API pointer from a predefined 4-byte CMOS location and updates the output parameter with the pointer.
GetCmosAccessInterface | Gets the EFI_CMOS_ACCESS_INTERFACE for the current manager interface.
InitializeCmosManagerInterface | This function initializes structure data and function pointer elements for a EFI_CMOS_MANAGER_INTERFACE.
InstallCmosAccessInterface | This function installs either the PEI or DXE phase interface (PPI or Protocol) for accessing CMOS.
NewCmosManagerInterface | This function locates (or allocates memory for) the EFI_CMOS_MANAGER_INTERFACE, calculates the checksum, checks the battery condition and updates the Manager's status bits.
SaveApiPointerToCmos | This function saves the specified pointer to a predefined 4-byte CMOS location.


CmosConfigureManager in the CmosManager.c

Function : CmosConfigureManager

File: CmosManager.c
Description:
This function configures the CMOS Manager.
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Manager
   -- Pointer to the Manager's interface
IN CMOS_CONFIGURATION_SETTING Setting
   -- Configuration setting to invoke.
Output:
EFI_STATUS (Return value)
   = EFI_SUCCESS or valid EFI error code
Notes:


CmosGetMangerInterface in the CmosManager.c

Function : CmosGetMangerInterface

File: CmosManager.c
Description:
Gets the EFI_CMOS_MANAGER_INTERFACE for the current access
interface.
Input:
IN  EFI_CMOS_ACCESS_INTERFACE *Cmos
   -- This is the access interface pointer.
Output:
EFI_CMOS_MANAGER_INTERFACE * (Return Value)
   -- If successful, the CMOS manager interface is returned.
   -- Otherwise, a valid EFI error code
Notes:
None


CmosManagerAllocatePool in the CmosManager.c

Function : CmosManagerAllocatePool

File: CmosManager.c
Description:
This function allocates memory for all boot phases.
Input:
IN EFI_PEI_SERVICES **PeiServices
   -- PEI Services table (NULL in DXE phase)
IN UINTN Size
   -- Number of bytes to allocate
OUT VOID **Buffer
   -- Pointer to buffer for which memory is allocated
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS if successful
   = or other valid EFI error code
Notes:
None


CmosManagerCheckAnyStatus in the CmosManager.c

Function : CmosManagerCheckAnyStatus

File: CmosManager.c
Description:
This function returns true if any of the status bits are set as
specified by the BitMap.
Input:
IN EFI_CMOS_MANAGER_INTERFACE   *Manager
   -- Pointer to the Manager's interface
IN CMOS_MANAGER_STATUS          BitMap
   -- Bits to check
Output:
BOOLEAN (Return value)
= TRUE, if one or more of the bits in ManagerStatus
  specified by BitMap are set.

= FALSE, otherwise.
Notes:


CmosManagerCheckStatus in the CmosManager.c

Function : CmosManagerCheckStatus

File: CmosManager.c
Description:
This function returns true if all the status bits are set as
specified by the BitMap.
Input:
IN EFI_CMOS_MANAGER_INTERFACE   *Manager
   -- Pointer to the Manager's interface
IN CMOS_MANAGER_STATUS          BitMap
   -- Bits to check
Output:
BOOLEAN (Return value)
= TRUE, if all bits in ManagerStatus specified by
  BitMap are set.

= FALSE, otherwise.
Notes:


CmosManagerClearStatus in the CmosManager.c

Function : CmosManagerClearStatus

File: CmosManager.c
Description:
This function clears status bits according to the specified bitmap.
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Manager
   -- Pointer to the Manager's interface
IN CMOS_MANAGER_STATUS BitMap
   -- Bits to clear
Output:
EFI_STATUS (Return value)
   = EFI_SUCCESS or valid EFI error code
Notes:


CmosManagerSetClearStatus in the CmosManager.c

Function : CmosManagerSetClearStatus

File: CmosManager.c
Description:
This function provides a single entry point into the code that
actually updates status values.
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Manager
   -- Pointer to the Manager's interface
IN CMOS_MANAGER_STATUS BitMap
   -- Bits to set or clear
IN CMOS_BIT_ACCESS_TYPE AccessType
   -- SetType or ClearType depending upon whether
      setting or clearing bits
Output:
EFI_STATUS (Return value)
   = EFI_SUCCESS or valid EFI error code
Notes:


CmosManagerSetStatus in the CmosManager.c

Function : CmosManagerSetStatus

File: CmosManager.c
Description:
This function sets status bits according to the specified bitmap.
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Manager
   -- Pointer to the Manager's interface
IN CMOS_MANAGER_STATUS BitMap
   -- Bits to set
Output:
EFI_STATUS (Return value)
   = EFI_SUCCESS or valid EFI error code
Notes:


CmosUpdateMemoryStatus in the CmosManager.c

Function : CmosUpdateMemoryStatus

File: CmosManager.c
Description:
This function is used in the PEI phase to set/clear the
CMOS_EXECUTING_IN_MEMORY depending on whether or not the manager
is executing after permanent memory has been initialized.
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Manager
   -- Pointer to the Manager's interface
Output:
EFI_STATUS (Return value)
   = EFI_SUCCESS or valid EFI error code
Notes:


GetApiPointerFromCmos in the CmosManager.c

Function : GetApiPointerFromCmos

File: CmosManager.c
Description:
This function get the CMOS API pointer from a predefined 4-byte
CMOS location and updates the output parameter with the pointer.
Input:
IN EFI_CMOS_MANAGER_INTERFACE *CmosManager
   - Pointer to the manager's interface to be installed
OUT EFI_CMOS_ACCESS_INTERFACE **ApiPointer
   - Address of the API pointer
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS or valid EFI error code
Notes:
None


GetCmosAccessInterface in the CmosManager.c

Function : GetCmosAccessInterface

File: CmosManager.c
Description:
Gets the EFI_CMOS_ACCESS_INTERFACE for the current manager
interface.
Input:
IN  EFI_CMOS_MANAGER_INTERFACE *Manager
   -- This is the manager interface pointer.
Output:
EFI_CMOS_ACCESS_INTERFACE * (Return Value)
   -- If successful, the CMOS access interface is returned.
   -- Otherwise, NULL is returned.
Notes:
None


InitializeCmosManagerInterface in the CmosManager.c

Function : InitializeCmosManagerInterface

File: CmosManager.c
Description:
This function initializes structure data and function pointer
elements for a EFI_CMOS_MANAGER_INTERFACE.
Input:
IN  EFI_PEI_SERVICES **PeiServices
   - This parameter will be NULL in the DXE phase
OUT EFI_CMOS_MANAGER_INTERFACE *CmosManager
   - Pointer to the interface to be initialized
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS or valid EFI error code
CmosManager->ManagerStatus
   = CMOS_VALID_INTERFACE indicates successful
       initialization of the structure.
Notes:
This function is used for both PEI and DXE phase.  The build
macro PEI_COMPILE will determine how the object code is
created.


InstallCmosAccessInterface in the CmosManager.c

Function : InstallCmosAccessInterface

File: CmosManager.c
Description:
This function installs either the PEI or DXE phase interface
(PPI or Protocol) for accessing CMOS.
Input:
IN EFI_CMOS_MANAGER_INTERFACE      *CmosManager
   - Pointer to the interface to be installed
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS or valid EFI error code
CmosManager->ManagerStatus
   = CMOS_VALID_MANAGER indicates successful
     installation of interface.
Notes:
This function is used for both PEI and DXE phase.  The build
macro PEI_COMPILE will determine how the object code is
created/linked.


NewCmosManagerInterface in the CmosManager.c

Function : NewCmosManagerInterface

File: CmosManager.c
Description:
This function locates (or allocates memory for) the
EFI_CMOS_MANAGER_INTERFACE, calculates the checksum, checks the
battery condition and updates the Manager's status bits.
Input:
IN EFI_PEI_SERVICES **PeiServices
   - This parameter will be NULL in the DXE phase
Output:
EFI_CMOS_MANAGER_INTERFACE* (Return Value)
   =  If successful, a pointer to the allocated/found
      structure is returned.
   =  NULL is returned on failure to allocate

NewManager->ManagerStatus
   =  CMOS_INTERFACE_ALREADY_INSTALLED, if the interface is
      found prior to allocating
   =  CMOS_VALID_INTERFACE, on successful initialization
      of the access interface.
Notes:
This function is used for PEI, DXE and SMM interface initialization.
The build Macros PEI_COMPILE and SMM_COMPILE will determine how the
object code is compiled.

See CMOS_MANAGER_STATUS enum type for more information on manager
status bits.

Assumptions:

1) This function should only be called once for each
   entrypoint.

2) It is up to the user of the Manager interface to determine
   how to use the CMOS_MANAGER_STATUS bits upon return from
   this function.


SaveApiPointerToCmos in the CmosManager.c

Function : SaveApiPointerToCmos

File: CmosManager.c
Description:
This function saves the specified pointer to a predefined 4-byte
CMOS location.
Input:
IN EFI_CMOS_MANAGER_INTERFACE *CmosManager
   - Pointer to the manager's interface
IN EFI_CMOS_ACCESS_INTERFACE *ApiPointer
   - API address
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS or valid EFI error code
Notes:
None


CmosManager.h

Description:
Contains the constants, data types and declarations
necessary to support the CMOS manager interface.

The following data structures are used in the file: CmosManager.h.

Variable | Description
EFI_CMOS_MANAGER_INTERFACE | This is the internal interface used by subsystems within the CMOS manager module.

The following descriptions are used in the file: CmosManager.h.

Header | Description
Internal_Interfaces | The page provides links to descriptions of the internal interfaces used by the CMOS Manager's subsystems.


EFI_CMOS_MANAGER_INTERFACE in the CmosManager.h

Variable : EFI_CMOS_MANAGER_INTERFACE

File: CmosManager.h
Fields:

Type | Name | Description
EFI_CMOS_ACCESS_INTERFACE | Access | The external interface
CMOS_MANAGER_INSTALL_ACCESS_INTERFACE | InstallAccessInterface | Installs the Access PPI or Protocol, depending on the phase (see InstallCmosAccessInterface)
CMOS_MANAGER_GET_ACCESS_INTERFACE | GetAccessInterface | Used internally to get a pointer to the Access interface (see GetCmosAccessInterface)
EFI_GUID | AccessGuid | The Access PPI (or Protocol) GUID
EFI_PEI_PPI_DESCRIPTOR | Ppi | [4] Descriptors for the PEIMs installed by this module
UINT8 | FirstManagedRegister | First register in the managed space
UINT8 | LastManagedRegister | Last register in the managed space
CMOS_TOKEN | *TokenTable | All defined tokens
UINT16 | TokenCount | Entry count for TokenTable (#Tokens + 1)
CMOS_REGISTER | *OptimalDefaultTable | Default values for all managed CMOS addresses
UINT16 | OptimalDefaultCount | Entry count for OptimalDefaultTable
CMOS_REGISTER | *NoChecksumTable | CMOS address of locations not included in the checksum in the managed area
UINT16 | NoChecksumCount | Entry count for NoChecksumTable
CMOS_MANAGER_CONFIGURE | ConfigureManager | Provides means for specifying configurable settings for CMOS manager during PEI/DXE initialization (see CmosConfigureManager)
CMOS_CHECKSUM | Checksum | Valid checksum after the call to NewCmosManagerInterface()
CMOS_MANAGER_CALCULATE_CHECKSUM | CalculateChecksum | Forces calculation of the checksum over the entire managed region
CMOS_MANAGER_READ_CHECKSUM | ReadChecksum | Reads checksum from the CMOS checksum location
CMOS_MANAGER_WRITE_CHECKSUM | WriteChecksum | Writes the provided checksum to the CMOS checksum location
CMOS_MANAGER_LOAD_OPTIMAL_DEFAULTS | LoadOptimalDefaults | Writes default values from the OptimalDefaultTable to all CMOS registers
CMOS_MANAGER_STATUS | ManagerStatus | Bitmap containing various Manager-related status values
CMOS_MANAGER_SET_STATUS | SetStatus | Sets bits in the ManagerStatus value (see CmosManagerSetStatus)
CMOS_MANAGER_CLEAR_STATUS | ClearStatus | Clears bits in the ManagerStatus value (see CmosManagerClearStatus)
CMOS_MANAGER_CHECK_STATUS | CheckStatus | Returns true if all of the specified bits are "set" in the ManagerStatus value (see CmosManagerCheckStatus)
CMOS_MANAGER_CHECK_ANY_STATUS | CheckAnyStatus | Returns true if any of the specified bits are "set" in the ManagerStatus value (see CmosManagerCheckAnyStatus)
CMOS_MANAGER_HOB | *ManagerHob | Pointer to the HOB defined after permanent memory detection in PEI
CMOS_MANAGER_SAVE_API_POINTER_TO_CMOS | SaveApiPointerToCmos | Pointer to the Access interface is maintained in a 4-byte CMOS location
CMOS_MANAGER_GET_API_POINTER_FROM_CMOS | GetApiPointerFromCmos | Retrieve pointer to the Access interface from 4-byte CMOS location

Description:
This is the internal interface used by subsystems within the CMOS
manager module.


Internal_Interfaces in the CmosManager.h

General : Internal_Interfaces

File: CmosManager.h
Fields:

Phase | Name | Description
All | EFI_CMOS_MANAGER_INTERFACE | Provides general services

Description:
The page provides links to descriptions of the internal interfaces
used by the CMOS Manager's subsystems.


CmosManager.mak

Description:
This is a make file used to build the CMOS manager component

The following descriptions are used in the file: CmosManager.mak.

Header | Description
Entry_Functions | This page provides links to descriptions of the PEI and DXE phase entrypoint functions for the CMOS Manager module.


Entry_Functions in the CmosManager.mak

General : Entry_Functions

File: CmosManager.mak
Fields:

Phase | Entrypoint | Description
PEI | CmosManagerPeiEntry | Main PEI phase entry point
PEI | CmosManagerAfterMemoryEntry | PEI after memory detection entry point
DXE | CmosManagerDxeEntry | Main DXE phase entry point
DXE | CmosManagerSmmEntry | Entry into SMM (Runtime) CMOS access support driver

Description:
This page provides links to descriptions of the PEI and DXE phase
entrypoint functions for the CMOS Manager module.


CmosManager.sdl

Description:
This AMI SDL file defines porting constants used in
the CMOS Manager module.  Please see CmosBoard.sdl for
SDL Tokens/eLinks that are expected to be cloned/added
for project-level porting.

The following data structures are used in the file: CmosManager.sdl.

Variable | Description
ADDON_SSP_FILES | There are no default eLinks This eLink is used to update the list of CMOS Token definition files to be processed by AmiSsp2.exe during the build process. For example, the following eLink will add AgesaCmosTokens.SSP to the list of CMOS Token definition files: ELINK Name = "$(AGESA_EFI_DIR)\AgesaCmosTokens.SSP" Parent = "ADDON_SSP_FILES" InvokeOrder = AfterParent End
CMOS_ACCESS_API_BYTE3 | Default value is 0x42 The high byte of the CMOS Access API pointer registers. 1) These registers are in range: 0x10-0x7f. 2) If you change this token, you must modify CmosManager.SSP. 3) Do not set the NMI bit as this is a policy to be implemented by the ReadWrite function.
CMOS_DIAGNOSTIC_STATUS_REGISTER | Default value is 0xe This is the diagnostic status register. (Do not set the NMI bit as this is a policy to be implmeneted by the ReadWrite function.)
CMOS_MANAGER_SUPPORT | This token is the main switch to enable CMOS manager support in Project
CMOS_RTC_STATUS_REGISTER | Default value is 0xd This is the RTC status register. Bit 7 is the battery status. (Do not set the NMI bit as this is a policy to be implmeneted by the ReadWrite function.)
SSP | Default value is AMISSP2.exe Defines the location of AmiSsp2.exe, which is used to generate the header files containing CMOS information.


ADDON_SSP_FILES in the CmosManager.sdl

Variable : ADDON_SSP_FILES

File: CmosManager.sdl
Description:

There are no default eLinks

This eLink is used to update the list of CMOS Token definition files
to be processed by AmiSsp2.exe during the build process.

For example, the following eLink will add AgesaCmosTokens.SSP to the
list of CMOS Token definition files:

    ELINK
        Name = "$(AGESA_EFI_DIR)\AgesaCmosTokens.SSP"
        Parent  = "ADDON_SSP_FILES"
        InvokeOrder = AfterParent
    End
Built on 11:30:58 01/27/12


CMOS_ACCESS_API_BYTE3 in the CmosManager.sdl

Variable : CMOS_ACCESS_API_BYTE3

File: CmosManager.sdl
Description:

Default value is 0x42

The high byte of the CMOS Access API pointer registers.
   1) These registers are in range: 0x10-0x7f.
   2) If you change this token, you must modify CmosManager.SSP.
   3) Do not set the NMI bit as this is a policy to be
      implemented by the ReadWrite function.
Built on 11:30:58 01/27/12


CMOS_DIAGNOSTIC_STATUS_REGISTER in the CmosManager.sdl

Variable : CMOS_DIAGNOSTIC_STATUS_REGISTER

File: CmosManager.sdl
Description:

Default value is 0xe

This is the diagnostic status register. (Do not set the NMI bit as
this is a policy to be implmeneted by the ReadWrite function.)
Built on 11:30:58 01/27/12


CMOS_MANAGER_SUPPORT in the CmosManager.sdl

Variable : CMOS_MANAGER_SUPPORT

File: CmosManager.sdl
Description:
This token is the main switch to enable CMOS manager support in Project
Built on 11:30:58 01/27/12


CMOS_RTC_STATUS_REGISTER in the CmosManager.sdl

Variable : CMOS_RTC_STATUS_REGISTER

File: CmosManager.sdl
Description:

Default value is 0xd

This is the RTC status register. Bit 7 is the battery status.
(Do not set the NMI bit as this is a policy to be implmeneted by
the ReadWrite function.)
Built on 11:30:58 01/27/12


SSP in the CmosManager.sdl

Variable : SSP

File: CmosManager.sdl
Description:

Default value is AMISSP2.exe

Defines the location of AmiSsp2.exe, which is used to generate
the header files containing CMOS information.


CmosManagerDxe.c

Description:
Contains the routines that constitute the CMOS manager's
DXE phase entry.

The following functions are used in the file: CmosManagerDxe.c.

Function | Description
ClearCmosBasedStatus | This function uses the CMOS Manager interface to clear the un-managed private status bits upon boot or setup entry.
CmosManagerDxeEntry | This function is the main DXE phase entry point for the CMOS manager module.
CreateEventHandlers | This function creates a callback on the setup entry event and boot event to (respectively) update the CMOS setup variable and clear the CMOS-based status bits.
UpdateCmosSetupVariable | This function updates the CMOS setup variable using information from the CMOS-based status bits.


ClearCmosBasedStatus in the CmosManagerDxe.c

Function : ClearCmosBasedStatus

File: CmosManagerDxe.c
Description:
This function uses the CMOS Manager interface to clear the un-managed
private status bits upon boot or setup entry.
Input:
IN EFI_EVENT Event
   - Event handle
IN VOID *Context
   - Not used
Output:
None
Notes:
None
Built on 11:30:58 01/27/12


CmosManagerDxeEntry in the CmosManagerDxe.c

Function : CmosManagerDxeEntry

File: CmosManagerDxe.c
Description:
This function is the main DXE phase entry point for the CMOS
manager module.
Input:
IN EFI_HANDLE ImageHandle
   - Image handle
IN EFI_SYSTEM_TABLE *SystemTable
   - System table pointer
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS if successful
   = or other valid EFI error code
Notes:
*  Initializes/Installs the EFI_CMOS_ACCESS_INTERFACE
   Protocol.


CreateEventHandlers in the CmosManagerDxe.c

Function : CreateEventHandlers

File: CmosManagerDxe.c
Description:
This function creates a callback on the setup entry event and boot
event to (respectively) update the CMOS setup variable and clear
the CMOS-based status bits.
Input:
None
Output:
None
Notes:
None


UpdateCmosSetupVariable in the CmosManagerDxe.c

Function : UpdateCmosSetupVariable

File: CmosManagerDxe.c
Description:
This function updates the CMOS setup variable using information
from the CMOS-based status bits.
Input:
IN EFI_EVENT Event
   - Event handle
IN VOID *Context
   - Not used
Output:
None
Notes:


CmosManagerDxe.h

Description:
Contains declarations to support the CMOS Manager
in DXE phase.


CmosManagerHob.c

Description:
Contains the routines that are used to access the
HOB data structure.

The following functions are used in the file: CmosManagerHob.c.

Function | Description
CmosManagerAfterMemoryEntry | This function calls CreateCmosDataHob to create the DXE data HOB after permanent memory has been installed, and updates the new CMOS Access Interface Address, as well as the CMOS-based API pointer.
CmosSynchronizeHobChecksum | This function synchronizes the Checksum information in the CMOS data HOB to be passed to DXE.
CmosSynchronizeHobManagerStatus | This function synchronizes the ManagerStatus information in the CMOS data HOB to be passed to DXE.
CreateCmosDataHob | This function creates the CMOS data HOB, when memory is available.
InitializeCmosDataTablesFromHob | This function locates the HOB containing the table of CMOS tokens and initializes token table information in the CMOS manager's interface.


CmosManagerAfterMemoryEntry in the CmosManagerHob.c

Function : CmosManagerAfterMemoryEntry

File: CmosManagerHob.c
Description:
This function calls CreateCmosDataHob to create the DXE data HOB
after permanent memory has been installed, and updates the new CMOS
Access Interface Address, as well as the CMOS-based API pointer.
Input:
IN EFI_FFS_FILE_HEADER *FfsHeader
   -- EFI_FFS_FILE_HEADER pointer
IN EFI_PEI_SERVICES **PeiServices
   -- PEI Services table pointer
Output:
EFI_STATUS (Return value)
   = EFI_SUCCESS or valid EFI error code
Notes:
This function is used only in PEI phase, included by the build
macro PEI_COMPILE.


CmosSynchronizeHobChecksum in the CmosManagerHob.c

Function : CmosSynchronizeHobChecksum

File: CmosManagerHob.c
Description:
This function synchronizes the Checksum information in
the CMOS data HOB to be passed to DXE.
Input:
OUT EFI_CMOS_MANAGER_INTERFACE *Manager
   -- Manager->ManagerHob->CheckSum = Manager->CheckSum
Output:
VOID (Return value)
Notes:


CmosSynchronizeHobManagerStatus in the CmosManagerHob.c

Function : CmosSynchronizeHobManagerStatus

File: CmosManagerHob.c
Description:
This function synchronizes the ManagerStatus information in
the CMOS data HOB to be passed to DXE.
Input:
IN EFI_CMOS_MANAGER_INTERFACE   *Manager
   -- Manager interface pointer
Output:
VOID (Return value)
Notes:


CreateCmosDataHob in the CmosManagerHob.c

Function : CreateCmosDataHob

File: CmosManagerHob.c
Description:
This function creates the CMOS data HOB, when memory is available.
Input:
IN EFI_CMOS_MANAGER_INTERFACE *Manager
   -- Manager interface pointer
Output:
EFI_STATUS (Return value)
   = EFI_SUCCESS or valid EFI error code
Notes:
This function is used only in PEI phase, included by the build
macro PEI_COMPILE.


InitializeCmosDataTablesFromHob in the CmosManagerHob.c

Function : InitializeCmosDataTablesFromHob

File: CmosManagerHob.c
Description:
This function locates the HOB containing the table of CMOS tokens
and initializes token table information in the CMOS manager's
interface.
Input:
OUT EFI_CMOS_MANAGER_INTERFACE  *Manager
   - The CMOS manager interface to initialize.
Output:
EFI_STATUS (Return value)
   = EFI_SUCCESS or valid EFI error code
Notes:
This function is used only in DXE phase, included by the build
process via the absence of the macro PEI_COMPILE.


CmosManagerHob.h

Description:
Contains declarations to support the CMOS Manager
CMOS_MANAGER_HOB.


CmosManagerPei.c

Description:
Contains the routines that constitute the CMOS manager's
   PEI phase entry.

The following functions are used in the file: CmosManagerPei.c.

Function | Description
CmosManagerPeiEntry | This function is the main PEI phase entry point for the CMOS manager module.


CmosManagerPeiEntry in the CmosManagerPei.c

Function : CmosManagerPeiEntry

File: CmosManagerPei.c
Description:
This function is the main PEI phase entry point for the CMOS
manager module.
Input:
IN EFI_FFS_FILE_HEADER *FfsHeader
   -- FFS file header pointer
IN EFI_PEI_SERVICES **PeiServices
   -- PEI Services table pointer
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS if successful
   = or other valid EFI error code
Notes:
Execution Sequence:
   1)  Initialize CMOS Manager interface
   2)  Load default values into CMOS registers if
       this is the first boot.
   3)  Configure usage of the Optimal Defaults table if
       the battery or checksum is bad.
   4)  Update the CMOS-based API/PPI pointer.
   5)  Install the EFI_CMOS_ACCESS_INTERFACE PPI


CmosManagerPei.h

Description:
Contains declarations to support the CMOS Manager
in PEI phase.


CmosManagerSec.asm

Description:
This file contains all code necessary to support CMOS Manager's SEC
phase initialization and external services.

The following functions are used in the file: CmosManagerSec.asm.

Function | Description
CmosReadWrite | Returns the CMOS value associated with the given CMOS token from the actual CMOS storage. CMOS checksum is don't care. Upon detecting an error, the carry flag is set and an error code is returned in AX.
SEC_CmosManager | This is the entrypoint for CMOS Manager SEC code.


CmosReadWrite in the CmosManagerSec.asm

Function : CmosReadWrite

File: CmosManagerSec.asm
Segment: STARTUP_SEG
Description:
Returns the CMOS value associated with the given CMOS token
from the actual CMOS storage. CMOS checksum is don't care. Upon detecting
an error, the carry flag is set and an error code is returned in AX.
Input:
AX - CMOS Token.
DL - Set for write or Clear for read
DH - Value to write
Output:
AX - CMOS value if reading
NC - If success
CY - If error & AX = Error code
Modified:
AX, MM0, MM1, MM2, MM3
(EDX upper word and EAX upper word are unmodified)
All other registers are preserved
Notes:
An error code is returned in AX with Carry Flag set upon detected
error condition. The following error code constants (defined in
CmosAccessSec.inc) are used:

    CMOS_BATTERY_ERR
    CMOS_BITSIZE_ERR
    CMOS_OVERFLOW_ERR
Referrals:
None


SEC_CmosManager in the CmosManagerSec.asm

Function : SEC_CmosManager

File: CmosManagerSec.asm
Segment: STARTUP_SEG
Description:
This is the entrypoint for CMOS Manager SEC code.
Input:
None
Output:
None
Modified:
None
Notes:
Currently, there are no SEC tasks for the CMOS Manager.
Referrals:
None


CmosManagerSmm.c

Description:
Contains the routines that initialize the CMOS manager's
SMM services.

The following functions are used in the file: CmosManagerSmm.c.

Function | Description
CmosManagerSmmEntry | This function is the entrypoint for installing the SMM driver for CMOS Manager.
GetAslNameObject | This function returns the 64-bit value assigned to the ASL named object.
InSmmFunction | This function is executed from SMM in order to install the SMRAM-based CMOS Access Interface pointer.
SmiHandler | This is called from SMM or ASL code to access CMOS during runtime.
UpdateAslCommunicationBuffer | This function is executed in non-SMM in order to allocate the runtime communication buffer used by the \CMOS.ACCE asl method to use CMOS Manager services at runtime.


CmosManagerSmmEntry in the CmosManagerSmm.c

Function : CmosManagerSmmEntry

File: CmosManagerSmm.c
Description:
This function is the entrypoint for installing the SMM driver for
CMOS Manager.
Input:
IN EFI_HANDLE ImageHandle
   - Image handle
IN EFI_SYSTEM_TABLE *SystemTable
   - System table pointer
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS if successful
   = or other valid EFI error code
Notes:
*  Initializes/Installs the EFI_CMOS_ACCESS_INTERFACE
   Protocol for SMM.


InSmmFunction in the CmosManagerSmm.c

Function : InSmmFunction

File: CmosManagerSmm.c
Description:
This function is executed from SMM in order to install the SMRAM-based
CMOS Access Interface pointer.
Input:
IN EFI_HANDLE ImageHandle
   - Image handle
IN EFI_SYSTEM_TABLE *SystemTable
   - System table pointer
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS if successful
   = or other valid EFI error code
Notes:
*  Initializes/Installs the EFI_CMOS_ACCESS_INTERFACE
   Protocol for SMM.


SmiHandler in the CmosManagerSmm.c

Function : SmiHandler

File: CmosManagerSmm.c
Description:
This is called from SMM or ASL code to access CMOS during
runtime.
Input:
IN EFI_HANDLE DispatchHandle
IN EFI_SMM_SW_DISPATCH_CONTEXT *DispatchContext
Output:
NONE
Modified:
NONE
Notes:

Referrals:


CmosManagerSmm.dxs

Description:
Contains the dependency expression for SMM CMOS
   driver.


CmosManagerSmm.h

Description:
Contains declarations to support the CMOS Access interface
in SMM.


CmosMessages.c

Description:
Contains code to display CMOS-related boot messages.


CmosMessages.mak

Description:
Make file for the CmosMessages.obj


CmosMessages.sdl

Description:
This AMI SDL file defines CMOS message-related information.


CmosSetup.sd

Description:
CMOS Form Template


CmosTables.c

Description:
Contains the global static data tables that are initialized
from AmiSsp2.exe output during the build process. These
tables are used in the PEI phase and passed, as needed,
to DXE via HOB data structure.

This file must always be included in source form.

The following tables are used in the file: CmosTables.c.

Table | Description
gCmosNoCheckSumTable | This is a table of CMOS registers excluded from checksum calculations. This table is derived from Macros defined in SspData.h, which is generated by AmiSsp2.exe during the build process.
gCmosOptimalDefaultTable | This is a table of default (or optimal) CMOS register values derived from Macros defined in SspData.h, which is generated by AmiSsp2.exe during the build process.
gCmosTokenTable | This is a table of CMOS tokens derived from Macros defined in SspData.h, which is generated by AmiSsp2.exe during the build process.
gUnmanagedTable | This is a table of CMOS registers that are allocated, but otherwise unmanaged. The purpose is to provide support for locations that must be written prior to CMOS Manager, and to provide alternative mechanisms in situations where CMOS Manager's loading of default values would cause major implementation problems.

The following descriptions are used in the file: CmosTables.c.

Header | Description
Initialization_Tables | This page provides links to descriptions of the major tables used in initializing/supporting the CMOS Manager module.


gCmosNoCheckSumTable in the CmosTables.c

Table : gCmosNoCheckSumTable

File: CmosTables.c
Description:
This is a table of CMOS registers excluded from checksum
calculations.  This table is derived from Macros defined in
SspData.h, which is generated by AmiSsp2.exe during the build
process.
Notes:
This is an array of type: CMOS_REGISTER


gCmosOptimalDefaultTable in the CmosTables.c

Table : gCmosOptimalDefaultTable

File: CmosTables.c
Description:
This is a table of default (or optimal) CMOS register values derived
from Macros defined in SspData.h, which is generated by AmiSsp2.exe
during the build process.
Notes:
This is an array of type: CMOS_REGISTER


gCmosTokenTable in the CmosTables.c

Table : gCmosTokenTable

File: CmosTables.c
Description:
This is a table of CMOS tokens derived from Macros defined in
SspData.h, which is generated by AmiSsp2.exe during the build
process.
Notes:
This is an array of type: CMOS_TOKEN


gUnmanagedTable in the CmosTables.c

Table : gUnmanagedTable

File: CmosTables.c
Description:
This is a table of CMOS registers that are allocated, but otherwise
unmanaged.  The purpose is to provide support for locations that
must be written prior to CMOS Manager, and to provide alternative
mechanisms in situations where CMOS Manager's loading of default
values would cause major implementation problems.
Notes:
This is an array of type: CMOS_REGISTER

It is up to the owner of the SSP CMOS Token to determine whether
or not the value of an un-managed location is valid.


Initialization_Tables in the CmosTables.c

General : Initialization_Tables

File: CmosTables.c
Fields:

Phase | Name | Description
ALL | gCmosTokenTable | all SSP defined tokens
ALL | gCmosOptimalDefaultTable | default values for all CMOS registers
ALL | gCmosNoCheckSumTable | CMOS addresses that are not checksummed

Description:
This page provides links to descriptions of the major tables used in
initializing/supporting the CMOS Manager module.


CmosTypes.h

Description:
Contains the constants, data types and declarations
necessary to support the CMOS manager module.

The following data structures are used in the file: CmosTypes.h.

Variable | Description
CMOS_BYTE | This structure type is used to define a generic CMOS byte that, among other things, can be used to define an array of CMOS addresses and values to be read or written.
CMOS_CONFIGURATION_SETTING | This enumerated type is used to define a bitmap that represents the requested configuration settings for the CMOS manager. If a bit is set then the associated feature or setting is requested.
CMOS_MANAGER_STATUS | This enumerated type is used to define a bitmap that represents the configuration status of the CMOS manager. If a bit is set then the condition is TRUE. If a bit is clear then the condition it represents is FALSE.
CMOS_REGISTER | This union type is used to define un-encoded register values/numbers.
CMOS_TOKEN | This structure type is used to define CMOS tokens, which are encoded values that define the usage of bits at a particular physical CMOS location.


CMOS_BYTE in the CmosTypes.h

Variable : CMOS_BYTE

File: CmosTypes.h
Fields:

Type | Name | Description
UINT16 | Register | CMOS register associated with this byte
UINT8 | Value | Byte value associated with the specified register

Description:
This structure type is used to define a generic CMOS byte that,
among other things, can be used to define an array of CMOS addresses
and values to be read or written.
Notes:
None
Built on 11:30:58 01/27/12


CMOS_CONFIGURATION_SETTING in the CmosTypes.h

Variable : CMOS_CONFIGURATION_SETTING

File: CmosTypes.h
Description:
This enumerated type is used to define a bitmap that represents the
requested configuration settings for the CMOS manager.  If a bit is
set then the associated feature or setting is requested.
Built on 11:30:58 01/27/12


CMOS_MANAGER_STATUS in the CmosTypes.h

Variable : CMOS_MANAGER_STATUS

File: CmosTypes.h
Fields:

_ Bit Condition
_ CMOS_VALID_MANAGER The manager is initialized
_ CMOS_INTERFACE_ALREADY_INSTALLED The access interface has already been installed
_ CMOS_INSTALL_FAILED The installation of the access interface failed
_ CMOS_VALID_INTERFACE The access interface is valid, but not necessarily installed
_ CMOS_FIRST_BOOT_DETECTED Indicates first boot (after progamming the boot device) is detected
_ CMOS_EXECUTING_IN_MEMORY The CMOS manager is executing in permanent memory
_ CMOS_BAD_CHECKSUM The most recently computed checksum does not equal the saved checksum
_ CMOS_ADDRESS_IS_CHECKSUMMED The most recently accessed address is included in the checksum
_ CMOS_ERROR_LOADING_DEFAULTS CMOS could not be updated from the default optimal data table
_ CMOS_FORCE_NO_CHECKSUM Checksum updating is disabled
_ CMOS_LEGACY_STATUS_ENABLED Update legacy status registers in CMOS
_ CMOS_BAD_BATTERY Bad battery has been detected
_ CMOS_OPTIMAL_DEFAULTS_ENABLED Optimal Defaults buffer is in use
_ CMOS_DEFAULTS_LOADED Optimal Defaults buffer has been written to CMOS
_ CMOS_RECOVER_ONLY_CHECKSUMMED Use Optimal Defaults buffer only for checksummed locations upon incoherency detection
_ CMOS_COLD_BOOT_DETECTED Cold boot was detected
_ CMOS_BSP_IS_EXECUTING BSP is executing
_ CMOS_RECOVER_IN_PEI PEI incoherency recovery (bad checksum & good battery)

Description:
This enumerated type is used to define a bitmap that represents the
configuration status of the CMOS manager.  If a bit is set then
the condition is TRUE.  If a bit is clear then the condition it
represents is FALSE.
Built on 11:30:58 01/27/12


CMOS_REGISTER in the CmosTypes.h

Variable : CMOS_REGISTER

File: CmosTypes.h
Fields:

Type | Name | Description
UINT16 | Value | The un-encoded value of a register
UINT8 | Index | The un-encoded register address

Description:
This union type is used to define un-encoded register
values/numbers.
Built on 11:30:58 01/27/12


CMOS_TOKEN in the CmosTypes.h

Variable : CMOS_TOKEN

File: CmosTypes.h
Fields:

Type | Name | Description
UINT64 | Name | A constant string pointer providing the name associated with the token (available only in debug mode)
union | Value | Provides access to the encoded information in the token (see Notes below)

Description:
This structure type is used to define CMOS tokens, which are encoded
values that define the usage of bits at a particular physical CMOS
location.
Notes:
The Value union provides access to all the bits of the token or to
a specific token data field:

Value.AllBits            All bits of the encoded token data
Value.Field              Provides access to a specific token field
Value.Field.BitOffset    Offset within the CMOS byte
Value.Field.CmosAddress  The actual CMOS location
Value.Field.Size         The number of bits consumed by the token
Built on 11:30:58 01/27/12


Function by Segment

By Segment

The following is a list of the segments.
For a list in alphabetical order, see In Alphabetical Order.
For a list by file name, see By File Name.

  • STARTUP_SEG


STARTUP_SEG

The following functions are used in the segment: STARTUP_SEG.

Function | Description
CmosReadWrite | Returns the CMOS value associated with the given CMOS token from the actual CMOS storage. CMOS checksum is don't care. Upon detecting an error, the carry flag is set and an error code is returned in AX.
SEC_CmosManager | This is the entrypoint for CMOS Manager SEC code.


Functions in Alphabetical Order

In Alphabetical Order

The following topics provide a list in alphabetical order.
For a list by file name, see By File Name.
For a list by segment, see By Segment.

  • A
  • B
  • C
  • D
  • E
  • F
  • G
  • I
  • L
  • M
  • N
  • R
  • S
  • U
  • W
Built on 11:30:58 01/27/12


Functions in Alphabetical Order

A

Data Structure | Description
ADDON_SSP_FILES | There are no default eLinks This eLink is used to update the list of CMOS Token definition files to be processed by AmiSsp2.exe during the build process. For example, the following eLink will add AgesaCmosTokens.SSP to the list of CMOS Token definition files: ELINK Name = "$(AGESA_EFI_DIR)\AgesaCmosTokens.SSP" Parent = "ADDON_SSP_FILES" InvokeOrder = AfterParent End

Built on 11:30:58 01/27/12


Functions in Alphabetical Order

B

Function | Description
BCDToDec | Converts a Decimal value to a BCD value.
BitFieldOverflow | For testing whether or not a Value overflows the field size as specified in Token.

Built on 11:30:58 01/27/12


Functions in Alphabetical Order

C

Function | Description
CalculateChecksum | Calculate the checksum over the entire range of managed CMOS (standard and/or extended CMOS).
CalculateUpdatedCheckSum | Computes a new "updated" CMOS checksum based on the change of value at a single address.
CanClearLegacyStatusBits | Determines whether or not the legacy status bits in CMOS_DIAGNOSTIC_STATUS_REGISTER can be cleared to a non-failure status.
ClearCmosBasedStatus | This function uses the CMOS Manager interface to clear the un-managed private status bits upon boot or setup entry.
CmosBankReadWrite | This function determines which structure in the global CMOS_PORT_MAP array corresponds to the provided CmosAddress and either calls the associated function or uses the associated IO ports to read/write the CMOS register value to/from the CmosParameterValue.
CmosBufferReadWrite | This function provides support for performing the actual read or write from/to a CMOS buffer location (using the Optimal Defaults Table Buffer).
CmosConfigureManager | This function configures the CMOS Manager.
CmosFindToken | Returns index of CMOS token in token table or 0 if not found.
CmosGetDateTime | Return the current date and time
CmosGetMangerInterface | Gets the EFI_CMOS_MANAGER_INTERFACE for the current access interface.
CmosGetTokenFromRegister | Returns encoded token for the specified register.
CmosIsUsable | This function determines whether or not the CMOS is usable. It may be possible to use the CMOS even if the battery is bad.
CmosManagerAfterMemoryEntry | This function calls CreateCmosDataHob to create the DXE data HOB after permanent memory has been installed, and updates the new CMOS Access Interface Address, as well as the CMOS-based API pointer.
CmosManagerAllocatePool | This function allocates memory for all boot phases.
CmosManagerCheckAnyStatus | This function returns true if any of the status bits are set as specified by the BitMap.
CmosManagerCheckStatus | This function returns true if all the status bits are set as specified by the BitMap.
CmosManagerClearStatus | This function clears status bits according to the specified bitmap.
CmosManagerDxeEntry | This function is the main DXE phase entry point for the CMOS manager module.
CmosManagerPeiEntry | This function is the main PEI phase entry point for the CMOS manager module.
CmosManagerSetClearStatus | This function provides a single entry point into the code that actually updates status values.
CmosManagerSetStatus | This function sets status bits according to the specified bitmap.
CmosManagerSmmEntry | This function is the entrypoint for installing the SMM driver for CMOS Manager.
CmosMgrBatteryIsGood | This function is used to determing whether or not the CMOS battery is good.
CmosMgrIsBsp | This function returns TRUE if the currently executing CPU core is the boot strap processor (BSP).
CmosMgrIsColdBoot | This function returns TRUE to specify the platform is always perfoming a cold boot.
CmosMgrIsFirstBoot | This function determines whether or not this is the first boot after programming the boot device (flash part, ROM emulator, ...).
CmosMgrReadRtcIndex | Read the RTC value at the given Index.
CmosMgrWriteRtcIndex | Write the RTC value at the given Index.
CmosPhysicalReadWrite | This function provides support for performing the actual read or write from/to a physical CMOS location.
CmosRead | Reads to CmosValue from the CMOS location specified by CmosToken.
CmosReadWrite | Returns the CMOS value associated with the given CMOS token from the actual CMOS storage. CMOS checksum is don't care. Upon detecting an error, the carry flag is set and an error code is returned in AX.
CmosReadWrite | Decides which version of xxxReadWrite to call based upon the current Access Routing Logic.
CmosReadWriteEncodedToken | This is the main worker function which verifies and either reads/writes a value from/to the CMOS location as specified by the encoded token.
CmosSetDateTime | This routine simply writes the CMOS RTC registers from information provided by the EFI_TIME structure, assuming the information is correct.
CmosSynchronizeHobChecksum | This function synchronizes the Checksum information in the CMOS data HOB to be passed to DXE.
CmosSynchronizeHobManagerStatus | This function synchronizes the ManagerStatus information in the CMOS data HOB to be passed to DXE.
CmosUpdateMemoryStatus | This function is used in the PEI phase to set/clear the CMOS_EXECUTING_IN_MEMORY depending on whether or not the manager is executing after permanent memory has been initialized.
CmosWrite | Writes from CmosValue to CMOS location encoded into CmosToken.
CreateCmosDataHob | This function creates the CMOS data HOB, when memory is available.
CreateEventHandlers | This function creates a callback on the setup entry event and boot event to (respectively) update the CMOS setup variable and clear the CMOS-based status bits.

Data Structure | Description
CMOS_ACCESS_API_BYTE3 | Default value is 0x42 The high byte of the CMOS Access API pointer registers. 1) These registers are in range: 0x10-0x7f. 2) If you change this token, you must modify CmosManager.SSP. 3) Do not set the NMI bit as this is a policy to be implemented by the ReadWrite function.
CMOS_BANK0_DATA | Default value is 0x71 Data I/O port to access CMOS registers in range: 0x0-0x7f.
CMOS_BANK0_INDEX | Default value is 0x70 Index I/O port to access CMOS registers in range: 0x0-0x7f.
CMOS_BATTERY_TEST_MAPPING | The default function is CmosMgrBatteryIsGood. This SDL eLink provides a mechanism to replace the default function for determining whether or not the battery is bad.
CMOS_BYTE | This structure type is used to define a generic CMOS byte that, among other things, can be used to define an array of CMOS addresses and values to be read or written.
CMOS_CONFIGURATION_SETTING | This enumerated type is used to define a bitmap that represents the requested configuration settings for the CMOS manager. If a bit is set then the associated feature or setting is requested.
CMOS_DIAGNOSTIC_STATUS_REGISTER | Default value is 0xe This is the diagnostic status register. (Do not set the NMI bit as this is a policy to be implmeneted by the ReadWrite function.)
CMOS_IS_BSP_MAPPING | The default function is CmosMgrIsBsp. This SDL eLink provides a mechanism to replace the default function for determining whether or not the currently executing CPU core is the boot strap processor (BSP).
CMOS_IS_COLD_BOOT_MAPPING | The default function is CmosMgrIsColdBoot. This SDL eLink provides a mechanism to replace the default function for determining whether or not the platform is executing a cold boot.
CMOS_IS_FIRST_BOOT_MAPPING | The default function is CmosMgrIsFirstBoot. This SDL eLink provides a mechanism to replace the default function for determining whether or not the current execution is the first boot after programming the boot firmware device (flash part, ROM emulator, ...).
CMOS_IS_USABLE_MAPPING | The default function is CmosIsUsable. This SDL eLink provides a mechanism to replace the default function for determining whether or not the CMOS hardware is usable. (Note, the CMOS may be usable even if the battery is bad.)
CMOS_MANAGER_STATUS | This enumerated type is used to define a bitmap that represents the configuration status of the CMOS manager. If a bit is set then the condition is TRUE. If a bit is clear then the condition it represents is FALSE.
CMOS_MANAGER_SUPPORT | This token is the main switch to enable CMOS manager support in Project
CMOS_MESSAGES_SUPPORT | Default value is 0 (CMOS_SETUP_SUPPORT = FALSE by default) This token specifies whether or not messages are displayed to provide CMOS Manager related power-on information.
CMOS_MGR_RECOVER_IN_PEI | Default value is 1 (PEI recovery is enabled) This configures the recovery policy so that the Optimal Defaults buffer is written to CMOS in the PEI phase.
CMOS_MGR_RECOVER_ONLY_CHECKUMMED | Default value is 0 (all Managed Region locations are recovered) 1 = Do not recover non-checksummed locations in the Managed Region 0 = Recover all locations in the Managed Region This configures the recovery policy so that the Optimal Defaults buffer is only used for checksummed locations upon bad checksum detection.
CMOS_MGR_SET_NMI_BIT | Default value is 1 (NMI access is enabled for 0x0-0x7f) 1 = Set NMI bit for access to NMI region 0 = Do not set NMI bit for access to NMI region
CMOS_NMI_BIT_VALUE | Default value is 0x80 (CMOS_MGR_SET_NMI_BIT = TRUE by default) There are two possible values for this token as determined by the value of CMOS_MGR_SET_NMI_BIT: 0x80 = if CMOS_MGR_SET_NMI_BIT == TRUE 0x00 = if CMOS_MGR_SET_NMI_BIT == FALSE
CMOS_PORT_MAPPING | Default value (see Notes below) This Elink is used to associate CMOS register address ranges with an 8-bit index/data port pair or an access function. Additional ranges can be specified by adding additional eLinks. The default eLink for the 0x0-0x7f range can be replaced by first disabling the CMOS_USES_STANDARD_RANGE_ACCESS SDL token and then defining a new eLink.
CMOS_REGISTER | This union type is used to define un-encoded register values/numbers.
CMOS_RTC_STATUS_REGISTER | Default value is 0xd This is the RTC status register. Bit 7 is the battery status. (Do not set the NMI bit as this is a policy to be implmeneted by the ReadWrite function.)
CMOS_SETUP_SUPPORT | Default value is 0 (CMOS_SETUP_SUPPORT = FALSE by default) This token specifies whether or not a setup page is enabled to provide CMOS Manager related information/options.
CMOS_SMM_SUPPORT | Default value is 1 (SMM support is enabled) This token specifies whether or not the CMOS Access interface is available in SMM. 1 = Enable SMM CMOS Access 0 = Disable SMM CMOS Access
CMOS_STATUS_BYTES | This structure type is used to define particular CMOS status bytes.
CMOS_TOKEN | This structure type is used to define CMOS tokens, which are encoded values that define the usage of bits at a particular physical CMOS location.
CMOS_USES_STANDARD_BATTERY_TEST | Default value is 1 (default function is used) This SDL Token specifies whether or not to use the default function to determine whether or not the CMOS battery is good.
CMOS_USES_STANDARD_IS_BSP | Default value is 1 (default function is used) This SDL Token specifies whether or not to use the default function to determine whether or not the boot strap processor is executing. If a platform provides a different function for determining the BSP, this token should be disabled.
CMOS_USES_STANDARD_IS_CMOS_USABLE | Default value is 1 (default function is used) This SDL Token specifies whether or not to use the default function to determine whether or not the CMOS hardware is usable. If a platform provides a different function, this token should be disabled.
CMOS_USES_STANDARD_IS_COLD_BOOT | Default value is 1 (default function is used) This SDL Token specifies whether or not to use the default function to determine whether or not the platform is executing a cold boot.
CMOS_USES_STANDARD_IS_FIRST_BOOT | Default value is 1 (default function is used) This SDL Token specifies whether or not to use the default function to determine whether or not the platform is executing a first boot.
CMOS_USES_STANDARD_RANGE_ACCESS | Default value is 1 (default function is enabled) Specifies whether or not to use CMOS Manager's default access function for the 0-0x7f range. If a platform provides a different access function for this region this token should be FALSE.

Built on 11:30:58 01/27/12


Functions in Alphabetical Order

D

Function | Description
DecodeParameter | Value is shifted right and masked by the bit field's size and offset as specified in Token.

Built on 11:30:58 01/27/12


Functions in Alphabetical Order

E

Function | Description
EncodeParameter | Value is shifted left by the bit field size specified in Token.

Data Structure | Description
EFI_CMOS_ACCESS_INTERFACE | This is the external interface to all the functionality provided by the CMOS Manager to external modules.
EFI_CMOS_MANAGER_INTERFACE | This is the internal interface used by subsystems within the CMOS manager module.

Built on 11:30:58 01/27/12


Functions in Alphabetical Order

F

Data Structure | Description
FIRST_MANAGED_CMOS_ADDRESS | Default value is 0x40 This is the lower limit of the CMOS register range to be managed by CMOS Manager The region starting at FIRST_MANAGED_CMOS_ADDRESS and ending at MAX_MANAGED_CMOS_ADDRESS - 1 represents the managed region.
FULL_CMOS_MANAGER_DEBUG | Default value is 0 1 = Turn on all available CMOS Manager debug messages, resulting in larger build. 0 = Only basic debugging messages are displayed, dependent upon project-level debug settings.

Built on 11:30:58 01/27/12


Functions in Alphabetical Order

G

Function | Description
GetApiPointerFromCmos | This function get the CMOS API pointer from a predefined 4-byte CMOS location and updates the output parameter with the pointer.
GetAslNameObject | This function returns the 64-bit value assigned to the ASL named object.
GetCmosAccessInterface | Gets the EFI_CMOS_ACCESS_INTERFACE for the current manager interface.
GetPointerCmos32 | This routine returns the 32-bit value stored in CMOS where the high byte starts at location specified by register AL.

Table | Description
gCmosNoCheckSumTable | This is a table of CMOS registers excluded from checksum calculations. This table is derived from Macros defined in SspData.h, which is generated by AmiSsp2.exe during the build process.
gCmosOptimalDefaultTable | This is a table of default (or optimal) CMOS register values derived from Macros defined in SspData.h, which is generated by AmiSsp2.exe during the build process.
gCmosTokenTable | This is a table of CMOS tokens derived from Macros defined in SspData.h, which is generated by AmiSsp2.exe during the build process.
gUnmanagedTable | This is a table of CMOS registers that are allocated, but otherwise unmanaged. The purpose is to provide support for locations that must be written prior to CMOS Manager, and to provide alternative mechanisms in situations where CMOS Manager's loading of default values would cause major implementation problems.

Built on 11:30:58 01/27/12


Functions in Alphabetical Order

I

Function | Description
InitializeCmosDataTablesFromHob | This function locates the HOB containing the table of CMOS tokens and initializes token table information in the CMOS manager's interface.
InitializeCmosManagerInterface | This function initializes structure data and function pointer elements for a EFI_CMOS_MANAGER_INTERFACE.
InSmmFunction | This function is executed from SMM in order to install the SMRAM-based CMOS Access Interface pointer.
InstallCmosAccessInterface | This function installs either the PEI or DXE phase interface (PPI or Protocol) for accessing CMOS.

Built on 11:30:58 01/27/12


Functions in Alphabetical Order

L

Function | Description
LoadOptimalDefaults | Initialize all physical CMOS registers with the default values specified in NvramField's Default value.
LOCATE_CMOS_ACCESS_API_POINTER | This Macro initializes InterfacePtr = NULL if the battery is bad. Otherwise, read the four bytes of the CMOS-based API pointer into InterfacePtr, starting at CMOS_ACCESS_API_BYTE3.
LOCATE_CMOS_ACCESS_PPI | This Macro calls (*PeiServices)->LocatePpi() to locate the CMOS access PPI.
LOCATE_CMOS_ACCESS_PROTOCOL | This Macro calls pBS->LocateProtocol() to locate the CMOS access Protocol.
LOCATE_CMOS_ACCESS_SMM_PROTOCOL | This Macro calls pBS->LocateProtocol() to locate the CMOS access Protocol for SMM access to CMOS.

Built on 11:30:58 01/27/12


Functions in Alphabetical Order

M

Function | Description
MaReadCmosByte | Reads a byte from the CMOS location specified by AL.

Data Structure | Description
MAX_MANAGED_CMOS_ADDRESS | Default value is 128 (128 bytes with max address of 127) This is the upper limit (last address + 1) of CMOS address locations that are managed by CMOS Manager. (I.e., if 256 bytes of CMOS is available and is entirely managed by CMOS Manager, then the value of this token would be 256.)

Built on 11:30:58 01/27/12


Functions in Alphabetical Order

N

Function | Description
NewCmosManagerInterface | This function locates (or allocates memory for) the EFI_CMOS_MANAGER_INTERFACE, calculates the checksum, checks the battery condition and updates the Manager's status bits.
NotChecksummed | This function returns TRUE if the CmosAddress is NOT included in the checksum and returns FALSE otherwise.

Built on 11:30:58 01/27/12


Functions in Alphabetical Order

R

Function | Description
READ_CMOS_PPI | This macro calls EFI_CMOS_ACCESS_INTERFACE.Read() to read the CMOS location associated with CmosToken into the value byte at the address specified by CmosValuePtr, after pushing the required arguments onto the stack.
READ_CMOS_REGISTER | This macro calls ReadWriteCmosRegister to read the physical CMOS register specified by CmosRegister into the value byte at the address specified by CmosValuePtr, after pushing the required arguments onto the stack.
READ_CMOS_TOKEN | This macro invokes ReadWriteCmosToken() to read the CMOS location associated with CmosToken into the value byte at the address specified by CmosValuePtr, after pushing the required arguments onto the stack.
ReadChecksum | Reads the checksum from the CMOS register(s).
ReadCmosBytes | Reads Bytes from the specified CMOS register(s).
ReadCmosStatusBytes | Initializes a CMOS_STATUS_BYTES structure and reads the associated CMOS registers.
ReadWriteCmosRegister | This function calls EFI_CMOS_ACCESS_INTERFACE.Write or EFI_CMOS_ACCESS_INTERFACE.Read to write or read a CMOS value to a CMOS register.
ReadWriteCmosToken | This function calls EFI_CMOS_ACCESS_INTERFACE.Write or EFI_CMOS_ACCESS_INTERFACE.Read to write or read a CMOS value to a CMOS register.
ReadWriteStandardRange | This function is used to access addresses in the Standard CMOS register range (0x0-0x7f), for PEI and DXE boot phases.

Built on 11:30:58 01/27/12


Functions in Alphabetical Order

S

Function | Description
SaveApiPointerToCmos | This function saves the specified pointer to a predefined 4-byte CMOS location.
SEC_CmosManager | This is the entrypoint for CMOS Manager SEC code.
SetClobberBits | Creates a mask with bits set corresponding to the size and offset of the bit field as specified by Token.
SmiHandler | This is called from SMM or ASL code to access CMOS during runtime.
StartTime | Start the time on RTC clock. This is used when changing the Date and Time
StopTime | Stops the time on RTC clock.
SynchronizeLegacyStatusRegisters | Synchronizes legacy CMOS status registers with status changes.

Data Structure | Description
SSP | Default value is AMISSP2.exe Defines the location of AmiSsp2.exe, which is used to generate the header files containing CMOS information.

Built on 11:30:58 01/27/12


Functions in Alphabetical Order

U

Function | Description
UpdateAslCommunicationBuffer | This function is executed in non-SMM in order to allocate the runtime communication buffer used by the \CMOS.ACCE asl method to use CMOS Manager services at runtime.
UpdateBatteryStatus | This function is used to update the CMOS battery status. It is up to the user of the Manager interface to determine whether or ot the platform supports this feature. (If the platform does not support this feature, the battery status is indeterminate.)
UpdateCmosSetupVariable | This function updates the CMOS setup variable using information from the CMOS-based status bits.

Built on 11:30:58 01/27/12


Functions in Alphabetical Order

W

Function | Description
WRITE_CMOS_PPI | This macro calls EFI_CMOS_ACCESS_INTERFACE.Write() to write the the value specified by CmosValue to the CMOS location associated with CmosToken, after pushing the required arguments onto the stack.
WRITE_CMOS_REGISTER | This macro calls ReadWriteCmosRegister to write the value specified by CmosValue to the physical CMOS location specified by CmosRegister after pushing the required arguments onto the stack.
WRITE_CMOS_TOKEN | This macro invokes ReadWriteCmosToken() to write the byte specified by CmosValue to the CMOS location associated with CmosToken, after pushing the required arguments onto the stack.
WriteChecksum | Write the checksum to the CMOS register(s).

Built on 11:30:58 01/27/12


General Information

Header | Description
All_Elinks_Tokens | The following files contain the SDL Tokens/Elinks used in the CMOS Manager module, which may be ported. CmosBoard.sdl -- SDL Tokens/Elinks typically used for project-specific porting CmosManager.sdl -- SDL Tokens/Elinks typically not modified
CMOS_Manager_Initialization_and_Usage | This page provides an outline of the steps required for CMOS Manager initialization and services usage.
Entry_Functions | This page provides links to descriptions of the PEI and DXE phase entrypoint functions for the CMOS Manager module.
Initialization_Tables | This page provides links to descriptions of the major tables used in initializing/supporting the CMOS Manager module.
Internal_Interfaces | The page provides links to descriptions of the internal interfaces used by the CMOS Manager's subsystems.
Macros | The page provides links to Macros that can be used by CMOS Manager client modules.
Protocols_and_PPI | This page provides links to the Protocols and PPI installed by this module. These are the external interfaces to the CMOS Manager module's services.
Terms | This page defines/clarifies the implied/intended meaning for the terminology used in the CMOS Manager module's documentation.


GetAslNameObject in the CmosManagerSmm.c

Function : GetAslNameObject

File: CmosManagerSmm.c
Description:
This function returns the 64-bit value assigned to the ASL named
object.
Input:
IN ACPI_HDR *PDsdt
   - pointer to the DSDT table
IN UINT8 *ObjName
   - pointer to the name string
OUT UINT64 *Value
   - pointer to the value to be updated
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS if successful
   = or other valid EFI error code
Notes:
N/A


UpdateAslCommunicationBuffer in the CmosManagerSmm.c

Function : UpdateAslCommunicationBuffer

File: CmosManagerSmm.c
Description:
This function is executed in non-SMM in order to allocate the
runtime communication buffer used by the \CMOS.ACCE asl method
to use CMOS Manager services at runtime.
Input:
N/A
Output:
EFI_STATUS (Return Value)
   = EFI_SUCCESS if successful
   = or other valid EFI error code
Notes:
N/A