1 /** @file 2 Header file for Console Platfrom DXE Driver. 3 4 Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> 5 This program and the accompanying materials 6 are licensed and made available under the terms and conditions of the BSD License 7 which accompanies this distribution. The full text of the license may be found at 8 http://opensource.org/licenses/bsd-license.php 9 10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 12 13 **/ 14 15 #ifndef _CON_PLATFORM_H_ 16 #define _CON_PLATFORM_H_ 17 18 #include <Uefi.h> 19 20 #include <Protocol/SimpleTextOut.h> 21 #include <Protocol/DevicePath.h> 22 #include <Protocol/SimpleTextIn.h> 23 #include <Protocol/PciIo.h> 24 #include <Protocol/GraphicsOutput.h> 25 26 #include <Guid/GlobalVariable.h> 27 #include <Guid/ConsoleInDevice.h> 28 #include <Guid/StandardErrorDevice.h> 29 #include <Guid/ConsoleOutDevice.h> 30 31 #include <Library/DebugLib.h> 32 #include <Library/UefiDriverEntryPoint.h> 33 #include <Library/UefiLib.h> 34 #include <Library/BaseMemoryLib.h> 35 #include <Library/UefiBootServicesTableLib.h> 36 #include <Library/UefiRuntimeServicesTableLib.h> 37 #include <Library/DevicePathLib.h> 38 #include <Library/MemoryAllocationLib.h> 39 40 // 41 // Driver Binding Externs 42 // 43 extern EFI_DRIVER_BINDING_PROTOCOL gConPlatformTextInDriverBinding; 44 extern EFI_COMPONENT_NAME_PROTOCOL gConPlatformComponentName; 45 extern EFI_COMPONENT_NAME2_PROTOCOL gConPlatformComponentName2; 46 extern EFI_DRIVER_BINDING_PROTOCOL gConPlatformTextOutDriverBinding; 47 extern EFI_COMPONENT_NAME_PROTOCOL gConPlatformComponentName; 48 extern EFI_COMPONENT_NAME2_PROTOCOL gConPlatformComponentName2; 49 50 51 typedef enum { 52 Check, 53 Append, 54 Delete 55 } CONPLATFORM_VAR_OPERATION; 56 57 /** 58 Test to see if specific protocol could be supported on the ControllerHandle. 59 60 @param This Protocol instance pointer. 61 @param ControllerHandle Handle of device to test. 62 @param ProtocolGuid The specfic protocol. 63 64 @retval EFI_SUCCESS This driver supports this device 65 @retval other This driver does not support this device 66 67 **/ 68 EFI_STATUS 69 ConPlatformDriverBindingSupported ( 70 IN EFI_DRIVER_BINDING_PROTOCOL *This, 71 IN EFI_HANDLE ControllerHandle, 72 IN EFI_GUID *ProtocolGuid 73 ); 74 75 /** 76 Test to see if EFI_SIMPLE_TEXT_INPUT_PROTOCOL is supported on ControllerHandle. 77 78 @param This Protocol instance pointer. 79 @param ControllerHandle Handle of device to test. 80 @param RemainingDevicePath Optional parameter use to pick a specific child 81 device to start. 82 83 @retval EFI_SUCCESS This driver supports this device. 84 @retval other This driver does not support this device. 85 86 **/ 87 EFI_STATUS 88 EFIAPI 89 ConPlatformTextInDriverBindingSupported ( 90 IN EFI_DRIVER_BINDING_PROTOCOL *This, 91 IN EFI_HANDLE Handle, 92 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL 93 ); 94 95 /** 96 Test to see if EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL is supported on ControllerHandle. 97 98 @param This Protocol instance pointer. 99 @param ControllerHandle Handle of device to test. 100 @param RemainingDevicePath Optional parameter use to pick a specific child 101 device to start. 102 103 @retval EFI_SUCCESS This driver supports this device. 104 @retval other This driver does not support this device. 105 106 **/ 107 EFI_STATUS 108 EFIAPI 109 ConPlatformTextOutDriverBindingSupported ( 110 IN EFI_DRIVER_BINDING_PROTOCOL *This, 111 IN EFI_HANDLE Handle, 112 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL 113 ); 114 115 /** 116 Start this driver on the device for console input. 117 118 Start this driver on ControllerHandle by opening Simple Text Input Protocol, 119 reading Device Path, and installing Console In Devcice GUID on ControllerHandle. 120 121 If this devcie is not one hot-plug devce, append its device path into the 122 console environment variables ConInDev. 123 124 @param This Protocol instance pointer. 125 @param ControllerHandle Handle of device to bind driver to 126 @param RemainingDevicePath Optional parameter use to pick a specific child 127 device to start. 128 129 @retval EFI_SUCCESS This driver is added to ControllerHandle 130 @retval EFI_ALREADY_STARTED This driver is already running on ControllerHandle 131 @retval other This driver does not support this device. 132 133 **/ 134 EFI_STATUS 135 EFIAPI 136 ConPlatformTextInDriverBindingStart ( 137 IN EFI_DRIVER_BINDING_PROTOCOL *This, 138 IN EFI_HANDLE Handle, 139 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath 140 ); 141 142 /** 143 Start this driver on the device for console output and stardard error output. 144 145 Start this driver on ControllerHandle by opening Simple Text Output Protocol, 146 reading Device Path, and installing Console Out Devcic GUID, Standard Error 147 Device GUID on ControllerHandle. 148 149 If this devcie is not one hot-plug devce, append its device path into the 150 console environment variables ConOutDev, StdErrDev. 151 152 @param This Protocol instance pointer. 153 @param ControllerHandle Handle of device to bind driver to 154 @param RemainingDevicePath Optional parameter use to pick a specific child 155 device to start. 156 157 @retval EFI_SUCCESS This driver is added to ControllerHandle 158 @retval EFI_ALREADY_STARTED This driver is already running on ControllerHandle 159 @retval other This driver does not support this device 160 161 **/ 162 EFI_STATUS 163 EFIAPI 164 ConPlatformTextOutDriverBindingStart ( 165 IN EFI_DRIVER_BINDING_PROTOCOL *This, 166 IN EFI_HANDLE Handle, 167 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath 168 ); 169 170 /** 171 Stop this driver on ControllerHandle by removing Console In Devcice GUID 172 and closing the Simple Text Input protocol on ControllerHandle. 173 174 @param This Protocol instance pointer. 175 @param ControllerHandle Handle of device to stop driver on 176 @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of 177 children is zero stop the entire bus driver. 178 @param ChildHandleBuffer List of Child Handles to Stop. 179 180 @retval EFI_SUCCESS This driver is removed ControllerHandle 181 @retval other This driver was not removed from this device 182 183 **/ 184 EFI_STATUS 185 EFIAPI 186 ConPlatformTextInDriverBindingStop ( 187 IN EFI_DRIVER_BINDING_PROTOCOL *This, 188 IN EFI_HANDLE Handle, 189 IN UINTN NumberOfChildren, 190 IN EFI_HANDLE *ChildHandleBuffer 191 ); 192 193 /** 194 Stop this driver on ControllerHandle by removing Console Out Devcice GUID 195 and closing the Simple Text Output protocol on ControllerHandle. 196 197 @param This Protocol instance pointer. 198 @param ControllerHandle Handle of device to stop driver on 199 @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of 200 children is zero stop the entire bus driver. 201 @param ChildHandleBuffer List of Child Handles to Stop. 202 203 @retval EFI_SUCCESS This driver is removed ControllerHandle 204 @retval other This driver was not removed from this device 205 206 **/ 207 EFI_STATUS 208 EFIAPI 209 ConPlatformTextOutDriverBindingStop ( 210 IN EFI_DRIVER_BINDING_PROTOCOL *This, 211 IN EFI_HANDLE Handle, 212 IN UINTN NumberOfChildren, 213 IN EFI_HANDLE *ChildHandleBuffer 214 ); 215 216 /** 217 Uninstall the specified protocol. 218 219 @param This Protocol instance pointer. 220 @param Handle Handle of device to uninstall protocol on. 221 @param ProtocolGuid The specified protocol need to be uninstalled. 222 223 **/ 224 VOID 225 ConPlatformUnInstallProtocol ( 226 IN EFI_DRIVER_BINDING_PROTOCOL *This, 227 IN EFI_HANDLE Handle, 228 IN EFI_GUID *ProtocolGuid 229 ); 230 231 /** 232 Read the EFI variable (Name) and return a dynamically allocated 233 buffer, and the size of the buffer. On failure return NULL. 234 235 @param Name String part of EFI variable name 236 237 @return Dynamically allocated memory that contains a copy of the EFI variable. 238 Caller is repsoncible freeing the buffer. Return NULL means Variable 239 was not read. 240 241 **/ 242 VOID * 243 ConPlatformGetVariable ( 244 IN CHAR16 *Name 245 ); 246 247 /** 248 Function compares a device path data structure to that of all the nodes of a 249 second device path instance. 250 251 252 @param Multi A pointer to a multi-instance device path data structure. 253 @param Single A pointer to a single-instance device path data structure. 254 @param NewDevicePath If Delete is TRUE, this parameter must not be null, and it 255 points to the remaining device path data structure. 256 (remaining device path = Multi - Single.) 257 @param Delete If TRUE, means removing Single from Multi. 258 If FALSE, the routine just check whether Single matches 259 with any instance in Multi. 260 261 @retval EFI_SUCCESS If the Single is contained within Multi. 262 @retval EFI_NOT_FOUND If the Single is not contained within Multi. 263 @retval EFI_INVALID_PARAMETER Multi is NULL. 264 @retval EFI_INVALID_PARAMETER Single is NULL. 265 @retval EFI_INVALID_PARAMETER NewDevicePath is NULL when Delete is TRUE. 266 267 **/ 268 EFI_STATUS 269 ConPlatformMatchDevicePaths ( 270 IN EFI_DEVICE_PATH_PROTOCOL *Multi, 271 IN EFI_DEVICE_PATH_PROTOCOL *Single, 272 OUT EFI_DEVICE_PATH_PROTOCOL **NewDevicePath OPTIONAL, 273 IN BOOLEAN Delete 274 ); 275 276 /** 277 Update console environment variables. 278 279 @param VariableName Console environment variables, ConOutDev, ConInDev 280 StdErrDev, ConIn or ConOut. 281 @param DevicePath Console devcie's device path. 282 @param Operation Variable operations, including APPEND, CHECK and DELETE. 283 284 @retval EFI_SUCCESS Variable operates successfully. 285 @retval EFI_OUT_OF_RESOURCES If variable cannot be appended. 286 @retval other Variable updating failed. 287 288 **/ 289 EFI_STATUS 290 ConPlatformUpdateDeviceVariable ( 291 IN CHAR16 *VariableName, 292 IN EFI_DEVICE_PATH_PROTOCOL *DevicePath, 293 IN CONPLATFORM_VAR_OPERATION Operation 294 ); 295 296 /** 297 Check if the device supports hot-plug through its device path. 298 299 This function could be updated to check more types of Hot Plug devices. 300 Currently, it checks USB and PCCard device. 301 302 @param DevicePath Pointer to device's device path. 303 304 @retval TRUE The devcie is a hot-plug device 305 @retval FALSE The devcie is not a hot-plug device. 306 307 **/ 308 BOOLEAN 309 IsHotPlugDevice ( 310 IN EFI_DEVICE_PATH_PROTOCOL *DevicePath 311 ); 312 313 // 314 // EFI Component Name Functions 315 // 316 /** 317 Retrieves a Unicode string that is the user readable name of the driver. 318 319 This function retrieves the user readable name of a driver in the form of a 320 Unicode string. If the driver specified by This has a user readable name in 321 the language specified by Language, then a pointer to the driver name is 322 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified 323 by This does not support the language specified by Language, 324 then EFI_UNSUPPORTED is returned. 325 326 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 327 EFI_COMPONENT_NAME_PROTOCOL instance. 328 @param Language[in] A pointer to a Null-terminated ASCII string 329 array indicating the language. This is the 330 language of the driver name that the caller is 331 requesting, and it must match one of the 332 languages specified in SupportedLanguages. The 333 number of languages supported by a driver is up 334 to the driver writer. Language is specified 335 in RFC 4646 or ISO 639-2 language code format. 336 @param DriverName[out] A pointer to the Unicode string to return. 337 This Unicode string is the name of the 338 driver specified by This in the language 339 specified by Language. 340 341 @retval EFI_SUCCESS The Unicode string for the Driver specified by 342 This and the language specified by Language was 343 returned in DriverName. 344 @retval EFI_INVALID_PARAMETER Language is NULL. 345 @retval EFI_INVALID_PARAMETER DriverName is NULL. 346 @retval EFI_UNSUPPORTED The driver specified by This does not support 347 the language specified by Language. 348 349 **/ 350 EFI_STATUS 351 EFIAPI 352 ConPlatformComponentNameGetDriverName ( 353 IN EFI_COMPONENT_NAME_PROTOCOL *This, 354 IN CHAR8 *Language, 355 OUT CHAR16 **DriverName 356 ); 357 358 359 /** 360 Retrieves a Unicode string that is the user readable name of the controller 361 that is being managed by a driver. 362 363 This function retrieves the user readable name of the controller specified by 364 ControllerHandle and ChildHandle in the form of a Unicode string. If the 365 driver specified by This has a user readable name in the language specified by 366 Language, then a pointer to the controller name is returned in ControllerName, 367 and EFI_SUCCESS is returned. If the driver specified by This is not currently 368 managing the controller specified by ControllerHandle and ChildHandle, 369 then EFI_UNSUPPORTED is returned. If the driver specified by This does not 370 support the language specified by Language, then EFI_UNSUPPORTED is returned. 371 372 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 373 EFI_COMPONENT_NAME_PROTOCOL instance. 374 @param ControllerHandle[in] The handle of a controller that the driver 375 specified by This is managing. This handle 376 specifies the controller whose name is to be 377 returned. 378 @param ChildHandle[in] The handle of the child controller to retrieve 379 the name of. This is an optional parameter that 380 may be NULL. It will be NULL for device 381 drivers. It will also be NULL for a bus drivers 382 that wish to retrieve the name of the bus 383 controller. It will not be NULL for a bus 384 driver that wishes to retrieve the name of a 385 child controller. 386 @param Language[in] A pointer to a Null-terminated ASCII string 387 array indicating the language. This is the 388 language of the driver name that the caller is 389 requesting, and it must match one of the 390 languages specified in SupportedLanguages. The 391 number of languages supported by a driver is up 392 to the driver writer. Language is specified in 393 RFC 4646 or ISO 639-2 language code format. 394 @param ControllerName[out] A pointer to the Unicode string to return. 395 This Unicode string is the name of the 396 controller specified by ControllerHandle and 397 ChildHandle in the language specified by 398 Language from the point of view of the driver 399 specified by This. 400 401 @retval EFI_SUCCESS The Unicode string for the user readable name in 402 the language specified by Language for the 403 driver specified by This was returned in 404 DriverName. 405 @retval EFI_INVALID_PARAMETER ControllerHandle is NULL. 406 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid 407 EFI_HANDLE. 408 @retval EFI_INVALID_PARAMETER Language is NULL. 409 @retval EFI_INVALID_PARAMETER ControllerName is NULL. 410 @retval EFI_UNSUPPORTED The driver specified by This is not currently 411 managing the controller specified by 412 ControllerHandle and ChildHandle. 413 @retval EFI_UNSUPPORTED The driver specified by This does not support 414 the language specified by Language. 415 416 **/ 417 EFI_STATUS 418 EFIAPI 419 ConPlatformComponentNameGetControllerName ( 420 IN EFI_COMPONENT_NAME_PROTOCOL *This, 421 IN EFI_HANDLE ControllerHandle, 422 IN EFI_HANDLE ChildHandle OPTIONAL, 423 IN CHAR8 *Language, 424 OUT CHAR16 **ControllerName 425 ); 426 427 /** 428 Update ConOutDev and ErrOutDev variables to add the device path of 429 GOP controller itself and the sibling controllers. 430 431 @param DevicePath Pointer to device's device path. 432 433 @retval TRUE The devcie is a GOP device. 434 @retval FALSE The devcie is not a GOP device. 435 436 **/ 437 BOOLEAN 438 ConPlatformUpdateGopCandidate ( 439 IN EFI_DEVICE_PATH_PROTOCOL *DevicePath 440 ); 441 442 #endif 443