MdePkg/Include/Protocol/PciHotPlugRequest.h

   1 /** @file
   2   Provides services to notify the PCI bus driver that some events have happened
   3   in a hot-plug controller (such as a PC Card socket, or PHPC), and to ask the
   4   PCI bus driver to create or destroy handles for PCI-like devices.
   5
   6   A hot-plug capable PCI bus driver should produce the EFI PCI Hot Plug Request
   7   protocol. When a PCI device or a PCI-like device (for example, 32-bit PC Card)
   8   is installed after PCI bus does the enumeration, the PCI bus driver can be
   9   notified through this protocol. For example, when a 32-bit PC Card is inserted
  10   into the PC Card socket, the PC Card bus driver can call interface of this
  11   protocol to notify PCI bus driver to allocate resource and create handles for
  12   this PC Card.
  13
  14   The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL is installed by the PCI bus driver on a
  15   separate handle when PCI bus driver starts up. There is only one instance in
  16   the system.  Any driver that wants to use this protocol must locate it globally.
  17   The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL allows the driver of hot-plug controller,
  18   for example, PC Card Bus driver, to notify PCI bus driver that an event has
  19   happened in the hot-plug controller, and the PCI bus driver is requested to
  20   create (add) or destroy (remove) handles for the specified PCI-like devices.
  21   For example, when a 32-bit PC Card is inserted, this protocol interface will
  22   be called with an add operation, and the PCI bus driver will enumerate and
  23   start the devices inserted; when a 32-bit PC Card is removed, this protocol
  24   interface will be called with a remove operation, and the PCI bus driver will
  25   stop the devices and destroy their handles.  The existence of this protocol
  26   represents the capability of the PCI bus driver. If this protocol exists in
  27   system, it means PCI bus driver is hot-plug capable, thus together with the
  28   effort of PC Card bus driver, hot-plug of PC Card can be supported. Otherwise,
  29   the hot-plug capability is not provided.
  30
  31   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
  32   This program and the accompanying materials
  33   are licensed and made available under the terms and conditions of the BSD License
  34   which accompanies this distribution.  The full text of the license may be found at
  35   http://opensource.org/licenses/bsd-license.php
  36
  37   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  38   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  39
  40   @par Revision Reference:
  41   This Protocol is defined in UEFI Platform Initialization Specification 1.2
  42   Volume 5: Standards
  43
  44 **/
  45
  46 #ifndef __PCI_HOTPLUG_REQUEST_H_
  47 #define __PCI_HOTPLUG_REQUEST_H_
  48
  49 ///
  50 /// Global ID for EFI_PCI_HOTPLUG_REQUEST_PROTOCOL
  51 ///
  52 #define EFI_PCI_HOTPLUG_REQUEST_PROTOCOL_GUID \
  53   { \
  54     0x19cb87ab, 0x2cb9, 0x4665, {0x83, 0x60, 0xdd, 0xcf, 0x60, 0x54, 0xf7, 0x9d} \
  55   }
  56
  57 ///
  58 /// Forward declaration for EFI_PCI_HOTPLUG_REQUEST_PROTOCOL
  59 ///
  60 typedef struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL  EFI_PCI_HOTPLUG_REQUEST_PROTOCOL;
  61
  62 ///
  63 /// Enumeration of PCI hot plug operations
  64 ///
  65 typedef enum {
  66   ///
  67   /// The PCI bus driver is requested to create handles for the specified devices.
  68   /// An array of EFI_HANDLE is returned, with a NULL element marking the end of
  69   /// the array.
  70   ///
  71   EfiPciHotPlugRequestAdd,
  72
  73   ///
  74   /// The PCI bus driver is requested to destroy handles for the specified devices.
  75   ///
  76   EfiPciHotplugRequestRemove
  77 } EFI_PCI_HOTPLUG_OPERATION;
  78
  79 /**
  80   This function is used to notify PCI bus driver that some events happened in a
  81   hot-plug controller, and the PCI bus driver is requested to start or stop
  82   specified PCI-like devices.
  83
  84   This function allows the PCI bus driver to be notified to act as requested when
  85   a hot-plug event has happened on the hot-plug controller. Currently, the
  86   operations include add operation and remove operation.  If it is a add operation,
  87   the PCI bus driver will enumerate, allocate resources for devices behind the
  88   hot-plug controller, and create handle for the device specified by RemainingDevicePath.
  89   The RemainingDevicePath is an optional parameter. If it is not NULL, only the
  90   specified device is started; if it is NULL, all devices behind the hot-plug
  91   controller are started.  The newly created handles of PC Card functions are
  92   returned in the ChildHandleBuffer, together with the number of child handle in
  93   NumberOfChildren.  If it is a remove operation, when NumberOfChildren contains
  94   a non-zero value, child handles specified in ChildHandleBuffer are stopped and
  95   destroyed; otherwise, PCI bus driver is notified to stop managing the controller
  96   handle.
  97
  98     @param[in] This                    A pointer to the EFI_PCI_HOTPLUG_REQUEST_PROTOCOL
  99                                        instance.
 100     @param[in] Operation               The operation the PCI bus driver is requested
 101                                        to make.
 102     @param[in] Controller              The handle of the hot-plug controller.
 103     @param[in] RemainingDevicePath     The remaining device path for the PCI-like
 104                                        hot-plug device.  It only contains device
 105                                        path nodes behind the hot-plug controller.
 106                                        It is an optional parameter and only valid
 107                                        when the Operation is a add operation. If
 108                                        it is NULL, all devices behind the PC Card
 109                                        socket are started.
 110     @param[in,out] NumberOfChildren    The number of child handles. For an add
 111                                        operation, it is an output parameter.  For
 112                                        a remove operation, it's an input parameter.
 113                                        When it contains a non-zero value, children
 114                                        handles specified in ChildHandleBuffer are
 115                                        destroyed.  Otherwise, PCI bus driver is
 116                                        notified to stop managing the controller
 117                                        handle.
 118     @param[in,out] ChildHandleBuffer   The buffer which contains the child handles.
 119                                        For an add operation, it is an output
 120                                        parameter and contains all newly created
 121                                        child handles.  For a remove operation, it
 122                                        contains child handles to be destroyed when
 123                                        NumberOfChildren contains a non-zero value.
 124                                        It can be NULL when NumberOfChildren is 0.
 125                                        It's the caller's responsibility to allocate
 126                                        and free memory for this buffer.
 127
 128   @retval EFI_SUCCESS             The handles for the specified device have been
 129                                   created or destroyed as requested, and for an
 130                                   add operation, the new handles are returned in
 131                                   ChildHandleBuffer.
 132   @retval EFI_INVALID_PARAMETER   Operation is not a legal value.
 133   @retval EFI_INVALID_PARAMETER   Controller is NULL or not a valid handle.
 134   @retval EFI_INVALID_PARAMETER   NumberOfChildren is NULL.
 135   @retval EFI_INVALID_PARAMETER   ChildHandleBuffer is NULL while Operation is
 136                                   remove and NumberOfChildren contains a non-zero
 137                                   value.
 138   @retval EFI_INVALID_PARAMETER   ChildHandleBuffer is NULL while Operation is add.
 139   @retval EFI_OUT_OF_RESOURCES    There are no enough resources to start the
 140                                   devices.
 141 **/
 142 typedef
 143 EFI_STATUS
 144 (EFIAPI *EFI_PCI_HOTPLUG_REQUEST_NOTIFY)(
 145   IN     EFI_PCI_HOTPLUG_REQUEST_PROTOCOL  *This,
 146   IN     EFI_PCI_HOTPLUG_OPERATION         Operation,
 147   IN     EFI_HANDLE                        Controller,
 148   IN     EFI_DEVICE_PATH_PROTOCOL          *RemainingDevicePath  OPTIONAL,
 149   IN OUT UINT8                             *NumberOfChildren,
 150   IN OUT EFI_HANDLE                        *ChildHandleBuffer
 151   );
 152
 153 ///
 154 /// Provides services to notify PCI bus driver that some events have happened in
 155 /// a hot-plug controller (for example, PC Card socket, or PHPC), and ask PCI bus
 156 /// driver to create or destroy handles for the PCI-like devices.
 157 ///
 158 struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL {
 159   ///
 160   /// Notify the PCI bus driver that some events have happened in a hot-plug
 161   /// controller (for example, PC Card socket, or PHPC), and ask PCI bus driver
 162   /// to create or destroy handles for the PCI-like devices. See Section 0 for
 163   /// a detailed description.
 164   ///
 165   EFI_PCI_HOTPLUG_REQUEST_NOTIFY  Notify;
 166 };
 167
 168 extern EFI_GUID gEfiPciHotPlugRequestProtocolGuid;
 169
 170 #endif