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