IntelFrameworkModulePkg/Include/Protocol/PciHotPlugRequest.h

   1 /** @file
   2   Provides services to notify the PCI bus driver that some events have happened in a hot-plug controller
   3   (such as a PC Card socket, or PHPC), and to ask the PCI bus driver to create or destroy handles for
   4   PCI-like devices.
   5
   6 Copyright (c) 2006 - 2009, Intel Corporation
   7 All rights reserved. This program and the accompanying materials
   8 are licensed and made available under the terms and conditions of the BSD License
   9 which accompanies this distribution.  The full text of the license may be found at
  10 http://opensource.org/licenses/bsd-license.php
  11
  12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15 **/
  16
  17 #ifndef __PCI_HOTPLUG_REQUEST_H_
  18 #define __PCI_HOTPLUG_REQUEST_H_
  19
  20 #define EFI_PCI_HOTPLUG_REQUEST_PROTOCOL_GUID \
  21   { \
  22     0x19cb87ab, 0x2cb9, 0x4665, {0x83, 0x60, 0xdd, 0xcf, 0x60, 0x54, 0xf7, 0x9d} \
  23   }
  24
  25 typedef enum {
  26   ///
  27   /// The PCI bus driver is requested to create handles for the specified devices. An array of
  28   /// EFI_HANDLE is returned, with a NULL element marking the end of the array.
  29   ///
  30   EfiPciHotPlugRequestAdd,
  31
  32   ///
  33   /// The PCI bus driver is requested to destroy handles for the specified devices.
  34   ///
  35   EfiPciHotplugRequestRemove
  36 } EFI_PCI_HOTPLUG_OPERATION;
  37
  38 typedef struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL  EFI_PCI_HOTPLUG_REQUEST_PROTOCOL;
  39
  40 /**
  41   This function allows the PCI bus driver to be notified to act as requested when a hot-plug event has  happened on the hot-plug controller. Currently, the operations include add operation and remove operation.
  42   @param This                    A pointer to the hot plug request protocol.
  43   @param Operation               The operation the PCI bus driver is requested to make.
  44   @param Controller              The handle of the hot-plug controller.
  45   @param RemainingDevicePath     The remaining device path for the PCI-like hot-plug device.
  46   @param NumberOfChildren        The number of child handles. For an add operation, it is an output parameter.
  47                                  For a remove operation, it's an input parameter. When it contains a non-zero
  48                                  value, children handles specified in ChildHandleBuffer are destroyed. Otherwise,
  49                                  PCI bus driver is notified to stop managing the controller handle.
  50   @param ChildHandleBuffer       The buffer which contains the child handles. For an add operation, it is an output
  51                                  parameter and contains all newly created child handles. For a remove operation, it
  52                                  contains child handles to be destroyed when NumberOfChildren contains a non-
  53                                  zero value. It can be NULL when NumberOfChildren is 0. It's the caller's
  54                                  responsibility to allocate and free memory for this buffer.
  55
  56   @retval EFI_SUCCESS            The handles for the specified device have been created or destroyed
  57                                  as requested, and for an add operation, the new handles are
  58                                  returned in ChildHandleBuffer.
  59   @retval EFI_INVALID_PARAMETER  Operation is not a legal value.
  60   @retval EFI_INVALID_PARAMETER  Controller is NULL or not a valid handle.
  61   @retval EFI_INVALID_PARAMETER  NumberOfChildren is NULL.
  62   @retval EFI_INVALID_PARAMETER  ChildHandleBuffer is NULL while Operation is remove and
  63                                  NumberOfChildren contains a non-zero value.
  64   @retval EFI_INVALID_PARAMETER  ChildHandleBuffer is NULL while Operation is add.
  65   @retval EFI_OUT_OF_RESOURCES   There are no enough resources to start the devices.
  66 **/
  67 typedef
  68 EFI_STATUS
  69 (EFIAPI *EFI_PCI_HOTPLUG_REQUEST_NOTIFY) (
  70  IN EFI_PCI_HOTPLUG_REQUEST_PROTOCOL *This,
  71  IN EFI_PCI_HOTPLUG_OPERATION        Operation,
  72  IN EFI_HANDLE                       Controller,
  73  IN EFI_DEVICE_PATH_PROTOCOL         *RemainingDevicePath OPTIONAL,
  74  IN OUT UINT8                        *NumberOfChildren,
  75  IN OUT EFI_HANDLE                   *ChildHandleBuffer
  76 );
  77
  78
  79
  80 struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL {
  81   EFI_PCI_HOTPLUG_REQUEST_NOTIFY     Notify;
  82 };
  83
  84 extern EFI_GUID gEfiPciHotPlugRequestProtocolGuid;
  85
  86 #endif