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