MdeModulePkg/Universal/Network/IScsiDxe/IScsiDriver.h

   1 /** @file
   2   The header file of IScsiDriver.c.
   3
   4 Copyright (c) 2004 - 2008, Intel Corporation.<BR>
   5 All rights reserved. This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef _ISCSI_DRIVER_H_
  16 #define _ISCSI_DRIVER_H_
  17
  18 #include <PiDxe.h>
  19 #include <Protocol/DevicePath.h>
  20 #include <Protocol/LoadedImage.h>
  21 #include <Protocol/HiiConfigAccess.h>
  22 #include <Protocol/HiiDatabase.h>
  23 #include <Library/UefiDriverEntryPoint.h>
  24 #include <Library/UefiBootServicesTableLib.h>
  25 #include <Library/UefiLib.h>
  26 #include <Library/DevicePathLib.h>
  27 #include <Protocol/DriverBinding.h>
  28 #include <Protocol/ScsiPassThruExt.h>
  29 #include <Protocol/IScsiInitiatorName.h>
  30 #include <Protocol/Ip4Config.h>
  31 #include <Protocol/ComponentName.h>
  32 #include <Protocol/ComponentName2.h>
  33
  34
  35 #define ISCSI_PRIVATE_GUID \
  36   { 0xfa3cde4c, 0x87c2, 0x427d, {0xae, 0xde, 0x7d, 0xd0, 0x96, 0xc8, 0x8c, 0x58} }
  37
  38 #define ISCSI_INITIATOR_NAME_VAR_NAME L"I_NAME"
  39
  40 extern EFI_COMPONENT_NAME2_PROTOCOL       gIScsiComponentName2;
  41 extern EFI_COMPONENT_NAME_PROTOCOL        gIScsiComponentName;
  42
  43
  44 extern EFI_GUID                           mIScsiPrivateGuid;
  45
  46 typedef struct _ISCSI_PRIVATE_PROTOCOL {
  47   UINT32  Reserved;
  48 } ISCSI_PRIVATE_PROTOCOL;
  49
  50 //
  51 // EFI Driver Binding Protocol for iSCSI driver.
  52 //
  53
  54 /**
  55   Tests to see if this driver supports a given controller. If a child device is provided,
  56   it further tests to see if this driver supports creating a handle for the specified child device.
  57
  58   @param  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  59   @param  ControllerHandle     The handle of the controller to test. This handle
  60                                must support a protocol interface that supplies
  61                                an I/O abstraction to the driver.
  62   @param  RemainingDevicePath  A pointer to the remaining portion of a device path.
  63                                This parameter is ignored by device drivers, and is optional for bus drivers.
  64
  65
  66   @retval EFI_SUCCESS         The device specified by ControllerHandle and
  67                               RemainingDevicePath is supported by the driver specified by This.
  68   @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
  69                               RemainingDevicePath is already being managed by the driver
  70                               specified by This.
  71   @retval EFI_ACCESS_DENIED   The device specified by ControllerHandle and
  72                               RemainingDevicePath is already being managed by a different
  73                               driver or an application that requires exclusive acces.
  74                               Currently not implemented.
  75   @retval EFI_UNSUPPORTED     The device specified by ControllerHandle and
  76                               RemainingDevicePath is not supported by the driver specified by This.
  77 **/
  78 EFI_STATUS
  79 EFIAPI
  80 IScsiDriverBindingSupported (
  81   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
  82   IN EFI_HANDLE                   ControllerHandle,
  83   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
  84   );
  85
  86 /**
  87   Start this driver on ControllerHandle. The Start() function is designed to be
  88   invoked from the EFI boot service ConnectController(). As a result, much of
  89   the error checking on the parameters to Start() has been moved into this
  90   common boot service. It is legal to call Start() from other locations,
  91   but the following calling restrictions must be followed or the system behavior will not be deterministic.
  92   1. ControllerHandle must be a valid EFI_HANDLE.
  93   2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
  94      EFI_DEVICE_PATH_PROTOCOL.
  95   3. Prior to calling Start(), the Supported() function for the driver specified by This must
  96      have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
  97
  98   @param  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  99   @param  ControllerHandle     The handle of the controller to start. This handle
 100                                must support a protocol interface that supplies
 101                                an I/O abstraction to the driver.
 102   @param  RemainingDevicePath  A pointer to the remaining portion of a device path.
 103                                This parameter is ignored by device drivers, and is optional for bus drivers.
 104
 105   @retval EFI_SUCCESS          The device was started.
 106   @retval EFI_DEVICE_ERROR     The device could not be started due to a device error.Currently not implemented.
 107   @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
 108   @retval other                The driver failded to start the device.
 109 **/
 110 EFI_STATUS
 111 EFIAPI
 112 IScsiDriverBindingStart (
 113   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 114   IN EFI_HANDLE                   ControllerHandle,
 115   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 116   );
 117
 118 /**
 119   Stop this driver on ControllerHandle.
 120
 121   Release the control of this controller and remove the IScsi functions. The Stop()
 122   function is designed to be invoked from the EFI boot service DisconnectController().
 123   As a result, much of the error checking on the parameters to Stop() has been moved
 124   into this common boot service. It is legal to call Stop() from other locations,
 125   but the following calling restrictions must be followed or the system behavior will not be deterministic.
 126   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
 127      same driver's Start() function.
 128   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
 129      EFI_HANDLE. In addition, all of these handles must have been created in this driver's
 130      Start() function, and the Start() function must have called OpenProtocol() on
 131      ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 132
 133   @param  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 134   @param  ControllerHandle  A handle to the device being stopped. The handle must
 135                             support a bus specific I/O protocol for the driver
 136                             to use to stop the device.
 137   @param  NumberOfChildren  The number of child device handles in ChildHandleBuffer.Not used.
 138   @param  ChildHandleBuffer An array of child handles to be freed. May be NULL
 139                             if NumberOfChildren is 0.Not used.
 140
 141   @retval EFI_SUCCESS       The device was stopped.
 142   @retval EFI_DEVICE_ERROR  The device could not be stopped due to a device error.
 143 **/
 144 EFI_STATUS
 145 EFIAPI
 146 IScsiDriverBindingStop (
 147   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 148   IN EFI_HANDLE                   ControllerHandle,
 149   IN UINTN                        NumberOfChildren,
 150   IN EFI_HANDLE                   *ChildHandleBuffer
 151   );
 152
 153 //
 154 // EFI Component Name Protocol for IScsi driver.
 155 //
 156 /**
 157   Retrieves a Unicode string that is the user readable name of the EFI Driver.
 158
 159   This function retrieves the user readable name of a driver in the form of a
 160   Unicode string. If the driver specified by This has a user readable name in
 161   the language specified by Language, then a pointer to the driver name is
 162   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 163   by This does not support the language specified by Language,
 164   then EFI_UNSUPPORTED is returned.
 165
 166   @param  This[in]              A pointer to the EFI_COMPONENT_NAME_PROTOCOL
 167                                 instance.
 168
 169   @param  Language[in]          A pointer to a three character ISO 639-2 language
 170                                 identifier.
 171                                 This is the language of the driver name that that
 172                                 the caller is requesting, and it must match one of
 173                                 the languages specified in SupportedLanguages.
 174                                 The number of languages supported by a driver is up
 175                                 to the driver writer.
 176
 177   @param  DriverName[out]       A pointer to the Unicode string to return.
 178                                 This Unicode string is the name of the
 179                                 driver specified by This in the language
 180                                 specified by Language.
 181
 182   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 183                                 This and the language specified by Language was
 184                                 returned in DriverName.
 185
 186   @retval EFI_INVALID_PARAMETER Language is NULL.
 187
 188   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 189
 190   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 191                                 the language specified by Language.
 192
 193 **/
 194 EFI_STATUS
 195 EFIAPI
 196 IScsiComponentNameGetDriverName (
 197   IN  EFI_COMPONENT_NAME_PROTOCOL   *This,
 198   IN  CHAR8                         *Language,
 199   OUT CHAR16                        **DriverName
 200   );
 201
 202 /**
 203   Retrieves a Unicode string that is the user readable name of the controller
 204   that is being managed by an EFI Driver.
 205
 206   @param  This[in]              A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.
 207
 208   @param  ControllerHandle[in]  The handle of a controller that the driver specified by
 209                                 This is managing.  This handle specifies the controller
 210                                 whose name is to be returned.
 211
 212   @param  ChildHandle[in]       The handle of the child controller to retrieve the name
 213                                 of.  This is an optional parameter that may be NULL.  It
 214                                 will be NULL for device drivers.  It will also be NULL
 215                                 for a bus drivers that wish to retrieve the name of the
 216                                 bus controller.  It will not be NULL for a bus driver
 217                                 that wishes to retrieve the name of a child controller.
 218
 219   @param  Language[in]          A pointer to a three character ISO 639-2 language
 220                                 identifier.  This is the language of the controller name
 221                                 that that the caller is requesting, and it must match one
 222                                 of the languages specified in SupportedLanguages.  The
 223                                 number of languages supported by a driver is up to the
 224                                 driver writer.
 225
 226   @param  ControllerName[out]   A pointer to the Unicode string to return.  This Unicode
 227                                 string is the name of the controller specified by
 228                                 ControllerHandle and ChildHandle in the language
 229                                 specified by Language from the point of view of the
 230                                 driver specified by This.
 231
 232   @retval EFI_SUCCESS           The Unicode string for the user readable name in the
 233                                 language specified by Language for the driver
 234                                 specified by This was returned in DriverName.
 235
 236   @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
 237
 238   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid EFI_HANDLE.
 239
 240   @retval EFI_INVALID_PARAMETER Language is NULL.
 241
 242   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 243
 244   @retval EFI_UNSUPPORTED       The driver specified by This is not currently managing
 245                                 the controller specified by ControllerHandle and ChildHandle.
 246
 247   @retval EFI_UNSUPPORTED       The driver specified by This does not support the
 248                                 language specified by Language.
 249
 250 **/
 251 EFI_STATUS
 252 EFIAPI
 253 IScsiComponentNameGetControllerName (
 254   IN  EFI_COMPONENT_NAME_PROTOCOL   *This,
 255   IN  EFI_HANDLE                    ControllerHandle,
 256   IN  EFI_HANDLE                    ChildHandle        OPTIONAL,
 257   IN  CHAR8                         *Language,
 258   OUT CHAR16                        **ControllerName
 259   );
 260
 261 #endif