qemu/roms/ipxe/src/include/ipxe/efi/Protocol/HiiDatabase.h

   1 /** @file
   2   The file provides Database manager for HII-related data
   3   structures.
   4
   5 Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>
   6 This program and the accompanying materials are licensed and made available under
   7 the terms and conditions of the BSD License that accompanies this distribution.
   8 The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php.
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef __HII_DATABASE_H__
  17 #define __HII_DATABASE_H__
  18
  19 FILE_LICENCE ( BSD3 );
  20
  21 #define EFI_HII_DATABASE_PROTOCOL_GUID \
  22   { 0xef9fc172, 0xa1b2, 0x4693, { 0xb3, 0x27, 0x6d, 0x32, 0xfc, 0x41, 0x60, 0x42 } }
  23
  24
  25 typedef struct _EFI_HII_DATABASE_PROTOCOL EFI_HII_DATABASE_PROTOCOL;
  26
  27
  28 ///
  29 /// EFI_HII_DATABASE_NOTIFY_TYPE.
  30 ///
  31 typedef UINTN   EFI_HII_DATABASE_NOTIFY_TYPE;
  32
  33 #define EFI_HII_DATABASE_NOTIFY_NEW_PACK    0x00000001
  34 #define EFI_HII_DATABASE_NOTIFY_REMOVE_PACK 0x00000002
  35 #define EFI_HII_DATABASE_NOTIFY_EXPORT_PACK 0x00000004
  36 #define EFI_HII_DATABASE_NOTIFY_ADD_PACK    0x00000008
  37 /**
  38
  39   Functions which are registered to receive notification of
  40   database events have this prototype. The actual event is encoded
  41   in NotifyType. The following table describes how PackageType,
  42   PackageGuid, Handle, and Package are used for each of the
  43   notification types.
  44
  45   @param PackageType  Package type of the notification.
  46
  47   @param PackageGuid  If PackageType is
  48                       EFI_HII_PACKAGE_TYPE_GUID, then this is
  49                       the pointer to the GUID from the Guid
  50                       field of EFI_HII_PACKAGE_GUID_HEADER.
  51                       Otherwise, it must be NULL.
  52
  53   @param Package      Points to the package referred to by the notification.
  54
  55   @param Handle       The handle of the package
  56                       list which contains the specified package.
  57
  58   @param NotifyType   The type of change concerning the
  59                       database. See
  60                       EFI_HII_DATABASE_NOTIFY_TYPE.
  61
  62 **/
  63 typedef
  64 EFI_STATUS
  65 (EFIAPI *EFI_HII_DATABASE_NOTIFY)(
  66   IN        UINT8                         PackageType,
  67   IN CONST  EFI_GUID                      *PackageGuid,
  68   IN CONST  EFI_HII_PACKAGE_HEADER        *Package,
  69   IN        EFI_HII_HANDLE                 Handle,
  70   IN        EFI_HII_DATABASE_NOTIFY_TYPE  NotifyType
  71 );
  72
  73 /**
  74
  75   This function adds the packages in the package list to the
  76   database and returns a handle. If there is a
  77   EFI_DEVICE_PATH_PROTOCOL associated with the DriverHandle, then
  78   this function will create a package of type
  79   EFI_PACKAGE_TYPE_DEVICE_PATH and add it to the package list. For
  80   each package in the package list, registered functions with the
  81   notification type NEW_PACK and having the same package type will
  82   be called. For each call to NewPackageList(), there should be a
  83   corresponding call to
  84   EFI_HII_DATABASE_PROTOCOL.RemovePackageList().
  85
  86   @param This           A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
  87
  88   @param PackageList    A pointer to an EFI_HII_PACKAGE_LIST_HEADER structure.
  89
  90   @param DriverHandle   Associate the package list with this EFI handle.
  91                         If a NULL is specified, this data will not be associate
  92                         with any drivers and cannot have a callback induced.
  93
  94   @param Handle         A pointer to the EFI_HII_HANDLE instance.
  95
  96   @retval EFI_SUCCESS           The package list associated with the
  97                                 Handle was added to the HII database.
  98
  99   @retval EFI_OUT_OF_RESOURCES  Unable to allocate necessary
 100                                 resources for the new database
 101                                 contents.
 102
 103   @retval EFI_INVALID_PARAMETER PackageList is NULL, or Handle is NULL.
 104
 105 **/
 106 typedef
 107 EFI_STATUS
 108 (EFIAPI *EFI_HII_DATABASE_NEW_PACK)(
 109   IN CONST  EFI_HII_DATABASE_PROTOCOL   *This,
 110   IN CONST  EFI_HII_PACKAGE_LIST_HEADER *PackageList,
 111   IN        EFI_HANDLE                  DriverHandle, OPTIONAL
 112   OUT       EFI_HII_HANDLE               *Handle
 113 );
 114
 115
 116 /**
 117
 118   This function removes the package list that is associated with a
 119   handle Handle from the HII database. Before removing the
 120   package, any registered functions with the notification type
 121   REMOVE_PACK and the same package type will be called. For each
 122   call to EFI_HII_DATABASE_PROTOCOL.NewPackageList(), there should
 123   be a corresponding call to RemovePackageList.
 124
 125   @param This             A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 126
 127   @param Handle           The handle that was registered to the data
 128                           that is requested for removal.
 129
 130   @retval EFI_SUCCESS     The data associated with the Handle was
 131                           removed from the HII database.
 132   @retval EFI_NOT_FOUND   The specified Handle is not in database.
 133
 134 **/
 135 typedef
 136 EFI_STATUS
 137 (EFIAPI *EFI_HII_DATABASE_REMOVE_PACK)(
 138   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 139   IN        EFI_HII_HANDLE             Handle
 140 );
 141
 142
 143 /**
 144
 145   This function updates the existing package list (which has the
 146   specified Handle) in the HII databases, using the new package
 147   list specified by PackageList. The update process has the
 148   following steps: Collect all the package types in the package
 149   list specified by PackageList. A package type consists of the
 150   Type field of EFI_HII_PACKAGE_HEADER and, if the Type is
 151   EFI_HII_PACKAGE_TYPE_GUID, the Guid field, as defined in
 152   EFI_HII_PACKAGE_GUID_HEADER. Iterate through the packages within
 153   the existing package list in the HII database specified by
 154   Handle. If a package's type matches one of the collected types collected
 155   in step 1, then perform the following steps:
 156   - Call any functions registered with the notification type
 157   REMOVE_PACK.
 158   - Remove the package from the package list and the HII
 159   database.
 160   Add all of the packages within the new package list specified
 161   by PackageList, using the following steps:
 162   - Add the package to the package list and the HII database.
 163   - Call any functions registered with the notification type
 164   ADD_PACK.
 165
 166   @param This         A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 167
 168   @param Handle       The handle that was registered to the data
 169                       that is requested for removal.
 170
 171   @param PackageList  A pointer to an EFI_HII_PACKAGE_LIST
 172                       package.
 173
 174   @retval EFI_SUCCESS            The HII database was successfully updated.
 175
 176   @retval EFI_OUT_OF_RESOURCES   Unable to allocate enough memory
 177                                  for the updated database.
 178
 179   @retval EFI_INVALID_PARAMETER  PackageList was NULL.
 180   @retval EFI_NOT_FOUND          The specified Handle is not in database.
 181
 182 **/
 183 typedef
 184 EFI_STATUS
 185 (EFIAPI *EFI_HII_DATABASE_UPDATE_PACK)(
 186   IN CONST  EFI_HII_DATABASE_PROTOCOL   *This,
 187   IN        EFI_HII_HANDLE               Handle,
 188   IN CONST  EFI_HII_PACKAGE_LIST_HEADER *PackageList
 189 );
 190
 191
 192 /**
 193
 194   This function returns a list of the package handles of the
 195   specified type that are currently active in the database. The
 196   pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package
 197   handles to be listed.
 198
 199   @param This                 A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 200
 201   @param PackageType          Specifies the package type of the packages
 202                               to list or EFI_HII_PACKAGE_TYPE_ALL for
 203                               all packages to be listed.
 204
 205   @param PackageGuid          If PackageType is
 206                               EFI_HII_PACKAGE_TYPE_GUID, then this is
 207                               the pointer to the GUID which must match
 208                               the Guid field of
 209                               EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it
 210                               must be NULL.
 211
 212   @param HandleBufferLength   On input, a pointer to the length
 213                               of the handle buffer. On output,
 214                               the length of the handle buffer
 215                               that is required for the handles found.
 216
 217   @param Handle               An array of EFI_HII_HANDLE instances returned.
 218
 219   @retval EFI_SUCCESS           The matching handles are outputed successfully.
 220                                 HandleBufferLength is updated with the actual length.
 221   @retval EFI_BUFFER_TOO_SMALL  The HandleBufferLength parameter
 222                                 indicates that Handle is too
 223                                 small to support the number of
 224                                 handles. HandleBufferLength is
 225                                 updated with a value that will
 226                                 enable the data to fit.
 227   @retval EFI_NOT_FOUND         No matching handle could be found in database.
 228   @retval EFI_INVALID_PARAMETER HandleBufferLength was NULL.
 229   @retval EFI_INVALID_PARAMETER The value referenced by HandleBufferLength was not
 230                                 zero and Handle was NULL.
 231   @retval EFI_INVALID_PARAMETER PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but
 232                                 PackageGuid is not NULL, PackageType is a EFI_HII_
 233                                 PACKAGE_TYPE_GUID but PackageGuid is NULL.
 234 **/
 235 typedef
 236 EFI_STATUS
 237 (EFIAPI *EFI_HII_DATABASE_LIST_PACKS)(
 238   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 239   IN        UINT8                     PackageType,
 240   IN CONST  EFI_GUID                  *PackageGuid,
 241   IN OUT    UINTN                     *HandleBufferLength,
 242   OUT       EFI_HII_HANDLE            *Handle
 243 );
 244
 245 /**
 246
 247   This function will export one or all package lists in the
 248   database to a buffer. For each package list exported, this
 249   function will call functions registered with EXPORT_PACK and
 250   then copy the package list to the buffer. The registered
 251   functions may call EFI_HII_DATABASE_PROTOCOL.UpdatePackageList()
 252   to modify the package list before it is copied to the buffer. If
 253   the specified BufferSize is too small, then the status
 254   EFI_OUT_OF_RESOURCES will be returned and the actual package
 255   size will be returned in BufferSize.
 256
 257   @param This         A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 258
 259
 260   @param Handle       An EFI_HII_HANDLE  that corresponds to the
 261                       desired package list in the HII database to
 262                       export or NULL to indicate all package lists
 263                       should be exported.
 264
 265   @param BufferSize   On input, a pointer to the length of the
 266                       buffer. On output, the length of the
 267                       buffer that is required for the exported
 268                       data.
 269
 270   @param Buffer       A pointer to a buffer that will contain the
 271                       results of the export function.
 272
 273
 274   @retval EFI_SUCCESS           Package exported.
 275
 276   @retval EFI_OUT_OF_RESOURCES  BufferSize is too small to hold the package.
 277
 278   @retval EFI_NOT_FOUND         The specifiecd Handle could not be found in the
 279                                 current database.
 280
 281   @retval EFI_INVALID_PARAMETER BufferSize was NULL.
 282
 283   @retval EFI_INVALID_PARAMETER The value referenced by BufferSize was not zero
 284                                 and Buffer was NULL.
 285 **/
 286 typedef
 287 EFI_STATUS
 288 (EFIAPI *EFI_HII_DATABASE_EXPORT_PACKS)(
 289   IN CONST  EFI_HII_DATABASE_PROTOCOL      *This,
 290   IN        EFI_HII_HANDLE                 Handle,
 291   IN OUT    UINTN                          *BufferSize,
 292   OUT       EFI_HII_PACKAGE_LIST_HEADER    *Buffer
 293 );
 294
 295
 296 /**
 297
 298
 299   This function registers a function which will be called when
 300   specified actions related to packages of the specified type
 301   occur in the HII database. By registering a function, other
 302   HII-related drivers are notified when specific package types
 303   are added, removed or updated in the HII database. Each driver
 304   or application which registers a notification should use
 305   EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify() before
 306   exiting.
 307
 308
 309   @param This             A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 310
 311   @param PackageType      The package type. See
 312                           EFI_HII_PACKAGE_TYPE_x in EFI_HII_PACKAGE_HEADER.
 313
 314   @param PackageGuid      If PackageType is
 315                           EFI_HII_PACKAGE_TYPE_GUID, then this is
 316                           the pointer to the GUID which must match
 317                           the Guid field of
 318                           EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it
 319                           must be NULL.
 320
 321   @param PackageNotifyFn  Points to the function to be called
 322                           when the event specified by
 323                           NotificationType occurs. See
 324                           EFI_HII_DATABASE_NOTIFY.
 325
 326   @param NotifyType       Describes the types of notification which
 327                           this function will be receiving. See
 328                           EFI_HII_DATABASE_NOTIFY_TYPE for a
 329                           list of types.
 330
 331   @param NotifyHandle     Points to the unique handle assigned to
 332                           the registered notification. Can be used
 333                           in EFI_HII_DATABASE_PROTOCOL.UnregisterPack
 334                           to stop notifications.
 335
 336
 337   @retval EFI_SUCCESS           Notification registered successfully.
 338
 339   @retval EFI_OUT_OF_RESOURCES  Unable to allocate necessary
 340                                 data structures.
 341
 342   @retval EFI_INVALID_PARAMETER PackageGuid is not NULL when
 343                                 PackageType is not
 344                                 EFI_HII_PACKAGE_TYPE_GUID.
 345
 346 **/
 347 typedef
 348 EFI_STATUS
 349 (EFIAPI *EFI_HII_DATABASE_REGISTER_NOTIFY)(
 350   IN CONST  EFI_HII_DATABASE_PROTOCOL     *This,
 351   IN        UINT8                         PackageType,
 352   IN CONST  EFI_GUID                      *PackageGuid,
 353   IN        EFI_HII_DATABASE_NOTIFY       PackageNotifyFn,
 354   IN        EFI_HII_DATABASE_NOTIFY_TYPE  NotifyType,
 355   OUT       EFI_HANDLE                    *NotifyHandle
 356 );
 357
 358
 359 /**
 360
 361   Removes the specified HII database package-related notification.
 362
 363   @param This                 A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 364
 365   @param NotificationHandle   The handle of the notification
 366                               function being unregistered.
 367
 368   @retval EFI_SUCCESS   Successsfully unregistered the notification.
 369
 370   @retval EFI_NOT_FOUND The incoming notification handle does not exist
 371                         in the current hii database.
 372
 373 **/
 374 typedef
 375 EFI_STATUS
 376 (EFIAPI *EFI_HII_DATABASE_UNREGISTER_NOTIFY)(
 377   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 378   IN        EFI_HANDLE                NotificationHandle
 379 );
 380
 381
 382 /**
 383
 384   This routine retrieves an array of GUID values for each keyboard
 385   layout that was previously registered in the system.
 386
 387   @param This                 A pointer to the EFI_HII_PROTOCOL instance.
 388
 389   @param KeyGuidBufferLength  On input, a pointer to the length
 390                               of the keyboard GUID buffer. On
 391                               output, the length of the handle
 392                               buffer that is required for the
 393                               handles found.
 394
 395   @param KeyGuidBuffer        An array of keyboard layout GUID
 396                               instances returned.
 397
 398   @retval EFI_SUCCESS           KeyGuidBuffer was updated successfully.
 399
 400   @retval EFI_BUFFER_TOO_SMALL  The KeyGuidBufferLength
 401                                 parameter indicates that
 402                                 KeyGuidBuffer is too small to
 403                                 support the number of GUIDs.
 404                                 KeyGuidBufferLength is updated
 405                                 with a value that will enable
 406                                 the data to fit.
 407   @retval EFI_INVALID_PARAMETER The KeyGuidBufferLength is NULL.
 408   @retval EFI_INVALID_PARAMETER The value referenced by
 409                                 KeyGuidBufferLength is not
 410                                 zero and KeyGuidBuffer is NULL.
 411   @retval EFI_NOT_FOUND         There was no keyboard layout.
 412
 413 **/
 414 typedef
 415 EFI_STATUS
 416 (EFIAPI *EFI_HII_FIND_KEYBOARD_LAYOUTS)(
 417   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 418   IN OUT    UINT16                    *KeyGuidBufferLength,
 419   OUT       EFI_GUID                  *KeyGuidBuffer
 420 );
 421
 422
 423 /**
 424
 425   This routine retrieves the requested keyboard layout. The layout
 426   is a physical description of the keys on a keyboard, and the
 427   character(s) that are associated with a particular set of key
 428   strokes.
 429
 430   @param This                   A pointer to the EFI_HII_PROTOCOL instance.
 431
 432   @param KeyGuid                A pointer to the unique ID associated with a
 433                                 given keyboard layout. If KeyGuid is NULL then
 434                                 the current layout will be retrieved.
 435
 436   @param KeyboardLayoutLength   On input, a pointer to the length of the
 437                                 KeyboardLayout buffer.  On output, the length of
 438                                 the data placed into KeyboardLayout.
 439
 440   @param KeyboardLayout         A pointer to a buffer containing the
 441                                 retrieved keyboard layout.
 442
 443   @retval EFI_SUCCESS   The keyboard layout was retrieved
 444                         successfully.
 445
 446   @retval EFI_NOT_FOUND The requested keyboard layout was not found.
 447
 448 **/
 449 typedef
 450 EFI_STATUS
 451 (EFIAPI *EFI_HII_GET_KEYBOARD_LAYOUT)(
 452   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 453   IN CONST  EFI_GUID                  *KeyGuid,
 454   IN OUT UINT16                       *KeyboardLayoutLength,
 455   OUT       EFI_HII_KEYBOARD_LAYOUT   *KeyboardLayout
 456 );
 457
 458 /**
 459
 460   This routine sets the default keyboard layout to the one
 461   referenced by KeyGuid. When this routine is called, an event
 462   will be signaled of the EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID
 463   group type. This is so that agents which are sensitive to the
 464   current keyboard layout being changed can be notified of this
 465   change.
 466
 467   @param This      A pointer to the EFI_HII_PROTOCOL instance.
 468
 469   @param KeyGuid   A pointer to the unique ID associated with a
 470                    given keyboard layout.
 471
 472   @retval EFI_SUCCESS    The current keyboard layout was successfully set.
 473
 474   @retval EFI_NOT_FOUND  The referenced keyboard layout was not
 475                          found, so action was taken.
 476
 477 **/
 478 typedef
 479 EFI_STATUS
 480 (EFIAPI *EFI_HII_SET_KEYBOARD_LAYOUT)(
 481   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 482   IN CONST  EFI_GUID                  *KeyGuid
 483 );
 484
 485 /**
 486
 487   Return the EFI handle associated with a package list.
 488
 489   @param This               A pointer to the EFI_HII_PROTOCOL instance.
 490
 491   @param PackageListHandle  An EFI_HII_HANDLE  that corresponds
 492                             to the desired package list in the
 493                             HIIdatabase.
 494
 495   @param DriverHandle       On return, contains the EFI_HANDLE which
 496                             was registered with the package list in
 497                             NewPackageList().
 498
 499   @retval EFI_SUCCESS            The DriverHandle was returned successfully.
 500
 501   @retval EFI_INVALID_PARAMETER  The PackageListHandle was not valid.
 502
 503 **/
 504 typedef
 505 EFI_STATUS
 506 (EFIAPI *EFI_HII_DATABASE_GET_PACK_HANDLE)(
 507   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 508   IN        EFI_HII_HANDLE             PackageListHandle,
 509   OUT       EFI_HANDLE                *DriverHandle
 510 );
 511
 512 ///
 513 /// Database manager for HII-related data structures.
 514 ///
 515 struct _EFI_HII_DATABASE_PROTOCOL {
 516   EFI_HII_DATABASE_NEW_PACK           NewPackageList;
 517   EFI_HII_DATABASE_REMOVE_PACK        RemovePackageList;
 518   EFI_HII_DATABASE_UPDATE_PACK        UpdatePackageList;
 519   EFI_HII_DATABASE_LIST_PACKS         ListPackageLists;
 520   EFI_HII_DATABASE_EXPORT_PACKS       ExportPackageLists;
 521   EFI_HII_DATABASE_REGISTER_NOTIFY    RegisterPackageNotify;
 522   EFI_HII_DATABASE_UNREGISTER_NOTIFY  UnregisterPackageNotify;
 523   EFI_HII_FIND_KEYBOARD_LAYOUTS       FindKeyboardLayouts;
 524   EFI_HII_GET_KEYBOARD_LAYOUT         GetKeyboardLayout;
 525   EFI_HII_SET_KEYBOARD_LAYOUT         SetKeyboardLayout;
 526   EFI_HII_DATABASE_GET_PACK_HANDLE    GetPackageListHandle;
 527 };
 528
 529 extern EFI_GUID gEfiHiiDatabaseProtocolGuid;
 530
 531 #endif
 532
 533