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   SPDX-License-Identifier: BSD-2-Clause-Patent
  33
  34   @par Revision Reference:
  35   This Protocol is defined in UEFI Platform Initialization Specification 1.2
  36   Volume 5: Standards
  37
  38 **/
  39
  40 #ifndef __PCI_HOTPLUG_REQUEST_H_
  41 #define __PCI_HOTPLUG_REQUEST_H_
  42
  43 ///
  44 /// Global ID for EFI_PCI_HOTPLUG_REQUEST_PROTOCOL
  45 ///
  46 #define EFI_PCI_HOTPLUG_REQUEST_PROTOCOL_GUID \
  47   { \
  48     0x19cb87ab, 0x2cb9, 0x4665, {0x83, 0x60, 0xdd, 0xcf, 0x60, 0x54, 0xf7, 0x9d} \
  49   }
  50
  51 ///
  52 /// Forward declaration for EFI_PCI_HOTPLUG_REQUEST_PROTOCOL
  53 ///
  54 typedef struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL EFI_PCI_HOTPLUG_REQUEST_PROTOCOL;
  55
  56 ///
  57 /// Enumeration of PCI hot plug operations
  58 ///
  59 typedef enum {
  60   ///
  61   /// The PCI bus driver is requested to create handles for the specified devices.
  62   /// An array of EFI_HANDLE is returned, with a NULL element marking the end of
  63   /// the array.
  64   ///
  65   EfiPciHotPlugRequestAdd,
  66
  67   ///
  68   /// The PCI bus driver is requested to destroy handles for the specified devices.
  69   ///
  70   EfiPciHotplugRequestRemove
  71 } EFI_PCI_HOTPLUG_OPERATION;
  72
  73 /**
  74   This function is used to notify PCI bus driver that some events happened in a
  75   hot-plug controller, and the PCI bus driver is requested to start or stop
  76   specified PCI-like devices.
  77
  78   This function allows the PCI bus driver to be notified to act as requested when
  79   a hot-plug event has happened on the hot-plug controller. Currently, the
  80   operations include add operation and remove operation.  If it is a add operation,
  81   the PCI bus driver will enumerate, allocate resources for devices behind the
  82   hot-plug controller, and create handle for the device specified by RemainingDevicePath.
  83   The RemainingDevicePath is an optional parameter. If it is not NULL, only the
  84   specified device is started; if it is NULL, all devices behind the hot-plug
  85   controller are started.  The newly created handles of PC Card functions are
  86   returned in the ChildHandleBuffer, together with the number of child handle in
  87   NumberOfChildren.  If it is a remove operation, when NumberOfChildren contains
  88   a non-zero value, child handles specified in ChildHandleBuffer are stopped and
  89   destroyed; otherwise, PCI bus driver is notified to stop managing the controller
  90   handle.
  91
  92     @param[in] This                    A pointer to the EFI_PCI_HOTPLUG_REQUEST_PROTOCOL
  93                                        instance.
  94     @param[in] Operation               The operation the PCI bus driver is requested
  95                                        to make.
  96     @param[in] Controller              The handle of the hot-plug controller.
  97     @param[in] RemainingDevicePath     The remaining device path for the PCI-like
  98                                        hot-plug device.  It only contains device
  99                                        path nodes behind the hot-plug controller.
 100                                        It is an optional parameter and only valid
 101                                        when the Operation is a add operation. If
 102                                        it is NULL, all devices behind the PC Card
 103                                        socket are started.
 104     @param[in,out] NumberOfChildren    The number of child handles. For an add
 105                                        operation, it is an output parameter.  For
 106                                        a remove operation, it's an input parameter.
 107                                        When it contains a non-zero value, children
 108                                        handles specified in ChildHandleBuffer are
 109                                        destroyed.  Otherwise, PCI bus driver is
 110                                        notified to stop managing the controller
 111                                        handle.
 112     @param[in,out] ChildHandleBuffer   The buffer which contains the child handles.
 113                                        For an add operation, it is an output
 114                                        parameter and contains all newly created
 115                                        child handles.  For a remove operation, it
 116                                        contains child handles to be destroyed when
 117                                        NumberOfChildren contains a non-zero value.
 118                                        It can be NULL when NumberOfChildren is 0.
 119                                        It's the caller's responsibility to allocate
 120                                        and free memory for this buffer.
 121
 122   @retval EFI_SUCCESS             The handles for the specified device have been
 123                                   created or destroyed as requested, and for an
 124                                   add operation, the new handles are returned in
 125                                   ChildHandleBuffer.
 126   @retval EFI_INVALID_PARAMETER   Operation is not a legal value.
 127   @retval EFI_INVALID_PARAMETER   Controller is NULL or not a valid handle.
 128   @retval EFI_INVALID_PARAMETER   NumberOfChildren is NULL.
 129   @retval EFI_INVALID_PARAMETER   ChildHandleBuffer is NULL while Operation is
 130                                   remove and NumberOfChildren contains a non-zero
 131                                   value.
 132   @retval EFI_INVALID_PARAMETER   ChildHandleBuffer is NULL while Operation is add.
 133   @retval EFI_OUT_OF_RESOURCES    There are no enough resources to start the
 134                                   devices.
 135 **/
 136 typedef
 137 EFI_STATUS
 138 (EFIAPI *EFI_PCI_HOTPLUG_REQUEST_NOTIFY)(
 139   IN     EFI_PCI_HOTPLUG_REQUEST_PROTOCOL  *This,
 140   IN     EFI_PCI_HOTPLUG_OPERATION         Operation,
 141   IN     EFI_HANDLE                        Controller,
 142   IN     EFI_DEVICE_PATH_PROTOCOL          *RemainingDevicePath  OPTIONAL,
 143   IN OUT UINT8                             *NumberOfChildren,
 144   IN OUT EFI_HANDLE                        *ChildHandleBuffer
 145   );
 146
 147 ///
 148 /// Provides services to notify PCI bus driver that some events have happened in
 149 /// a hot-plug controller (for example, PC Card socket, or PHPC), and ask PCI bus
 150 /// driver to create or destroy handles for the PCI-like devices.
 151 ///
 152 struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL {
 153   ///
 154   /// Notify the PCI bus driver that some events have happened in a hot-plug
 155   /// controller (for example, PC Card socket, or PHPC), and ask PCI bus driver
 156   /// to create or destroy handles for the PCI-like devices. See Section 0 for
 157   /// a detailed description.
 158   ///
 159   EFI_PCI_HOTPLUG_REQUEST_NOTIFY    Notify;
 160 };
 161
 162 extern EFI_GUID  gEfiPciHotPlugRequestProtocolGuid;
 163
 164 #endif