//
// Copyright (R) 1999-2000 Microsoft Corporation. All rights reserved.
//
// PURPOSE:
//  File contains declarations for the Non-Volatile RAM Driver
//  for the Windows-based Server Appliance.
//
//  This driver reads and writes to non-volatile RAM provided to
//  the OS by the OEM hardware. It also provides for the OEM to
//  indicate to the OS that power has cycled since the last boot
//  attempt that succeeded, from the BIOS perspective.
//
//  File Name:  SaMSNVRamIoctl.h
//  Originally: SaNVRamIoctl.h
//
#ifndef __SAMSNVRAM_IOCTL__
#define __SAMSNVRAM_IOCTL__


//
// Device Names
//
    // System Registered device name
#define PDEVICENAME_SANVRAM  (L"\\Device\\SANVRAM")

    // Device Symbolic name
#define PDEVSYMBOLICNAME_SANVRAM  (L"\\??\\SANVRAM1")

    // Device symbolic name as used in CreateFile
#define PDEVFILENAME_SANVRAM  (L"\\\\.\\SANVRAM1")

//
// IOCTL control codes
//

///////////////////////////////////////////////
// GET_VERSION
//
#define IOCTL_SANVRAM_GET_VERSION\
        CTL_CODE( FILE_DEVICE_UNKNOWN, 0xD01,\
                METHOD_BUFFERED, FILE_ANY_ACCESS )

//
// Structures used by the IOCTL codes
//
typedef struct _SANVRAM_GET_VER_OUT_BUFF {
        DWORD   Version;
} SANVRAM_GET_VER_OUT_BUFF, *PSANVRAM_GET_VER_OUT_BUFF;

//
// version bits
//
#ifndef VERSION_INFO
#define VERSION_INFO
#define VERSION1  0x1
#define VERSION2  0x2
#define VERSION3  0x4
#define VERSION4  0x8
#define VERSION5  0x10
#define VERSION6  0x20
#define VESRION7  0x40
#define VESRION8  0x80

#define THIS_VERSION VERSION2
#endif    //#ifndef VERSION_INFO


///////////////////////////////////////////////
// GET_CAPABILTIES
// Returns a DWORD with bits indicating capabilities.

#define IOCTL_SANVRAM_GET_CAPABILITIES\
        CTL_CODE( FILE_DEVICE_UNKNOWN, 0xD02,\
                METHOD_BUFFERED, FILE_ANY_ACCESS )
//
// Structures used by the IOCTL codes
//
typedef struct _SANVRAM_GET_CAPS_OUT_BUFF {
    DWORD   Version;
    DWORD   Capability;
}  SANVRAM_GET_CAPS_OUT_BUFF, *PSANVRAM_GET_CAPS_OUT_BUFF;


/////////////////////////////////////////////////////////////////////////////
// Semantics of the fields of the SANVRAM_GET_CAPS_OUT_BUFF structure.
//
// Version: Must have exactly one bit set, and must be one of the bits
//          set in the Version field on a prior return from the IOCTL
//          IOCTL_SANVRAM_GET_VERSION. The driver is required to
//          support the VERSION1 interface defined in this header.
//          At this time no other version is defined.
//
// Capability bits: Indicates that this driver supports the non-volatile RAM
//                  interface and that this driver supports the knowledge of
//                  whether the power has cycled since the last boot up. See
//                  the semantics for the relevant bits in the IOCTL_SANVRAM
//                  call below.
//
#define NON_VOLATILE_RAM    0x01 // set if driver supports non-volatile RAM
#define POWER_CYCLE_INFO    0x02 // set if driver supports power cycle info



///////////////////////////////////////////////
// IOCTL_SANVRAM
// Returns the input structure with actions taken
// as described in the discussion below. The input
// and output are identical in size and structure.
//
#define IOCTL_SANVRAM\
        CTL_CODE( FILE_DEVICE_UNKNOWN, 0xD03,\
                METHOD_BUFFERED, FILE_ANY_ACCESS )

//
// Structures used by this IOCTL code,
//
typedef struct _SANVRAM__BUFF {
    IN     DWORD  Version;      // version of interface used
    IN     DWORD  FlagsControl; // bit field indicating desired actions
    OUT    DWORD  FlagsInfo;    // bit field indicating state
    IN OUT DWORD  FirstDWORD;   // First uninterpreted DWORD: non-volatile RAM
    IN OUT DWORD  SecondDWORD;  // Second uninterpreted DWORD: non-volatile RAM
} SANVRAM__BUFF, *PSANVRAM__BUFF;


