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