NetworkPkg/ArpDxe/ArpDriver.h

   1 /** @file
   2   ARP driver header file.
   3
   4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef _ARP_DRIVER_H_
  10 #define _ARP_DRIVER_H_
  11
  12 #include <Uefi.h>
  13
  14 #include <Protocol/Arp.h>
  15 #include <Protocol/ManagedNetwork.h>
  16 #include <Protocol/ServiceBinding.h>
  17
  18 #include <Library/DebugLib.h>
  19 #include <Library/UefiDriverEntryPoint.h>
  20 #include <Library/UefiBootServicesTableLib.h>
  21 #include <Library/UefiLib.h>
  22
  23 //
  24 // Global variables
  25 //
  26 extern EFI_DRIVER_BINDING_PROTOCOL   gArpDriverBinding;
  27 extern EFI_COMPONENT_NAME_PROTOCOL   gArpComponentName;
  28 extern EFI_COMPONENT_NAME2_PROTOCOL  gArpComponentName2;
  29
  30 //
  31 // Function prototypes for the Driver Binding Protocol
  32 //
  33
  34 /**
  35   Tests to see if this driver supports a given controller.
  36
  37   If a child device is provided, it further tests to see if this driver supports
  38   creating a handle for the specified child device.
  39
  40   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  41   @param[in]  ControllerHandle     The handle of the controller to test. This handle
  42                                    must support a protocol interface that supplies
  43                                    an I/O abstraction to the driver.
  44   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.
  45                                    This parameter is ignored by device drivers,
  46                                    and is optional for bus drivers.
  47
  48   @retval EFI_SUCCESS              The device specified by ControllerHandle and
  49                                    RemainingDevicePath is supported by the driver
  50                                    specified by This.
  51   @retval EFI_ALREADY_STARTED      The device specified by ControllerHandle and
  52                                    RemainingDevicePath is already being managed
  53                                    by the driver specified by This.
  54   @retval EFI_ACCESS_DENIED        The device specified by ControllerHandle and
  55                                    RemainingDevicePath is already being managed by
  56                                    a different driver or an application that
  57                                    requires exclusive access. Currently not implemented.
  58   @retval EFI_UNSUPPORTED          The device specified by ControllerHandle and
  59                                    RemainingDevicePath is not supported by the
  60                                    driver specified by This.
  61
  62 **/
  63 EFI_STATUS
  64 EFIAPI
  65 ArpDriverBindingSupported (
  66   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
  67   IN EFI_HANDLE                   ControllerHandle,
  68   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
  69   );
  70
  71 /**
  72   Start this driver on ControllerHandle.
  73
  74   The Start() function is designed to be invoked from the EFI boot service ConnectController().
  75   As a result, much of the error checking on the parameters to Start() has been
  76   moved into this common boot service. It is legal to call Start() from other locations,
  77   but the following calling restrictions must be followed or the system behavior
  78   will not be deterministic.
  79   1. ControllerHandle must be a valid EFI_HANDLE.
  80   2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally
  81      aligned EFI_DEVICE_PATH_PROTOCOL.
  82   3. Prior to calling Start(), the Supported() function for the driver specified
  83      by This must have been called with the same calling parameters, and Supported()
  84      must have returned EFI_SUCCESS.
  85
  86   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  87   @param[in]  ControllerHandle     The handle of the controller to start. This handle
  88                                    must support a protocol interface that supplies
  89                                    an I/O abstraction to the driver.
  90   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.
  91                                    This parameter is ignored by device drivers,
  92                                    and is optional for bus drivers.
  93
  94   @retval EFI_SUCCESS              The device was started.
  95   @retval EFI_DEVICE_ERROR         The device could not be started due to a device error.
  96                                    Currently not implemented.
  97   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of
  98                                    resources.
  99   @retval Others                   The driver failed to start the device.
 100
 101 **/
 102 EFI_STATUS
 103 EFIAPI
 104 ArpDriverBindingStart (
 105   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 106   IN EFI_HANDLE                   ControllerHandle,
 107   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 108   );
 109
 110 /**
 111   Stop this driver on ControllerHandle.
 112
 113   Release the control of this controller and remove the IScsi functions. The Stop()
 114   function is designed to be invoked from the EFI boot service DisconnectController().
 115   As a result, much of the error checking on the parameters to Stop() has been moved
 116   into this common boot service. It is legal to call Stop() from other locations,
 117   but the following calling restrictions must be followed or the system behavior
 118   will not be deterministic.
 119   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
 120      same driver's Start() function.
 121   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
 122      EFI_HANDLE. In addition, all of these handles must have been created in this driver's
 123      Start() function, and the Start() function must have called OpenProtocol() on
 124      ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 125
 126   @param[in]  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 127   @param[in]  ControllerHandle  A handle to the device being stopped. The handle must
 128                                 support a bus specific I/O protocol for the driver
 129                                 to use to stop the device.
 130   @param[in]  NumberOfChildren  The number of child device handles in ChildHandleBuffer.
 131                                 Not used.
 132   @param[in]  ChildHandleBuffer An array of child handles to be freed. May be NULL
 133                                 if NumberOfChildren is 0.Not used.
 134
 135   @retval EFI_SUCCESS           The device was stopped.
 136   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 137
 138 **/
 139 EFI_STATUS
 140 EFIAPI
 141 ArpDriverBindingStop (
 142   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 143   IN EFI_HANDLE                   ControllerHandle,
 144   IN UINTN                        NumberOfChildren,
 145   IN EFI_HANDLE                   *ChildHandleBuffer
 146   );
 147
 148 /**
 149   Creates a child handle and installs a protocol.
 150
 151   The CreateChild() function installs a protocol on ChildHandle.
 152   If ChildHandle is a pointer to NULL, then a new handle is created and returned
 153   in ChildHandle. If ChildHandle is not a pointer to NULL, then the protocol
 154   installs on the existing ChildHandle.
 155
 156   @param  This        Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.
 157   @param  ChildHandle Pointer to the handle of the child to create. If it is NULL,
 158                       then a new handle is created. If it is a pointer to an existing
 159                       UEFI handle, then the protocol is added to the existing UEFI handle.
 160
 161   @retval EFI_SUCCESS           The protocol was added to ChildHandle.
 162   @retval EFI_INVALID_PARAMETER ChildHandle is NULL.
 163   @retval EFI_OUT_OF_RESOURCES  There are not enough resources available to create
 164                                 the child
 165   @retval other                 The child handle was not created
 166
 167 **/
 168 EFI_STATUS
 169 EFIAPI
 170 ArpServiceBindingCreateChild (
 171   IN EFI_SERVICE_BINDING_PROTOCOL  *This,
 172   IN EFI_HANDLE                    *ChildHandle
 173   );
 174
 175 /**
 176   Destroys a child handle with a protocol installed on it.
 177
 178   The DestroyChild() function does the opposite of CreateChild(). It removes a protocol
 179   that was installed by CreateChild() from ChildHandle. If the removed protocol is the
 180   last protocol on ChildHandle, then ChildHandle is destroyed.
 181
 182   @param  This        Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.
 183   @param  ChildHandle Handle of the child to destroy
 184
 185   @retval EFI_SUCCESS           The protocol was removed from ChildHandle.
 186   @retval EFI_UNSUPPORTED       ChildHandle does not support the protocol that is
 187                                 being removed.
 188   @retval EFI_INVALID_PARAMETER Child handle is NULL.
 189   @retval EFI_ACCESS_DENIED     The protocol could not be removed from the ChildHandle
 190                                 because its services are being used.
 191   @retval other                 The child handle was not destroyed
 192
 193 **/
 194 EFI_STATUS
 195 EFIAPI
 196 ArpServiceBindingDestroyChild (
 197   IN EFI_SERVICE_BINDING_PROTOCOL  *This,
 198   IN EFI_HANDLE                    ChildHandle
 199   );
 200
 201 //
 202 // EFI Component Name Functions
 203 //
 204
 205 /**
 206   Retrieves a Unicode string that is the user readable name of the driver.
 207
 208   This function retrieves the user readable name of a driver in the form of a
 209   Unicode string. If the driver specified by This has a user readable name in
 210   the language specified by Language, then a pointer to the driver name is
 211   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 212   by This does not support the language specified by Language,
 213   then EFI_UNSUPPORTED is returned.
 214
 215   @param[in]  This              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 216                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 217
 218   @param[in]  Language          A pointer to a Null-terminated ASCII string
 219                                 array indicating the language. This is the
 220                                 language of the driver name that the caller is
 221                                 requesting, and it must match one of the
 222                                 languages specified in SupportedLanguages. The
 223                                 number of languages supported by a driver is up
 224                                 to the driver writer. Language is specified
 225                                 in RFC 4646 or ISO 639-2 language code format.
 226
 227   @param[out]  DriverName       A pointer to the Unicode string to return.
 228                                 This Unicode string is the name of the
 229                                 driver specified by This in the language
 230                                 specified by Language.
 231
 232   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 233                                 This and the language specified by Language was
 234                                 returned in DriverName.
 235
 236   @retval EFI_INVALID_PARAMETER Language is NULL.
 237
 238   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 239
 240   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 241                                 the language specified by Language.
 242
 243 **/
 244 EFI_STATUS
 245 EFIAPI
 246 ArpComponentNameGetDriverName (
 247   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 248   IN  CHAR8                        *Language,
 249   OUT CHAR16                       **DriverName
 250   );
 251
 252 /**
 253   Retrieves a Unicode string that is the user readable name of the controller
 254   that is being managed by a driver.
 255
 256   This function retrieves the user readable name of the controller specified by
 257   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 258   driver specified by This has a user readable name in the language specified by
 259   Language, then a pointer to the controller name is returned in ControllerName,
 260   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 261   managing the controller specified by ControllerHandle and ChildHandle,
 262   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 263   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 264
 265   @param[in]  This              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 266                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 267
 268   @param[in]  ControllerHandle  The handle of a controller that the driver
 269                                 specified by This is managing.  This handle
 270                                 specifies the controller whose name is to be
 271                                 returned.
 272
 273   @param[in]  ChildHandle       The handle of the child controller to retrieve
 274                                 the name of.  This is an optional parameter that
 275                                 may be NULL.  It will be NULL for device
 276                                 drivers.  It will also be NULL for a bus drivers
 277                                 that wish to retrieve the name of the bus
 278                                 controller.  It will not be NULL for a bus
 279                                 driver that wishes to retrieve the name of a
 280                                 child controller.
 281
 282   @param[in]  Language          A pointer to a Null-terminated ASCII string
 283                                 array indicating the language.  This is the
 284                                 language of the driver name that the caller is
 285                                 requesting, and it must match one of the
 286                                 languages specified in SupportedLanguages. The
 287                                 number of languages supported by a driver is up
 288                                 to the driver writer. Language is specified in
 289                                 RFC 4646 or ISO 639-2 language code format.
 290
 291   @param[out]  ControllerName   A pointer to the Unicode string to return.
 292                                 This Unicode string is the name of the
 293                                 controller specified by ControllerHandle and
 294                                 ChildHandle in the language specified by
 295                                 Language from the point of view of the driver
 296                                 specified by This.
 297
 298   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 299                                 the language specified by Language for the
 300                                 driver specified by This was returned in
 301                                 DriverName.
 302
 303   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 304
 305   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 306                                 EFI_HANDLE.
 307
 308   @retval EFI_INVALID_PARAMETER Language is NULL.
 309
 310   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 311
 312   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 313                                 managing the controller specified by
 314                                 ControllerHandle and ChildHandle.
 315
 316   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 317                                 the language specified by Language.
 318
 319 **/
 320 EFI_STATUS
 321 EFIAPI
 322 ArpComponentNameGetControllerName (
 323   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 324   IN  EFI_HANDLE                   ControllerHandle,
 325   IN  EFI_HANDLE                   ChildHandle        OPTIONAL,
 326   IN  CHAR8                        *Language,
 327   OUT CHAR16                       **ControllerName
 328   );
 329
 330 #endif