/////////////////////////////////////////////////////////////////////////////
// Semantics of the fields of the SANVRAM_BUFF structure.
//
// Version: Must have exactly one bit set, and must be one of the bits
//          set in the Version field on a prior return from the IOCTL
//          IOCTL_SANVRAM_GET_VERSION. The driver is required to
//          support the VERSION1 interface defined in this header.
//          At this time no other version is defined.

// FlagsControl: Flags indicating the desired actions. The two DWORD values
//               may be set, read, or both set and read. Setting the values
//               in a single call must precede reading them. Requested
//               reads and writes must take place directly to and from the
//               non-volatile media. (Thus if a standard C optimizer is used
//               with the compiler, and both a write and a read are requested,
//               then optimizations should be turned off for these actions,
//               perhaps by using the "volatile" key word.) The two DWORD
//               values are independently controlled. There are two bits
//               for the first DWORD and two for the second.
//
//               NOTE:: Writing to the media
//               dedicated to the two non-volatile DWORDS MUST occur WHEN
//               and ONLY when commanded by these bits. This requirement
//               must be globally honored in time and space, through
//               failures, disk changes, etc.
//
#define FirstDWORD_WRITE      (0x01) // set if first DWORD is to be written
#define SecondDWORD_WRITE     (0x02) // set if second DWORD is to be written
#define FirstDWORD_READ       (0x04) // set if first DWORD is to be read
#define SecondDWORD_READ      (0x08) // set if second DWORD is to be read
#define REQUEST_ALTERNATE_OS  (0x10) // set if alternate OS is to be requested
#define NOTIFY_SYSTEM_FAILURE (0x20) // set to notify that alternate OS failed 
#define INDICATE_LAST_CALL    (0x40) // set to notify that this is last call before shutdown or reboot
//
// FlagsInfo: Bit field for output flags: Flag indicates whether the power
//            has cycled between the current boot of an operating system on
//            this machine and the last.  It indicates that this is the
//            first boot of an operating system since power had been off.
//            This bit has no significance if the capability to give this
//            information has not been declared with the POWER_CYCLE_INFO
//            bit. If the power cycle capability is provided, then this bit is
//            set on ALL boot attempts subsequent to a power cycle until a
//            boot succeedes sufficiently that the OS sets the BIOS boot
//            counter to zero. Stated differently we have that, after a
//            power cycle, the POWER_CYCLED bit will be set on all calls
//            to this function, until a boot attempt is under way that is
//            subsequent to a boot in which the OS made a call with the bit
//            RESET_BIOS_BOOT_COUNT set.
//
//            The behavior is given in the following matrix where pre-reset is
//            prior to a call to the NVRAM driver indicating to reset the bit,
//            and post-reset is after such a call.
//            In the matrix a non-PCB is a boot that was not occasioned
//            by the power coming up ( a non Power Cycle Boot). The running state
//            of the system is characterized here by whether the immediately 
//            preceding boot was occasioned by a power up, and whether, according
//            to the matrix, the power cycle bit was set prior to the boot. Note 
//            that semantically "power cycle boot" includes all boots (CPU resets)
//            that are occasioned by direct user actions. On most server appliances
//            this is covered by power cycles. However, if the user has some other
//            means to request a reboot of the box, e.g., a reset switch, then that
//            action is included in the status of a "power cycle boot." On such a 
//            hardware platform it is perhaps more accurate to call this a 
//            "user action" boot, and add that as a set it includes all power 
//            cycles.
//
//           | Power Cycle Bit Set Before Boot | Power Cycle Bit Clear Before Boot |
//           -----------------------------------------------------------------------
//           | Power Cycle Boot | non-PCB      | Power Cycle Boot | non-PCB        |
//           -----------------------------------------------------------------------
// pre-reset |   Set            |  Set         |      Set         |    Clear       |
// ---------------------------------------------------------------------------------
// post-reset|   Clear          |  Clear       |      Clear       |    Clear       |
// ---------------------------------------------------------------------------------
//
#define POWER_CYCLED            0x01 // set if power has cycled,

//
// FirstDWORD:
// SecondDWORD:
//      These values are simply stored and retrieved, they are not interpreted
//      at this level.
//      They must be stored in
//      non-volatile storage and will be written on boots, updates of the OS,
//      and shutdowns. They will therefore be written sufficiently infrequently
//      that slow non-volatile RAM technologies, such as Flash ROM, can be
//      suitable from a performance perspective. The lifetime of a particular
//      technology in write-cycles must be considered relative to the intended
//      design life between service or perhaps the total design life of the
//      particular server appliance.
//
//////////////////////////////////////////////////////////////////////////////



#endif // __SAMSNVRAM_IOCTL__