MdeModulePkg/Include/Protocol/VariablePolicy.h

   1 /** @file -- VariablePolicy.h
   2
   3 This protocol allows communication with Variable Policy Engine.
   4
   5 Copyright (c) Microsoft Corporation.
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7 **/
   8
   9 #ifndef __EDKII_VARIABLE_POLICY_PROTOCOL__
  10 #define __EDKII_VARIABLE_POLICY_PROTOCOL__
  11
  12 #define EDKII_VARIABLE_POLICY_PROTOCOL_REVISION   0x0000000000010000
  13
  14 #define EDKII_VARIABLE_POLICY_PROTOCOL_GUID \
  15   { \
  16     0x81D1675C, 0x86F6, 0x48DF, { 0xBD, 0x95, 0x9A, 0x6E, 0x4F, 0x09, 0x25, 0xC3 } \
  17   }
  18
  19 #define VARIABLE_POLICY_ENTRY_REVISION      0x00010000
  20
  21 #pragma pack(push, 1)
  22 typedef struct {
  23   UINT32   Version;
  24   UINT16   Size;
  25   UINT16   OffsetToName;
  26   EFI_GUID Namespace;
  27   UINT32   MinSize;
  28   UINT32   MaxSize;
  29   UINT32   AttributesMustHave;
  30   UINT32   AttributesCantHave;
  31   UINT8    LockPolicyType;
  32   UINT8    Padding[3];
  33   // UINT8    LockPolicy[];     // Variable Length Field
  34   // CHAR16   Name[]            // Variable Length Field
  35 } VARIABLE_POLICY_ENTRY;
  36
  37 #define     VARIABLE_POLICY_NO_MIN_SIZE             0
  38 #define     VARIABLE_POLICY_NO_MAX_SIZE             MAX_UINT32
  39 #define     VARIABLE_POLICY_NO_MUST_ATTR            0
  40 #define     VARIABLE_POLICY_NO_CANT_ATTR            0
  41
  42 #define     VARIABLE_POLICY_TYPE_NO_LOCK            0
  43 #define     VARIABLE_POLICY_TYPE_LOCK_NOW           1
  44 #define     VARIABLE_POLICY_TYPE_LOCK_ON_CREATE     2
  45 #define     VARIABLE_POLICY_TYPE_LOCK_ON_VAR_STATE  3
  46
  47 typedef struct {
  48   EFI_GUID Namespace;
  49   UINT8    Value;
  50   UINT8    Padding;
  51   // CHAR16   Name[];           // Variable Length Field
  52 } VARIABLE_LOCK_ON_VAR_STATE_POLICY;
  53 #pragma pack(pop)
  54
  55 /**
  56   This API function disables the variable policy enforcement. If it's
  57   already been called once, will return EFI_ALREADY_STARTED.
  58
  59   @retval     EFI_SUCCESS
  60   @retval     EFI_ALREADY_STARTED   Has already been called once this boot.
  61   @retval     EFI_WRITE_PROTECTED   Interface has been locked until reboot.
  62   @retval     EFI_WRITE_PROTECTED   Interface option is disabled by platform PCD.
  63
  64 **/
  65 typedef
  66 EFI_STATUS
  67 (EFIAPI *DISABLE_VARIABLE_POLICY)(
  68   VOID
  69   );
  70
  71 /**
  72   This API function returns whether or not the policy engine is
  73   currently being enforced.
  74
  75   @param[out]   State       Pointer to a return value for whether the policy enforcement
  76                             is currently enabled.
  77
  78   @retval     EFI_SUCCESS
  79   @retval     Others        An error has prevented this command from completing.
  80
  81 **/
  82 typedef
  83 EFI_STATUS
  84 (EFIAPI *IS_VARIABLE_POLICY_ENABLED)(
  85   OUT BOOLEAN *State
  86   );
  87
  88 /**
  89   This API function validates and registers a new policy with
  90   the policy enforcement engine.
  91
  92   @param[in]  NewPolicy     Pointer to the incoming policy structure.
  93
  94   @retval     EFI_SUCCESS
  95   @retval     EFI_INVALID_PARAMETER   NewPolicy is NULL or is internally inconsistent.
  96   @retval     EFI_ALREADY_STARTED     An identical matching policy already exists.
  97   @retval     EFI_WRITE_PROTECTED     The interface has been locked until the next reboot.
  98   @retval     EFI_ABORTED             A calculation error has prevented this function from completing.
  99   @retval     EFI_OUT_OF_RESOURCES    Cannot grow the table to hold any more policies.
 100
 101 **/
 102 typedef
 103 EFI_STATUS
 104 (EFIAPI *REGISTER_VARIABLE_POLICY)(
 105   IN CONST VARIABLE_POLICY_ENTRY  *PolicyEntry
 106   );
 107
 108 /**
 109   This API function will dump the entire contents of the variable policy table.
 110
 111   Similar to GetVariable, the first call can be made with a 0 size and it will return
 112   the size of the buffer required to hold the entire table.
 113
 114   @param[out]     Policy  Pointer to the policy buffer. Can be NULL if Size is 0.
 115   @param[in,out]  Size    On input, the size of the output buffer. On output, the size
 116                           of the data returned.
 117
 118   @retval     EFI_SUCCESS             Policy data is in the output buffer and Size has been updated.
 119   @retval     EFI_INVALID_PARAMETER   Size is NULL, or Size is non-zero and Policy is NULL.
 120   @retval     EFI_BUFFER_TOO_SMALL    Size is insufficient to hold policy. Size updated with required size.
 121
 122 **/
 123 typedef
 124 EFI_STATUS
 125 (EFIAPI *DUMP_VARIABLE_POLICY)(
 126   IN OUT UINT8  *Policy,
 127   IN OUT UINT32 *Size
 128   );
 129
 130 /**
 131   This API function locks the interface so that no more policy updates
 132   can be performed or changes made to the enforcement until the next boot.
 133
 134   @retval     EFI_SUCCESS
 135   @retval     Others        An error has prevented this command from completing.
 136
 137 **/
 138 typedef
 139 EFI_STATUS
 140 (EFIAPI *LOCK_VARIABLE_POLICY)(
 141   VOID
 142   );
 143
 144 typedef struct {
 145   UINT64                     Revision;
 146   DISABLE_VARIABLE_POLICY    DisableVariablePolicy;
 147   IS_VARIABLE_POLICY_ENABLED IsVariablePolicyEnabled;
 148   REGISTER_VARIABLE_POLICY   RegisterVariablePolicy;
 149   DUMP_VARIABLE_POLICY       DumpVariablePolicy;
 150   LOCK_VARIABLE_POLICY       LockVariablePolicy;
 151 } _EDKII_VARIABLE_POLICY_PROTOCOL;
 152
 153 typedef _EDKII_VARIABLE_POLICY_PROTOCOL EDKII_VARIABLE_POLICY_PROTOCOL;
 154
 155 extern EFI_GUID gEdkiiVariablePolicyProtocolGuid;
 156
 157 #endif