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