[mirror_edk2.git] / RedfishPkg / Include / Protocol / RedfishDiscover.h

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