OvmfPkg/SioBusDxe/SioBusDxe.h

   1 /** @file
   2   The SioBusDxe driver is used to create child devices on the ISA bus and
   3   installs the Super I/O protocols on them.
   4
   5   Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
   6
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #ifndef __SIO_BUS_DXE_H__
  12 #define __SIO_BUS_DXE_H__
  13
  14 #include <Uefi.h>
  15
  16 #include <IndustryStandard/Pci.h>
  17
  18 #include <Protocol/PciIo.h>
  19 #include <Protocol/SuperIo.h>
  20
  21 #include <Library/UefiDriverEntryPoint.h>
  22 #include <Library/UefiLib.h>
  23 #include <Library/UefiBootServicesTableLib.h>
  24 #include <Library/DebugLib.h>
  25 #include <Library/ReportStatusCodeLib.h>
  26 #include <Library/MemoryAllocationLib.h>
  27 #include <Library/BaseMemoryLib.h>
  28 #include <Library/DevicePathLib.h>
  29
  30 #include "SioService.h"
  31
  32 //
  33 // SIO Bus driver private data structure
  34 //
  35 typedef struct {
  36   EFI_PCI_IO_PROTOCOL    *PciIo;
  37   UINT64                 OriginalAttributes;
  38 } SIO_BUS_DRIVER_PRIVATE_DATA;
  39
  40 //
  41 // Global Variables
  42 //
  43 extern EFI_COMPONENT_NAME_PROTOCOL   gSioBusComponentName;
  44 extern EFI_COMPONENT_NAME2_PROTOCOL  gSioBusComponentName2;
  45
  46 //
  47 // EFI Component Name Functions
  48 //
  49
  50 /**
  51   Retrieves a Unicode string that is the user readable name of the driver.
  52
  53   This function retrieves the user readable name of a driver in the form of a
  54   Unicode string. If the driver specified by This has a user readable name in
  55   the language specified by Language, then a pointer to the driver name is
  56   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
  57   by This does not support the language specified by Language, then
  58   EFI_UNSUPPORTED is returned.
  59
  60   @param[in]  This              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL
  61                                 or EFI_COMPONENT_NAME_PROTOCOL instance.
  62   @param[in]  Language          A pointer to a Null-terminated ASCII string
  63                                 array indicating the language. This is the
  64                                 language of the driver name that the caller is
  65                                 requesting, and it must match one of the
  66                                 languages specified in SupportedLanguages. The
  67                                 number of languages supported by a driver is up
  68                                 to the driver writer. Language is specified
  69                                 in RFC 4646 or ISO 639-2 language code format.
  70   @param[out] DriverName        A pointer to the Unicode string to return. This
  71                                 Unicode string is the name of the driver
  72                                 specified by This in the language specified by
  73                                 Language.
  74
  75   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
  76                                 This and the language specified by Language was
  77                                 returned in DriverName.
  78   @retval EFI_INVALID_PARAMETER Language is NULL.
  79   @retval EFI_INVALID_PARAMETER DriverName is NULL.
  80   @retval EFI_UNSUPPORTED       The driver specified by This does not support
  81                                 the language specified by Language.
  82
  83 **/
  84 EFI_STATUS
  85 EFIAPI
  86 SioBusComponentNameGetDriverName (
  87   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
  88   IN  CHAR8                        *Language,
  89   OUT CHAR16                       **DriverName
  90   );
  91
  92 /**
  93   Retrieves a Unicode string that is the user readable name of the controller
  94   that is being managed by a driver.
  95
  96   This function retrieves the user readable name of the controller specified by
  97   ControllerHandle and ChildHandle in the form of a Unicode string. If the
  98   driver specified by This has a user readable name in the language specified
  99   by Language, then a pointer to the controller name is returned in
 100   ControllerName, and EFI_SUCCESS is returned.  If the driver specified by This
 101   is not currently managing the controller specified by ControllerHandle and
 102   ChildHandle, then EFI_UNSUPPORTED is returned.  If the driver specified by
 103   This does not support the language specified by Language, then
 104   EFI_UNSUPPORTED is returned.
 105
 106   @param[in]  This              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL
 107                                 or EFI_COMPONENT_NAME_PROTOCOL instance.
 108   @param[in]  ControllerHandle  The handle of a controller that the driver
 109                                 specified by This is managing.  This handle
 110                                 specifies the controller whose name is to be
 111                                 returned.
 112   @param[in]  ChildHandle       The handle of the child controller to retrieve
 113                                 the name of.  This is an optional parameter
 114                                 that may be NULL.  It will be NULL for device
 115                                 drivers.  It will also be NULL for a bus
 116                                 drivers that wish to retrieve the name of the
 117                                 bus controller.  It will not be NULL for a bus
 118                                 driver that wishes to retrieve the name of a
 119                                 child controller.
 120   @param[in]  Language          A pointer to a Null-terminated ASCII string
 121                                 array indicating the language.  This is the
 122                                 language of the driver name that the caller is
 123                                 requesting, and it must match one of the
 124                                 languages specified in SupportedLanguages. The
 125                                 number of languages supported by a driver is up
 126                                 to the driver writer. Language is specified in
 127                                 RFC 4646 or ISO 639-2 language code format.
 128   @param[out] ControllerName    A pointer to the Unicode string to return.
 129                                 This Unicode string is the name of the
 130                                 controller specified by ControllerHandle and
 131                                 ChildHandle in the language specified by
 132                                 Language from the point of view of the driver
 133                                 specified by This.
 134
 135   @retval EFI_SUCCESS           The Unicode string for the user readable name
 136                                 in the language specified by Language for the
 137                                 driver specified by This was returned in
 138                                 DriverName.
 139   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 140   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 141                                 EFI_HANDLE.
 142   @retval EFI_INVALID_PARAMETER Language is NULL.
 143   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 144   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 145                                 managing the controller specified by
 146                                 ControllerHandle and ChildHandle.
 147   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 148                                 the language specified by Language.
 149
 150 **/
 151 EFI_STATUS
 152 EFIAPI
 153 SioBusComponentNameGetControllerName (
 154   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 155   IN  EFI_HANDLE                   ControllerHandle,
 156   IN  EFI_HANDLE                   ChildHandle        OPTIONAL,
 157   IN  CHAR8                        *Language,
 158   OUT CHAR16                       **ControllerName
 159   );
 160
 161 //
 162 // Driver Binding Protocol interfaces
 163 //
 164
 165 /**
 166   Tests to see if this driver supports a given controller. If a child device is
 167   provided, it further tests to see if this driver supports creating a handle
 168   for the specified child device.
 169
 170   This function checks to see if the driver specified by This supports the
 171   device specified by ControllerHandle. Drivers will typically use the device
 172   path attached to ControllerHandle and/or the services from the bus I/O
 173   abstraction attached to ControllerHandle to determine if the driver supports
 174   ControllerHandle. This function may be called many times during platform
 175   initialization. In order to reduce boot times, the tests performed by this
 176   function must be very small, and take as little time as possible to execute.
 177   This function must not change the state of any hardware devices, and this
 178   function must be aware that the device specified by ControllerHandle may
 179   already be managed by the same driver or a different driver. This function
 180   must match its calls to AllocatePages() with FreePages(), AllocatePool() with
 181   FreePool(), and OpenProtocol() with CloseProtocol(). Since ControllerHandle
 182   may have been previously started by the same driver, if a protocol is already
 183   in the opened state, then it must not be closed with CloseProtocol(). This is
 184   required to guarantee the state of ControllerHandle is not modified by this
 185   function.
 186
 187   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL
 188                                    instance.
 189   @param[in]  ControllerHandle     The handle of the controller to test. This
 190                                    handle must support a protocol interface
 191                                    that supplies an I/O abstraction to the
 192                                    driver.
 193   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a
 194                                    device path.  This parameter is ignored by
 195                                    device drivers, and is optional for bus
 196                                    drivers. For bus drivers, if this parameter
 197                                    is not NULL, then the bus driver must
 198                                    determine if the bus controller specified by
 199                                    ControllerHandle and the child controller
 200                                    specified by RemainingDevicePath are both
 201                                    supported by this bus driver.
 202
 203   @retval EFI_SUCCESS              The device specified by ControllerHandle and
 204                                    RemainingDevicePath is supported by the
 205                                    driver specified by This.
 206   @retval EFI_ALREADY_STARTED      The device specified by ControllerHandle and
 207                                    RemainingDevicePath is already being managed
 208                                    by the driver specified by This.
 209   @retval EFI_ACCESS_DENIED        The device specified by ControllerHandle and
 210                                    RemainingDevicePath is already being managed
 211                                    by a different driver or an application that
 212                                    requires exclusive access.
 213   @retval EFI_UNSUPPORTED          The device specified by ControllerHandle and
 214                                    RemainingDevicePath is not supported by the
 215                                    driver specified by This.
 216
 217 **/
 218 EFI_STATUS
 219 EFIAPI
 220 SioBusDriverBindingSupported (
 221   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 222   IN EFI_HANDLE                   Controller,
 223   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 224   );
 225
 226 /**
 227   Starts a device controller or a bus controller.
 228
 229   The Start() function is designed to be invoked from the EFI boot service
 230   ConnectController(). As a result, much of the error checking on the
 231   parameters to Start() has been moved into this common boot service. It is
 232   legal to call Start() from other locations, but the following calling
 233   restrictions must be followed or the system behavior will not be
 234   deterministic.
 235   1. ControllerHandle must be a valid EFI_HANDLE.
 236   2. If RemainingDevicePath is not NULL, then it must be a pointer to a
 237      naturally aligned EFI_DEVICE_PATH_PROTOCOL.
 238   3. Prior to calling Start(), the Supported() function for the driver
 239      specified by This must have been called with the same calling parameters,
 240      and Supported() must have returned EFI_SUCCESS.
 241
 242   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL
 243                                    instance.
 244   @param[in]  ControllerHandle     The handle of the controller to start. This
 245                                    handle must support a protocol interface
 246                                    that supplies an I/O abstraction to the
 247                                    driver.
 248   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a
 249                                    device path.  This parameter is ignored by
 250                                    device drivers, and is optional for bus
 251                                    drivers. For a bus driver, if this parameter
 252                                    is NULL, then handles for all the children
 253                                    of Controller are created by this driver. If
 254                                    this parameter is not NULL and the first
 255                                    Device Path Node is not the End of Device
 256                                    Path Node, then only the handle for the
 257                                    child device specified by the first Device
 258                                    Path Node of RemainingDevicePath is created
 259                                    by this driver. If the first Device Path
 260                                    Node of RemainingDevicePath is the End of
 261                                    Device Path Node, no child handle is created
 262                                    by this driver.
 263
 264   @retval EFI_SUCCESS              The device was started.
 265   @retval EFI_DEVICE_ERROR         The device could not be started due to a
 266                                    device error.
 267   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a
 268                                    lack of resources.
 269   @retval Others                   The driver failded to start the device.
 270
 271 **/
 272 EFI_STATUS
 273 EFIAPI
 274 SioBusDriverBindingStart (
 275   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 276   IN EFI_HANDLE                   Controller,
 277   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 278   );
 279
 280 /**
 281   Stops a device controller or a bus controller.
 282
 283   The Stop() function is designed to be invoked from the EFI boot service
 284   DisconnectController(). As a result, much of the error checking on the
 285   parameters to Stop() has been moved into this common boot service. It is
 286   legal to call Stop() from other locations, but the following calling
 287   restrictions must be followed or the system behavior will not be
 288   deterministic.
 289   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous
 290      call to this same driver's Start() function.
 291   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a
 292      valid EFI_HANDLE. In addition, all of these handles must have been created
 293      in this driver's Start() function, and the Start() function must have
 294      called OpenProtocol() on ControllerHandle with an Attribute of
 295      EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 296
 297   @param[in]  This               A pointer to the EFI_DRIVER_BINDING_PROTOCOL
 298                                  instance.
 299   @param[in]  ControllerHandle   A handle to the device being stopped. The
 300                                  handle must support a bus specific I/O
 301                                  protocol for the driver to use to stop the
 302                                  device.
 303   @param[in]  NumberOfChildren   The number of child device handles in
 304                                  ChildHandleBuffer.
 305   @param[in]  ChildHandleBuffer  An array of child handles to be freed. May be
 306                                  NULL if NumberOfChildren is 0.
 307
 308   @retval EFI_SUCCESS            The device was stopped.
 309   @retval EFI_DEVICE_ERROR       The device could not be stopped due to a
 310                                  device error.
 311
 312 **/
 313 EFI_STATUS
 314 EFIAPI
 315 SioBusDriverBindingStop (
 316   IN  EFI_DRIVER_BINDING_PROTOCOL  *This,
 317   IN  EFI_HANDLE                   Controller,
 318   IN  UINTN                        NumberOfChildren,
 319   IN  EFI_HANDLE                   *ChildHandleBuffer
 320   );
 321
 322 #endif // __SIO_BUS_DXE_H__