EdkCompatibilityPkg/Foundation/Framework/Protocol/Hii/Hii.h

   1 /*++
   2
   3 Copyright (c) 2004 - 2006, Intel Corporation
   4 All rights reserved. This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 Module Name:
  13
  14   Hii.h
  15
  16 Abstract:
  17
  18   This file defines the Human Interface Infrastructure protocol which will
  19   be used by resources which want to publish IFR/Font/String data and have it
  20   collected by the Configuration engine.
  21
  22 --*/
  23
  24 #ifndef _HII_H_
  25 #define _HII_H_
  26
  27 #include "EfiInternalFormRepresentation.h"
  28 #include EFI_PROTOCOL_DEFINITION (UgaDraw)
  29 #include EFI_PROTOCOL_DEFINITION (GraphicsOutput)
  30
  31 //
  32 // EFI_HII_PROTOCOL_GUID has been changed from the one defined in Framework HII 0.92 as the
  33 // Framework HII protocol produced by HII Thunk Layer support the UEF IFR and UEFI String Package
  34 // format.
  35 //
  36 #define EFI_HII_PROTOCOL_GUID \
  37   { \
  38     0x5542cce1, 0xdf5c, 0x4d1b, { 0xab, 0xca, 0x36, 0x4f, 0x77, 0xd3, 0x99, 0xfb } \
  39   }
  40
  41 /*
  42 #define EFI_HII_PROTOCOL_GUID \
  43   { \
  44     0xd7ad636e, 0xb997, 0x459b, {0xbf, 0x3f, 0x88, 0x46, 0x89, 0x79, 0x80, 0xe1} \
  45   }
  46 */
  47
  48 //
  49 // Forward reference for pure ANSI compatability
  50 //
  51 typedef struct _EFI_HII_PROTOCOL  EFI_HII_PROTOCOL;
  52
  53 //
  54 // Global definition
  55 //
  56 #define NARROW_CHAR         0xFFF0
  57 #define WIDE_CHAR           0xFFF1
  58 #define NON_BREAKING_CHAR   0xFFF2
  59 #define GLYPH_WIDTH         8
  60 #define GLYPH_HEIGHT        19
  61
  62 #define EFI_HII_FONT        1
  63 #define EFI_HII_STRING      2
  64 #define EFI_HII_IFR         3
  65 #define EFI_HII_KEYBOARD    4
  66 #define EFI_HII_HANDLES     5
  67 #define EFI_HII_VARIABLE    6
  68 #define EFI_HII_DEVICE_PATH 7
  69
  70 #define HANG(foo) { \
  71     volatile INT32  __iii; \
  72     __iii = foo; \
  73     while (__iii) \
  74       ; \
  75   }
  76 //
  77 // #define HANG(foo)
  78 //
  79 // References to string tokens must use this macro to enable scanning for
  80 // token usages.
  81 //
  82 #define STRING_TOKEN(t) t
  83
  84 //
  85 // The following types are currently defined:
  86 //
  87 typedef UINT16  EFI_FORM_ID;
  88 typedef UINT16  EFI_FORM_LABEL;
  89 typedef UINT16  EFI_HII_HANDLE;
  90
  91 #pragma pack(1)
  92
  93 typedef struct {
  94   UINT32  Length;
  95   UINT16  Type;
  96 } EFI_HII_PACK_HEADER;
  97
  98 //
  99 // A form list consists of a large variety of structure
 100 // possibilities so to represent the binary blob of data
 101 // associated with a package of forms, we will assume a
 102 // pointer to a self-describing data buffer.
 103 //
 104 typedef struct {
 105   EFI_HII_PACK_HEADER Header;
 106 } EFI_HII_IFR_PACK;
 107
 108 typedef struct {
 109   EFI_HII_PACK_HEADER Header;           // Must be filled in
 110   EFI_HANDLE          ImageHandle;      // Must be filled in
 111   EFI_HANDLE          DeviceHandle;     // Optional
 112   EFI_HANDLE          ControllerHandle; // Optional
 113   EFI_HANDLE          CallbackHandle;   // Optional
 114   EFI_HANDLE          COBExportHandle;  // Optional
 115 } EFI_HII_HANDLE_PACK;
 116
 117 //
 118 // ********************************************************
 119 // EFI_VARIABLE_CONTENTS
 120 // ********************************************************
 121 //
 122 typedef struct {
 123   EFI_HII_PACK_HEADER Header;
 124   EFI_GUID            VariableGuid;
 125   UINT32              VariableNameLength;
 126   UINT16              VariableId;
 127   //
 128   //  CHAR16                VariableName[]; //Null-terminated
 129   //
 130 } EFI_HII_VARIABLE_PACK;
 131
 132 //
 133 // ********************************************************
 134 // EFI_DEVICE_PATH_PACK
 135 // ********************************************************
 136 //
 137 typedef struct {
 138   EFI_HII_PACK_HEADER Header;
 139   //
 140   //  EFI_DEVICE_PATH       DevicePath[];
 141   //
 142 } EFI_HII_DEVICE_PATH_PACK;
 143
 144 //
 145 // ********************************************************
 146 // EFI_HII_DATA_TABLE
 147 // ********************************************************
 148 //
 149 typedef struct {
 150   EFI_HII_HANDLE  HiiHandle;
 151   EFI_GUID        PackageGuid;
 152   UINT32          DataTableSize;
 153   UINT32          IfrDataOffset;
 154   UINT32          StringDataOffset;
 155   UINT32          VariableDataOffset;
 156   UINT32          DevicePathOffset;
 157   UINT32          NumberOfVariableData;
 158   UINT32          NumberOfLanguages;
 159   //
 160   // EFI_HII_DEVICE_PATH_PACK DevicePath[];
 161   // EFI_HII_VARIABLE_PACK VariableData[];
 162   // EFI_HII_IFR_PACK IfrData;
 163   // EFI_HII_STRING_PACK StringData[];
 164   //
 165 } EFI_HII_DATA_TABLE;
 166
 167 //
 168 // ********************************************************
 169 // EFI_HII_EXPORT_TABLE
 170 // ********************************************************
 171 //
 172 typedef struct {
 173   UINT16    NumberOfHiiDataTables;
 174   EFI_GUID  Revision;
 175   //
 176   // EFI_HII_DATA_TABLE HiiDataTable[];
 177   //
 178 } EFI_HII_EXPORT_TABLE;
 179
 180 typedef struct {
 181   BOOLEAN               FormSetUpdate;      // If TRUE, next variable is significant
 182   EFI_PHYSICAL_ADDRESS  FormCallbackHandle; // If not 0, will update Formset with this info
 183   BOOLEAN               FormUpdate;         // If TRUE, next variable is significant
 184   UINT16                FormValue;          // specify which form is to be updated if FormUpdate value is TRUE.
 185   STRING_REF            FormTitle;          // If not 0, will update Form with this info
 186   UINT16                DataCount;          // The number of Data entries in this structure
 187   UINT8                 *Data;              // An array of 1+ op-codes, specified by DataCount
 188 } EFI_HII_UPDATE_DATA;
 189
 190 //
 191 // String attributes
 192 //
 193 #define LANG_RIGHT_TO_LEFT  0x00000001
 194
 195 //
 196 // A string package is used to localize strings to a particular
 197 // language.  The package is associated with a particular driver
 198 // or set of drivers.  Tools are used to associate tokens with
 199 // string references in forms and in programs.  These tokens are
 200 // language agnostic.  When paired with a language pack (directly
 201 // or indirectly), the string token resolves into an actual
 202 // UNICODE string.  The NumStringPointers determines how many
 203 // StringPointers (offset values) there are as well as the total
 204 // number of Strings that are defined.
 205 //
 206 typedef struct {
 207   EFI_HII_PACK_HEADER Header;
 208   RELOFST             LanguageNameString;
 209   RELOFST             PrintableLanguageName;
 210   UINT32              NumStringPointers;
 211   UINT32              Attributes;
 212   //
 213   //  RELOFST               StringPointers[];
 214   //  EFI_STRING            Strings[];
 215   //
 216 } EFI_HII_STRING_PACK;
 217
 218 //
 219 // We use this one to get the real size of the header
 220 //
 221 typedef struct {
 222   EFI_HII_PACK_HEADER Header;
 223   RELOFST             LanguageNameString;
 224   RELOFST             PrintableLanguageName;
 225   UINT32              NumStringPointers;
 226   UINT32              Attributes;
 227 } EFI_HII_STRING_PACK_HEADER;
 228
 229 //
 230 // Glyph Attributes
 231 //
 232 #define GLYPH_NON_SPACING   1
 233 #define GLYPH_NON_BREAKING  2
 234
 235 typedef struct {
 236   CHAR16  UnicodeWeight;
 237   UINT8   Attributes;
 238   UINT8   GlyphCol1[GLYPH_HEIGHT];
 239 } EFI_NARROW_GLYPH;
 240
 241 typedef struct {
 242   CHAR16  UnicodeWeight;
 243   UINT8   Attributes;
 244   UINT8   GlyphCol1[GLYPH_HEIGHT];
 245   UINT8   GlyphCol2[GLYPH_HEIGHT];
 246   UINT8   Pad[3];
 247 } EFI_WIDE_GLYPH;
 248
 249 //
 250 // A font list consists of a font header followed by a series
 251 // of glyph structures.  Note that fonts are not language specific.
 252 //
 253 typedef struct {
 254   EFI_HII_PACK_HEADER Header;
 255   UINT16              NumberOfNarrowGlyphs;
 256   UINT16              NumberOfWideGlyphs;
 257 } EFI_HII_FONT_PACK;
 258
 259 //
 260 // The IfrData in the EFI_HII_IFR_PACK structure definition
 261 // is variable length, and not really part of the header. To
 262 // simplify from code the size of the header, define an
 263 // identical structure that does not include the IfrData field.
 264 // Then use sizeof() this new structure to determine the
 265 // actual size of the header.
 266 //
 267 typedef struct {
 268   EFI_HII_PACK_HEADER Header;
 269 } EFI_HII_IFR_PACK_HEADER;
 270
 271 //
 272 // pedef EFI_HII_PACK_HEADER EFI_HII_IFR_PACK_HEADER;
 273 //
 274 typedef enum {
 275   EfiKeyLCtrl,
 276   EfiKeyA0,
 277   EfiKeyLAlt,
 278   EfiKeySpaceBar,
 279   EfiKeyA2,
 280   EfiKeyA3,
 281   EfiKeyA4,
 282   EfiKeyRCtrl,
 283   EfiKeyLeftArrow,
 284   EfiKeyDownArrow,
 285   EfiKeyRightArrow,
 286   EfiKeyZero,
 287   EfiKeyPeriod,
 288   EfiKeyEnter,
 289   EfiKeyLShift,
 290   EfiKeyB0,
 291   EfiKeyB1,
 292   EfiKeyB2,
 293   EfiKeyB3,
 294   EfiKeyB4,
 295   EfiKeyB5,
 296   EfiKeyB6,
 297   EfiKeyB7,
 298   EfiKeyB8,
 299   EfiKeyB9,
 300   EfiKeyB10,
 301   EfiKeyRshift,
 302   EfiKeyUpArrow,
 303   EfiKeyOne,
 304   EfiKeyTwo,
 305   EfiKeyThree,
 306   EfiKeyCapsLock,
 307   EfiKeyC1,
 308   EfiKeyC2,
 309   EfiKeyC3,
 310   EfiKeyC4,
 311   EfiKeyC5,
 312   EfiKeyC6,
 313   EfiKeyC7,
 314   EfiKeyC8,
 315   EfiKeyC9,
 316   EfiKeyC10,
 317   EfiKeyC11,
 318   EfiKeyC12,
 319   EfiKeyFour,
 320   EfiKeyFive,
 321   EfiKeySix,
 322   EfiKeyPlus,
 323   EfiKeyTab,
 324   EfiKeyD1,
 325   EfiKeyD2,
 326   EfiKeyD3,
 327   EfiKeyD4,
 328   EfiKeyD5,
 329   EfiKeyD6,
 330   EfiKeyD7,
 331   EfiKeyD8,
 332   EfiKeyD9,
 333   EfiKeyD10,
 334   EfiKeyD11,
 335   EfiKeyD12,
 336   EfiKeyD13,
 337   EfiKeyDel,
 338   EfiKeyEnd,
 339   EfiKeyPgDn,
 340   EfiKeySeven,
 341   EfiKeyEight,
 342   EfiKeyNine,
 343   EfiKeyE0,
 344   EfiKeyE1,
 345   EfiKeyE2,
 346   EfiKeyE3,
 347   EfiKeyE4,
 348   EfiKeyE5,
 349   EfiKeyE6,
 350   EfiKeyE7,
 351   EfiKeyE8,
 352   EfiKeyE9,
 353   EfiKeyE10,
 354   EfiKeyE11,
 355   EfiKeyE12,
 356   EfiKeyBackSpace,
 357   EfiKeyIns,
 358   EfiKeyHome,
 359   EfiKeyPgUp,
 360   EfiKeyNLck,
 361   EfiKeySlash,
 362   EfiKeyAsterisk,
 363   EfiKeyMinus,
 364   EfiKeyEsc,
 365   EfiKeyF1,
 366   EfiKeyF2,
 367   EfiKeyF3,
 368   EfiKeyF4,
 369   EfiKeyF5,
 370   EfiKeyF6,
 371   EfiKeyF7,
 372   EfiKeyF8,
 373   EfiKeyF9,
 374   EfiKeyF10,
 375   EfiKeyF11,
 376   EfiKeyF12,
 377   EfiKeyPrint,
 378   EfiKeySLck,
 379   EfiKeyPause
 380 } EFI_KEY;
 381
 382 typedef struct {
 383   EFI_KEY Key;
 384   CHAR16  Unicode;
 385   CHAR16  ShiftedUnicode;
 386   CHAR16  AltGrUnicode;
 387   CHAR16  ShiftedAltGrUnicode;
 388   UINT16  Modifier;
 389 } EFI_KEY_DESCRIPTOR;
 390
 391 //
 392 // This structure allows a sparse set of keys to be redefined
 393 // or a complete redefinition of the keyboard layout.  Most
 394 // keyboards have a lot of commonality in their layouts, therefore
 395 // only defining those keys that need to change from the default
 396 // minimizes the passed in information.
 397 //
 398 // Additionally, when an update occurs, the active keyboard layout
 399 // will be switched to the newly updated keyboard layout.  This
 400 // allows for situations that when a keyboard layout driver is
 401 // loaded as part of system initialization, the system will default
 402 // the keyboard behavior to the new layout.
 403 //
 404 // Each call to update the keyboard mapping should contain the
 405 // complete set of key descriptors to be updated, since every
 406 // call to the HII which contains an EFI_HII_KEYBOARD_PACK will
 407 // wipe the previous set of overrides.  A call to
 408 //
 409 typedef struct {
 410   EFI_HII_PACK_HEADER Header;
 411   EFI_KEY_DESCRIPTOR  *Descriptor;
 412   UINT8               DescriptorCount;
 413 } EFI_HII_KEYBOARD_PACK;
 414
 415 //
 416 // The EFI_HII_PACKAGES can contain different types of packages just
 417 // after the structure as inline data.
 418 //
 419 typedef struct {
 420   UINTN     NumberOfPackages;
 421   EFI_GUID  *GuidId;
 422   //
 423   // EFI_HII_HANDLE_PACK    *HandlePack;        // Only one pack.
 424   // EFI_HII_IFR_PACK       *IfrPack;           // Only one pack.
 425   // EFI_HII_FONT_PACK      *FontPack[];        // Multiple packs ok
 426   // EFI_HII_STRING_PACK    *StringPack[];      // Multiple packs ok
 427   // EFI_HII_KEYBOARD_PACK  *KeyboardPack[];    // Multiple packs ok
 428   //
 429 } EFI_HII_PACKAGES;
 430
 431 typedef struct _EFI_HII_VARIABLE_PACK_LIST {
 432   struct _EFI_HII_VARIABLE_PACK_LIST   *NextVariablePack;
 433   EFI_HII_VARIABLE_PACK                *VariablePack;
 434 } EFI_HII_VARIABLE_PACK_LIST;
 435
 436 #pragma pack()
 437
 438 typedef
 439 EFI_STATUS
 440 (EFIAPI *EFI_HII_NEW_PACK) (
 441   IN  EFI_HII_PROTOCOL    * This,
 442   IN  EFI_HII_PACKAGES    * Packages,
 443   OUT EFI_HII_HANDLE      * Handle
 444   );
 445
 446 typedef
 447 EFI_STATUS
 448 (EFIAPI *EFI_HII_REMOVE_PACK) (
 449   IN EFI_HII_PROTOCOL    *This,
 450   IN EFI_HII_HANDLE      Handle
 451   );
 452
 453 typedef
 454 EFI_STATUS
 455 (EFIAPI *EFI_HII_FIND_HANDLES) (
 456   IN     EFI_HII_PROTOCOL *This,
 457   IN OUT UINT16           *HandleBufferLength,
 458   OUT    EFI_HII_HANDLE   *Handle
 459   );
 460
 461 typedef
 462 EFI_STATUS
 463 (EFIAPI *EFI_HII_EXPORT) (
 464   IN     EFI_HII_PROTOCOL *This,
 465   IN     EFI_HII_HANDLE   Handle,
 466   IN OUT UINTN            *BufferSize,
 467   OUT    VOID             *Buffer
 468   );
 469
 470 typedef
 471 EFI_STATUS
 472 (EFIAPI *EFI_HII_RESET_STRINGS) (
 473   IN     EFI_HII_PROTOCOL   *This,
 474   IN     EFI_HII_HANDLE     Handle
 475   );
 476
 477 typedef
 478 EFI_STATUS
 479 (EFIAPI *EFI_HII_TEST_STRING) (
 480   IN     EFI_HII_PROTOCOL  *This,
 481   IN     CHAR16            *StringToTest,
 482   IN OUT UINT32            *FirstMissing,
 483   OUT    UINT32            *GlyphBufferSize
 484   );
 485
 486 typedef
 487 EFI_STATUS
 488 (EFIAPI *EFI_HII_GET_GLYPH) (
 489   IN     EFI_HII_PROTOCOL  *This,
 490   IN     CHAR16            *Source,
 491   IN OUT UINT16            *Index,
 492   OUT    UINT8             **GlyphBuffer,
 493   OUT    UINT16            *BitWidth,
 494   IN OUT UINT32            *InternalStatus
 495   );
 496
 497 typedef
 498 EFI_STATUS
 499 (EFIAPI *EFI_HII_GLYPH_TO_BLT) (
 500   IN     EFI_HII_PROTOCOL               *This,
 501   IN     UINT8                          *GlyphBuffer,
 502   IN     EFI_GRAPHICS_OUTPUT_BLT_PIXEL  Foreground,
 503   IN     EFI_GRAPHICS_OUTPUT_BLT_PIXEL  Background,
 504   IN     UINTN                          Count,
 505   IN     UINTN                          Width,
 506   IN     UINTN                          Height,
 507   IN OUT EFI_GRAPHICS_OUTPUT_BLT_PIXEL  *BltBuffer
 508   );
 509
 510 typedef
 511 EFI_STATUS
 512 (EFIAPI *EFI_HII_NEW_STRING) (
 513   IN     EFI_HII_PROTOCOL      *This,
 514   IN     CHAR16                *Language,
 515   IN     EFI_HII_HANDLE        Handle,
 516   IN OUT STRING_REF            *Reference,
 517   IN     CHAR16                *NewString
 518   );
 519
 520 typedef
 521 EFI_STATUS
 522 (EFIAPI *EFI_HII_GET_PRI_LANGUAGES) (
 523   IN  EFI_HII_PROTOCOL    *This,
 524   IN  EFI_HII_HANDLE      Handle,
 525   OUT EFI_STRING          *LanguageString
 526   );
 527
 528 typedef
 529 EFI_STATUS
 530 (EFIAPI *EFI_HII_GET_SEC_LANGUAGES) (
 531   IN  EFI_HII_PROTOCOL    *This,
 532   IN  EFI_HII_HANDLE      Handle,
 533   IN  CHAR16              *PrimaryLanguage,
 534   OUT EFI_STRING          *LanguageString
 535   );
 536
 537 typedef
 538 EFI_STATUS
 539 (EFIAPI *EFI_HII_GET_STRING) (
 540   IN     EFI_HII_PROTOCOL  *This,
 541   IN     EFI_HII_HANDLE    Handle,
 542   IN     STRING_REF        Token,
 543   IN     BOOLEAN           Raw,
 544   IN     CHAR16            *LanguageString,
 545   IN OUT UINTN             *BufferLength,
 546   OUT    EFI_STRING        StringBuffer
 547   );
 548
 549 typedef
 550 EFI_STATUS
 551 (EFIAPI *EFI_HII_GET_LINE) (
 552   IN     EFI_HII_PROTOCOL  *This,
 553   IN     EFI_HII_HANDLE    Handle,
 554   IN     STRING_REF        Token,
 555   IN OUT UINT16            *Index,
 556   IN     UINT16            LineWidth,
 557   IN     CHAR16            *LanguageString,
 558   IN OUT UINT16            *BufferLength,
 559   OUT    EFI_STRING        StringBuffer
 560   );
 561
 562 typedef
 563 EFI_STATUS
 564 (EFIAPI *EFI_HII_GET_FORMS) (
 565   IN     EFI_HII_PROTOCOL  *This,
 566   IN     EFI_HII_HANDLE    Handle,
 567   IN     EFI_FORM_ID       FormId,
 568   IN OUT UINTN             *BufferLength,
 569   OUT    UINT8             *Buffer
 570   );
 571
 572 typedef
 573 EFI_STATUS
 574 (EFIAPI *EFI_HII_GET_DEFAULT_IMAGE) (
 575   IN     EFI_HII_PROTOCOL           *This,
 576   IN     EFI_HII_HANDLE             Handle,
 577   IN     UINTN                      DefaultMask,
 578   OUT    EFI_HII_VARIABLE_PACK_LIST **VariablePackList
 579   );
 580
 581 typedef
 582 EFI_STATUS
 583 (EFIAPI *EFI_HII_UPDATE_FORM) (
 584   IN EFI_HII_PROTOCOL     *This,
 585   IN EFI_HII_HANDLE       Handle,
 586   IN EFI_FORM_LABEL       Label,
 587   IN BOOLEAN              AddData,
 588   IN EFI_HII_UPDATE_DATA  *Data
 589   );
 590
 591 typedef
 592 EFI_STATUS
 593 (EFIAPI *EFI_HII_GET_KEYBOARD_LAYOUT) (
 594   IN     EFI_HII_PROTOCOL    * This,
 595   OUT    UINT16              *DescriptorCount,
 596   OUT    EFI_KEY_DESCRIPTOR  * Descriptor
 597   );
 598
 599 struct _EFI_HII_PROTOCOL {
 600   EFI_HII_NEW_PACK            NewPack;
 601   EFI_HII_REMOVE_PACK         RemovePack;
 602   EFI_HII_FIND_HANDLES        FindHandles;
 603   EFI_HII_EXPORT              ExportDatabase;
 604
 605   EFI_HII_TEST_STRING         TestString;
 606   EFI_HII_GET_GLYPH           GetGlyph;
 607   EFI_HII_GLYPH_TO_BLT        GlyphToBlt;
 608
 609   EFI_HII_NEW_STRING          NewString;
 610   EFI_HII_GET_PRI_LANGUAGES   GetPrimaryLanguages;
 611   EFI_HII_GET_SEC_LANGUAGES   GetSecondaryLanguages;
 612   EFI_HII_GET_STRING          GetString;
 613   EFI_HII_RESET_STRINGS       ResetStrings;
 614   EFI_HII_GET_LINE            GetLine;
 615   EFI_HII_GET_FORMS           GetForms;
 616   EFI_HII_GET_DEFAULT_IMAGE   GetDefaultImage;
 617   EFI_HII_UPDATE_FORM         UpdateForm;
 618
 619   EFI_HII_GET_KEYBOARD_LAYOUT GetKeyboardLayout;
 620 };
 621
 622 extern EFI_GUID gEfiHiiProtocolGuid;
 623
 624 #endif