MdePkg/Include/Protocol/RedfishDiscover.h

   1 /** @file
   2   This file defines the EFI Redfish Discover Protocol interface.
   3
   4   (C) Copyright 2021 Hewlett Packard Enterprise Development LP<BR>
   5
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8   @par Revision Reference:
   9   - Some corrections and revises are added to UEFI Specification 2.9.
  10   - This Protocol is introduced in UEFI Specification 2.8.
  11
  12 **/
  13
  14 #ifndef EFI_REDFISH_DISCOVER_PROTOCOL_H_
  15 #define EFI_REDFISH_DISCOVER_PROTOCOL_H_
  16
  17 //
  18 // GUID definitions
  19 //
  20 #define EFI_REDFISH_DISCOVER_PROTOCOL_GUID \
  21   { \
  22     0x5db12509, 0x4550, 0x4347, { 0x96, 0xb3, 0x73, 0xc0, 0xff, 0x6e, 0x86, 0x9f } \
  23   }
  24
  25 #define REDFISH_DISCOVER_TOKEN_SIGNATURE  SIGNATURE_32 ('R', 'F', 'T', 'S')
  26
  27 typedef UINT32 EFI_REDFISH_DISCOVER_FLAG;
  28 #define EFI_REDFISH_DISCOVER_HOST_INTERFACE  0x00000001 ///< Discover Redfish server reported in SMBIOS 42h.
  29 #define EFI_REDFISH_DISCOVER_SSDP            0x00000002 ///< Discover Redfish server using UPnP Http search method.
  30 #define EFI_REDFISH_DISCOVER_SSDP_UDP6       0x00000004 ///< Use UDP version 6.
  31 #define EFI_REDFISH_DISCOVER_KEEP_ALIVE      0x00000008 ///< Keep to send UPnP Search in the duration indicated in
  32                                                         ///< EFI_REDFISH_DISCOVER_DURATION_MASK.
  33 #define EFI_REDFISH_DISCOVER_RENEW  0x00000010         ///< Set this bit to indicate this function to notify the caller
  34                                                        ///< a list of all Redfish servers it found. Otherwise, this fucntion
  35                                                        ///< just notify the caller new found Redfish servers.
  36                                                        ///<
  37 #define EFI_REDFISH_DISCOVER_VALIDATION     0x80000000 ///< Validate Redfish service for host interface instance.
  38 #define EFI_REDFISH_DISCOVER_DURATION_MASK  0x0f000000 ///< 2 to the Power of Duration. The valid value of duration is between
  39                                                        ///< 3 to 15. The corresponding duration is 8 to 2^15 seconds.
  40                                                        ///< Duration is only valid when EFI_REDFISH_DISCOVER_KEEP_ALIVE
  41                                                        ///< is set to 1.
  42 typedef struct _EFI_REDFISH_DISCOVER_PROTOCOL EFI_REDFISH_DISCOVER_PROTOCOL;
  43
  44 typedef struct {
  45   EFI_HANDLE        RedfishRestExHandle;    ///< REST EX EFI handle associated with this Redfish service.
  46   BOOLEAN           IsUdp6;                 ///< Indicates it's IP versino 6.
  47   EFI_IP_ADDRESS    RedfishHostIpAddress;   ///< IP address of Redfish service.
  48   UINTN             RedfishVersion;         ///< Redfish service version.
  49   CHAR16            *Location;              ///< Redfish service location.
  50   CHAR16            *Uuid;                  ///< Redfish service UUID.
  51   CHAR16            *Os;                    ///< Redfish service OS.
  52   CHAR16            *OsVersion;             ///< Redfish service OS version.
  53   CHAR16            *Product;               ///< Redfish service product name.
  54   CHAR16            *ProductVer;            ///< Redfish service product version.
  55   BOOLEAN           UseHttps;               ///< Using HTTPS.
  56 } EFI_REDFISH_DISCOVERED_INFORMATION;
  57
  58 typedef struct {
  59   EFI_STATUS                            Status;      ///< Status of Redfish service discovery.
  60   EFI_REDFISH_DISCOVERED_INFORMATION    Information; ///< Redfish service discovered.
  61 } EFI_REDFISH_DISCOVERED_INSTANCE;
  62
  63 typedef struct {
  64   UINTN                              NumberOfServiceFound; ///< Must be 0 when pass to Acquire ().
  65   EFI_REDFISH_DISCOVERED_INSTANCE    *RedfishInstances;    ///< Must be NULL when pass to Acquire ().
  66 } EFI_REDFISH_DISCOVERED_LIST;
  67
  68 typedef struct {
  69   EFI_MAC_ADDRESS    MacAddress;                  ///< MAC address of network interfase to discover Redfish service.
  70   BOOLEAN            IsIpv6;                      ///< Indicates it's IP versino 6.
  71   EFI_IP_ADDRESS     SubnetId;                    ///< Subnet ID.
  72   UINT8              SubnetPrefixLength;          ///< Subnet prefix-length for IPv4 and IPv6.
  73   UINT16             VlanId;                      ///< VLAN ID.
  74 } EFI_REDFISH_DISCOVER_NETWORK_INTERFACE;
  75
  76 typedef struct {
  77   UINT32                         Signature;    ///< Token signature.
  78   EFI_REDFISH_DISCOVERED_LIST    DiscoverList; ///< The memory of EFI_REDFISH_DISCOVERED_LIST is
  79                                                ///< allocated by Acquire() and freed when caller invoke Release().
  80   EFI_EVENT                      Event;        ///< The TPL_CALLBACK event to be notified when Redfish services
  81                                                ///< are discovered or any errors occurred during discovery.
  82   UINTN                          Timeout;      ///< The timeout value declared in EFI_REDFISH_DISCOVERED_TOKEN
  83                                                ///< determines the seconds to drop discover process.
  84                                                ///< Basically, the nearby Redfish services must response in >=1
  85                                                ///< and <= 5 seconds. The valid timeout value used to have
  86                                                ///< asynchronous discovery is >= 1 and <= 5 seconds. Set the
  87                                                ///< timeout to zero means to discover Redfish service synchronously.
  88                                                ///< Event in token is created by caller to listen the Reefish services
  89                                                ///< found by Acquire().
  90 } EFI_REDFISH_DISCOVERED_TOKEN;
  91
  92 /**
  93   This function gets the NIC list which Redfish discover protocol
  94   can discover Redfish service on it.
  95
  96   @param[in]    This         EFI_REDFISH_DISCOVER_PROTOCOL instance.
  97   @param[in]    ImageHandle  EFI Image handle request the NIC list,
  98   @param[out]   NumberOfNetworkInterfaces Number of NICs can do Redfish service discovery.
  99   @param[out]   NetworkInterfaces NIC instances. It's an array of instance. The number of entries
 100                              in array is indicated by NumberOfNetworkInterfaces.
 101                              Caller has to release the memory
 102                              allocated by Redfish discover protocol.
 103
 104   @retval EFI_SUCCESS        REST EX instances of discovered Redfish are released.
 105   @retval Others             Fail to remove the entry
 106
 107 **/
 108 typedef
 109 EFI_STATUS
 110 (EFIAPI *EFI_REDFISH_DISCOVER_NETWORK_LIST)(
 111   IN EFI_REDFISH_DISCOVER_PROTOCOL           *This,
 112   IN EFI_HANDLE                              ImageHandle,
 113   OUT UINTN                                  *NumberOfNetworkInterfaces,
 114   OUT EFI_REDFISH_DISCOVER_NETWORK_INTERFACE **NetworkInterfaces
 115   );
 116
 117 /**
 118   This function acquires Redfish services by discovering static Redfish setting
 119   according to Redfish Host Interface or through SSDP. Returns a list of EFI
 120   handles in EFI_REDFISH_DISCOVERED_LIST. Each of EFI handle has cooresponding
 121   EFI REST EX instance installed on it. Each REST EX isntance is a child instance which
 122   created through EFI REST EX serivce protoocl for communicating with specific
 123   Redfish service.
 124
 125   @param[in]    This          EFI_REDFISH_DISCOVER_PROTOCOL instance.
 126   @param[in]    ImageHandle   EFI image owns these Redfish service instances.
 127   @param[in]    TargetNetworkInterface Target NIC to do the discovery.
 128                               NULL means discover Redfish service on all NICs on platform.
 129   @param[in]    Flags         Redfish service discover flags.
 130   @param[in]    Token         EFI_REDFISH_DISCOVERED_TOKEN instance.
 131                               The memory of EFI_REDFISH_DISCOVERED_LIST and the strings in
 132                               EFI_REDFISH_DISCOVERED_INFORMATION are all allocated by Acquire()
 133                               and must be freed when caller invoke Release().
 134
 135   @retval EFI_SUCCESS             REST EX instance of discovered Redfish services are returned.
 136   @retval EFI_INVALID_PARAMETERS  ImageHandle == NULL, Flags == 0, Token == NULL, Token->Timeout > 5,
 137                                   or Token->Event == NULL.
 138   @retval Others                  Fail acquire Redfish services.
 139
 140 **/
 141 typedef
 142 EFI_STATUS
 143 (EFIAPI *EFI_REDFISH_DISCOVER_ACQUIRE_SERVICE)(
 144   IN EFI_REDFISH_DISCOVER_PROTOCOL          *This,
 145   IN EFI_HANDLE                             ImageHandle,
 146   IN EFI_REDFISH_DISCOVER_NETWORK_INTERFACE *TargetNetworkInterface OPTIONAL,
 147   IN EFI_REDFISH_DISCOVER_FLAG              Flags,
 148   IN EFI_REDFISH_DISCOVERED_TOKEN           *Token
 149   );
 150
 151 /**
 152   This function aborts Redfish service discovery on the given network interface.
 153
 154   @param[in]    This                    EFI_REDFISH_DISCOVER_PROTOCOL instance.
 155   @param[in]    TargetNetworkInterface  Target NIC to do the discovery.
 156
 157   @retval EFI_SUCCESS             REST EX instance of discovered Redfish services are returned.
 158   @retval Others                  Fail to abort Redfish service discovery.
 159
 160 **/
 161 typedef
 162 EFI_STATUS
 163 (EFIAPI *EFI_REDFISH_DISCOVER_ABORT_ACQUIRE)(
 164   IN EFI_REDFISH_DISCOVER_PROTOCOL          *This,
 165   IN EFI_REDFISH_DISCOVER_NETWORK_INTERFACE *TargetNetworkInterface OPTIONAL
 166   );
 167
 168 /**
 169   This function releases Redfish services found by RedfishServiceAcquire().
 170
 171   @param[in]    This         EFI_REDFISH_DISCOVER_PROTOCOL instance.
 172   @param[in]    List         The Redfish service to release.
 173
 174   @retval EFI_SUCCESS        REST EX instances of discovered Redfish are released.
 175   @retval Others             Fail to remove the entry
 176
 177 **/
 178 typedef
 179 EFI_STATUS
 180 (EFIAPI *EFI_REDFISH_DISCOVER_RELEASE_SERVICE)(
 181   IN EFI_REDFISH_DISCOVER_PROTOCOL   *This,
 182   IN EFI_REDFISH_DISCOVERED_LIST     *List
 183   );
 184
 185 struct _EFI_REDFISH_DISCOVER_PROTOCOL {
 186   EFI_REDFISH_DISCOVER_NETWORK_LIST       GetNetworkInterfaceList;
 187   EFI_REDFISH_DISCOVER_ACQUIRE_SERVICE    AcquireRedfishService;
 188   EFI_REDFISH_DISCOVER_ABORT_ACQUIRE      AbortAcquireRedfishService;
 189   EFI_REDFISH_DISCOVER_RELEASE_SERVICE    ReleaseRedfishService;
 190 };
 191
 192 extern EFI_GUID  gEfiRedfishDiscoverProtocolGuid;
 193 #endif