MdeModulePkg/Bus/I2c/I2cDxe/I2cDxe.h

   1 /** @file
   2   Private data structures for the I2C DXE driver.
   3
   4   This file defines common data structures, macro definitions and some module
   5   internal function header files.
   6
   7   Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>
   8   This program and the accompanying materials
   9   are licensed and made available under the terms and conditions of the BSD License
  10   which accompanies this distribution.  The full text of the license may be found at
  11   http://opensource.org/licenses/bsd-license.php
  12
  13   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  14   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  15
  16 **/
  17
  18 #ifndef __I2C_DXE_H__
  19 #define __I2C_DXE_H__
  20
  21 #include <Uefi.h>
  22 #include <Library/BaseMemoryLib.h>
  23 #include <Library/DebugLib.h>
  24 #include <Library/DevicePathLib.h>
  25 #include <Library/MemoryAllocationLib.h>
  26 #include <Library/TimerLib.h>
  27 #include <Library/UefiBootServicesTableLib.h>
  28 #include <Library/UefiDriverEntryPoint.h>
  29 #include <Library/UefiLib.h>
  30
  31 #include <Protocol/DriverBinding.h>
  32 #include <Protocol/I2cEnumerate.h>
  33 #include <Protocol/I2cHost.h>
  34 #include <Protocol/I2cIo.h>
  35 #include <Protocol/I2cMaster.h>
  36 #include <Protocol/I2cBusConfigurationManagement.h>
  37 #include <Protocol/LoadedImage.h>
  38
  39 #define I2C_DEVICE_SIGNATURE          SIGNATURE_32 ('I', '2', 'C', 'D')
  40 #define I2C_HOST_SIGNATURE            SIGNATURE_32 ('I', '2', 'C', 'H')
  41 #define I2C_REQUEST_SIGNATURE         SIGNATURE_32 ('I', '2', 'C', 'R')
  42
  43 //
  44 // Synchronize access to the list of requests
  45 //
  46 #define TPL_I2C_SYNC                  TPL_NOTIFY
  47
  48 //
  49 //  I2C bus context
  50 //
  51 typedef struct {
  52   EFI_I2C_ENUMERATE_PROTOCOL       *I2cEnumerate;
  53   EFI_I2C_HOST_PROTOCOL            *I2cHost;
  54   EFI_HANDLE                       Controller;
  55   EFI_DEVICE_PATH_PROTOCOL         *ParentDevicePath;
  56   EFI_HANDLE                       DriverBindingHandle;
  57 } I2C_BUS_CONTEXT;
  58
  59 //
  60 // I2C device context
  61 //
  62 typedef struct {
  63   //
  64   // Structure identification
  65   //
  66   UINT32                        Signature;
  67
  68   //
  69   // I2c device handle
  70   //
  71   EFI_HANDLE                    Handle;
  72
  73   //
  74   // Upper level API to support the I2C device I/O
  75   //
  76   EFI_I2C_IO_PROTOCOL           I2cIo;
  77
  78   //
  79   // Device path for this device
  80   //
  81   EFI_DEVICE_PATH_PROTOCOL      *DevicePath;
  82
  83   //
  84   // Platform specific data for this device
  85   //
  86   CONST EFI_I2C_DEVICE          *I2cDevice;
  87
  88   //
  89   // Context for the common I/O support including the
  90   // lower level API to the host controller.
  91   //
  92   I2C_BUS_CONTEXT               *I2cBusContext;
  93 } I2C_DEVICE_CONTEXT;
  94
  95 #define I2C_DEVICE_CONTEXT_FROM_PROTOCOL(a) CR (a, I2C_DEVICE_CONTEXT, I2cIo, I2C_DEVICE_SIGNATURE)
  96
  97 //
  98 // I2C Request
  99 //
 100 typedef struct {
 101   //
 102   // Signature
 103   //
 104   UINT32                            Signature;
 105
 106   //
 107   // Next request in the pending request list
 108   //
 109   LIST_ENTRY                        Link;
 110
 111   //
 112   // I2C bus configuration for the operation
 113   //
 114   UINTN                             I2cBusConfiguration;
 115
 116   //
 117   // I2C slave address for the operation
 118   //
 119   UINTN                             SlaveAddress;
 120
 121   //
 122   // Event to set for asynchronous operations, NULL for
 123   // synchronous operations
 124   //
 125   EFI_EVENT                         Event;
 126
 127   //
 128   // I2C operation description
 129   //
 130   EFI_I2C_REQUEST_PACKET            *RequestPacket;
 131
 132   //
 133   // Optional buffer to receive the I2C operation completion status
 134   //
 135   EFI_STATUS                        *Status;
 136 } I2C_REQUEST;
 137
 138 #define I2C_REQUEST_FROM_ENTRY(a)         CR (a, I2C_REQUEST, Link, I2C_REQUEST_SIGNATURE);
 139
 140 //
 141 // I2C host context
 142 //
 143 typedef struct {
 144   //
 145   // Structure identification
 146   //
 147   UINTN Signature;
 148
 149   //
 150   // Current I2C bus configuration
 151   //
 152   UINTN I2cBusConfiguration;
 153
 154   //
 155   // I2C bus configuration management event
 156   //
 157   EFI_EVENT I2cBusConfigurationEvent;
 158
 159   //
 160   // I2C operation completion event
 161   //
 162   EFI_EVENT I2cEvent;
 163
 164   //
 165   // I2C operation and I2C bus configuration management status
 166   //
 167   EFI_STATUS Status;
 168
 169   //
 170   // I2C bus configuration management operation pending
 171   //
 172   BOOLEAN I2cBusConfigurationManagementPending;
 173
 174   //
 175   // I2C request list maintained by I2C Host
 176   //
 177   LIST_ENTRY                  RequestList;
 178
 179   //
 180   // Upper level API
 181   //
 182   EFI_I2C_HOST_PROTOCOL       I2cHost;
 183
 184   //
 185   // I2C bus configuration management protocol
 186   //
 187   EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL *I2cBusConfigurationManagement;
 188
 189   //
 190   // Lower level API for I2C master (controller)
 191   //
 192   EFI_I2C_MASTER_PROTOCOL *I2cMaster;
 193 } I2C_HOST_CONTEXT;
 194
 195 #define I2C_HOST_CONTEXT_FROM_PROTOCOL(a) CR (a, I2C_HOST_CONTEXT, I2cHost, I2C_HOST_SIGNATURE)
 196
 197 //
 198 // Global Variables
 199 //
 200 extern EFI_COMPONENT_NAME_PROTOCOL    gI2cBusComponentName;
 201 extern EFI_COMPONENT_NAME2_PROTOCOL   gI2cBusComponentName2;
 202 extern EFI_DRIVER_BINDING_PROTOCOL    gI2cBusDriverBinding;
 203
 204 extern EFI_COMPONENT_NAME_PROTOCOL    gI2cHostComponentName;
 205 extern EFI_COMPONENT_NAME2_PROTOCOL   gI2cHostComponentName2;
 206 extern EFI_DRIVER_BINDING_PROTOCOL    gI2cHostDriverBinding;
 207
 208 /**
 209   Start the I2C driver
 210
 211   This routine allocates the necessary resources for the driver.
 212
 213   This routine is called by I2cBusDriverStart to complete the driver
 214   initialization.
 215
 216   @param[in] I2cBus                   Address of an I2C_BUS_CONTEXT structure
 217   @param[in] Controller               Handle to the controller
 218   @param[in] RemainingDevicePath      A pointer to the remaining portion of a device path.
 219
 220   @retval EFI_SUCCESS                 Driver API properly initialized
 221
 222 **/
 223 EFI_STATUS
 224 RegisterI2cDevice (
 225   IN I2C_BUS_CONTEXT           *I2cBus,
 226   IN EFI_HANDLE                 Controller,
 227   IN EFI_DEVICE_PATH_PROTOCOL  *RemainingDevicePath
 228   );
 229
 230 /**
 231   Unregister an I2C device.
 232
 233   This function removes the protocols installed on the controller handle and
 234   frees the resources allocated for the I2C device.
 235
 236   @param  This                  The pointer to EFI_DRIVER_BINDING_PROTOCOL instance.
 237   @param  Controller            The controller handle of the I2C device.
 238   @param  Handle                The child handle.
 239
 240   @retval EFI_SUCCESS           The I2C device is successfully unregistered.
 241   @return Others                Some error occurs when unregistering the I2C device.
 242
 243 **/
 244 EFI_STATUS
 245 UnRegisterI2cDevice (
 246   IN  EFI_DRIVER_BINDING_PROTOCOL    *This,
 247   IN  EFI_HANDLE                     Controller,
 248   IN  EFI_HANDLE                     Handle
 249   );
 250
 251 /**
 252   Create a path for the I2C device
 253
 254   Append the I2C slave path to the I2C master controller path.
 255
 256   @param[in] I2cDeviceContext           Address of an I2C_DEVICE_CONTEXT structure.
 257   @param[in] BuildControllerNode        Flag to build controller node in device path.
 258
 259   @retval EFI_SUCCESS           The I2C device path is built successfully.
 260   @return Others                It is failed to built device path.
 261
 262 **/
 263 EFI_STATUS
 264 I2cBusDevicePathAppend (
 265   IN I2C_DEVICE_CONTEXT     *I2cDeviceContext,
 266   IN BOOLEAN                BuildControllerNode
 267   );
 268
 269 /**
 270   Queue an I2C transaction for execution on the I2C device.
 271
 272   This routine must be called at or below TPL_NOTIFY.  For synchronous
 273   requests this routine must be called at or below TPL_CALLBACK.
 274
 275   This routine queues an I2C transaction to the I2C controller for
 276   execution on the I2C bus.
 277
 278   When Event is NULL, QueueRequest() operates synchronously and returns
 279   the I2C completion status as its return value.
 280
 281   When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS
 282   indicating that the asynchronous I2C transaction was queued.  The values
 283   above are returned in the buffer pointed to by I2cStatus upon the
 284   completion of the I2C transaction when I2cStatus is not NULL.
 285
 286   The upper layer driver writer provides the following to the platform
 287   vendor:
 288
 289   1.  Vendor specific GUID for the I2C part
 290   2.  Guidance on proper construction of the slave address array when the
 291       I2C device uses more than one slave address.  The I2C bus protocol
 292       uses the SlaveAddressIndex to perform relative to physical address
 293       translation to access the blocks of hardware within the I2C device.
 294
 295   @param[in] This               Pointer to an EFI_I2C_IO_PROTOCOL structure.
 296   @param[in] SlaveAddressIndex  Index value into an array of slave addresses
 297                                 for the I2C device.  The values in the array
 298                                 are specified by the board designer, with the
 299                                 third party I2C device driver writer providing
 300                                 the slave address order.
 301
 302                                 For devices that have a single slave address,
 303                                 this value must be zero.  If the I2C device
 304                                 uses more than one slave address then the
 305                                 third party (upper level) I2C driver writer
 306                                 needs to specify the order of entries in the
 307                                 slave address array.
 308
 309                                 \ref ThirdPartyI2cDrivers "Third Party I2C
 310                                 Drivers" section in I2cMaster.h.
 311   @param[in] Event              Event to signal for asynchronous transactions,
 312                                 NULL for synchronous transactions
 313   @param[in] RequestPacket      Pointer to an EFI_I2C_REQUEST_PACKET structure
 314                                 describing the I2C transaction
 315   @param[out] I2cStatus         Optional buffer to receive the I2C transaction
 316                                 completion status
 317
 318   @retval EFI_SUCCESS           The asynchronous transaction was successfully
 319                                 queued when Event is not NULL.
 320   @retval EFI_SUCCESS           The transaction completed successfully when
 321                                 Event is NULL.
 322   @retval EFI_ABORTED           The request did not complete because the driver
 323                                 binding Stop() routine was called.
 324   @retval EFI_BAD_BUFFER_SIZE   The RequestPacket->LengthInBytes value is too
 325                                 large.
 326   @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the
 327                                 transaction.
 328   @retval EFI_INVALID_PARAMETER RequestPacket is NULL
 329   @retval EFI_NOT_FOUND         Reserved bit set in the SlaveAddress parameter
 330   @retval EFI_NO_MAPPING        The EFI_I2C_HOST_PROTOCOL could not set the
 331                                 bus configuration required to access this I2C
 332                                 device.
 333   @retval EFI_NO_RESPONSE       The I2C device is not responding to the slave
 334                                 address selected by SlaveAddressIndex.
 335                                 EFI_DEVICE_ERROR will be returned if the
 336                                 controller cannot distinguish when the NACK
 337                                 occurred.
 338   @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C transaction
 339   @retval EFI_UNSUPPORTED       The controller does not support the requested
 340                                 transaction.
 341
 342 **/
 343 EFI_STATUS
 344 EFIAPI
 345 I2cBusQueueRequest (
 346   IN CONST EFI_I2C_IO_PROTOCOL  *This,
 347   IN UINTN                      SlaveAddressIndex,
 348   IN EFI_EVENT                  Event               OPTIONAL,
 349   IN EFI_I2C_REQUEST_PACKET     *RequestPacket,
 350   OUT EFI_STATUS                *I2cStatus          OPTIONAL
 351   );
 352
 353 /**
 354   Tests to see if this driver supports a given controller. If a child device is provided,
 355   it further tests to see if this driver supports creating a handle for the specified child device.
 356
 357   This function checks to see if the driver specified by This supports the device specified by
 358   ControllerHandle. Drivers will typically use the device path attached to
 359   ControllerHandle and/or the services from the bus I/O abstraction attached to
 360   ControllerHandle to determine if the driver supports ControllerHandle. This function
 361   may be called many times during platform initialization. In order to reduce boot times, the tests
 362   performed by this function must be very small, and take as little time as possible to execute. This
 363   function must not change the state of any hardware devices, and this function must be aware that the
 364   device specified by ControllerHandle may already be managed by the same driver or a
 365   different driver. This function must match its calls to AllocatePages() with FreePages(),
 366   AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
 367   Since ControllerHandle may have been previously started by the same driver, if a protocol is
 368   already in the opened state, then it must not be closed with CloseProtocol(). This is required
 369   to guarantee the state of ControllerHandle is not modified by this function.
 370
 371   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 372   @param[in]  ControllerHandle     The handle of the controller to test. This handle
 373                                    must support a protocol interface that supplies
 374                                    an I/O abstraction to the driver.
 375   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 376                                    parameter is ignored by device drivers, and is optional for bus
 377                                    drivers. For bus drivers, if this parameter is not NULL, then
 378                                    the bus driver must determine if the bus controller specified
 379                                    by ControllerHandle and the child controller specified
 380                                    by RemainingDevicePath are both supported by this
 381                                    bus driver.
 382
 383   @retval EFI_SUCCESS              The device specified by ControllerHandle and
 384                                    RemainingDevicePath is supported by the driver specified by This.
 385   @retval EFI_ALREADY_STARTED      The device specified by ControllerHandle and
 386                                    RemainingDevicePath is already being managed by the driver
 387                                    specified by This.
 388   @retval EFI_ACCESS_DENIED        The device specified by ControllerHandle and
 389                                    RemainingDevicePath is already being managed by a different
 390                                    driver or an application that requires exclusive access.
 391                                    Currently not implemented.
 392   @retval EFI_UNSUPPORTED          The device specified by ControllerHandle and
 393                                    RemainingDevicePath is not supported by the driver specified by This.
 394 **/
 395 EFI_STATUS
 396 EFIAPI
 397 I2cBusDriverSupported (
 398   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 399   IN EFI_HANDLE                   Controller,
 400   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 401   );
 402
 403 /**
 404   Starts a device controller or a bus controller.
 405
 406   The Start() function is designed to be invoked from the EFI boot service ConnectController().
 407   As a result, much of the error checking on the parameters to Start() has been moved into this
 408   common boot service. It is legal to call Start() from other locations,
 409   but the following calling restrictions must be followed or the system behavior will not be deterministic.
 410   1. ControllerHandle must be a valid EFI_HANDLE.
 411   2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
 412      EFI_DEVICE_PATH_PROTOCOL.
 413   3. Prior to calling Start(), the Supported() function for the driver specified by This must
 414      have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
 415
 416   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 417   @param[in]  ControllerHandle     The handle of the controller to start. This handle
 418                                    must support a protocol interface that supplies
 419                                    an I/O abstraction to the driver.
 420   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 421                                    parameter is ignored by device drivers, and is optional for bus
 422                                    drivers. For a bus driver, if this parameter is NULL, then handles
 423                                    for all the children of Controller are created by this driver.
 424                                    If this parameter is not NULL and the first Device Path Node is
 425                                    not the End of Device Path Node, then only the handle for the
 426                                    child device specified by the first Device Path Node of
 427                                    RemainingDevicePath is created by this driver.
 428                                    If the first Device Path Node of RemainingDevicePath is
 429                                    the End of Device Path Node, no child handle is created by this
 430                                    driver.
 431
 432   @retval EFI_SUCCESS              The device was started.
 433   @retval EFI_DEVICE_ERROR         The device could not be started due to a device error.Currently not implemented.
 434   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.
 435   @retval Others                   The driver failded to start the device.
 436
 437 **/
 438 EFI_STATUS
 439 EFIAPI
 440 I2cBusDriverStart (
 441   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 442   IN EFI_HANDLE                   Controller,
 443   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 444   );
 445
 446 /**
 447   Stops a device controller or a bus controller.
 448
 449   The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
 450   As a result, much of the error checking on the parameters to Stop() has been moved
 451   into this common boot service. It is legal to call Stop() from other locations,
 452   but the following calling restrictions must be followed or the system behavior will not be deterministic.
 453   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
 454      same driver's Start() function.
 455   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
 456      EFI_HANDLE. In addition, all of these handles must have been created in this driver's
 457      Start() function, and the Start() function must have called OpenProtocol() on
 458      ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 459
 460   @param[in]  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 461   @param[in]  ControllerHandle  A handle to the device being stopped. The handle must
 462                                 support a bus specific I/O protocol for the driver
 463                                 to use to stop the device.
 464   @param[in]  NumberOfChildren  The number of child device handles in ChildHandleBuffer.
 465   @param[in]  ChildHandleBuffer An array of child handles to be freed. May be NULL
 466                                 if NumberOfChildren is 0.
 467
 468   @retval EFI_SUCCESS           The device was stopped.
 469   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 470
 471 **/
 472 EFI_STATUS
 473 EFIAPI
 474 I2cBusDriverStop (
 475   IN  EFI_DRIVER_BINDING_PROTOCOL  *This,
 476   IN  EFI_HANDLE                   Controller,
 477   IN  UINTN                        NumberOfChildren,
 478   IN  EFI_HANDLE                   *ChildHandleBuffer
 479   );
 480
 481 /**
 482   Retrieves a Unicode string that is the user readable name of the driver.
 483
 484   This function retrieves the user readable name of a driver in the form of a
 485   Unicode string. If the driver specified by This has a user readable name in
 486   the language specified by Language, then a pointer to the driver name is
 487   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 488   by This does not support the language specified by Language,
 489   then EFI_UNSUPPORTED is returned.
 490
 491   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 492                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 493
 494   @param  Language[in]          A pointer to a Null-terminated ASCII string
 495                                 array indicating the language. This is the
 496                                 language of the driver name that the caller is
 497                                 requesting, and it must match one of the
 498                                 languages specified in SupportedLanguages. The
 499                                 number of languages supported by a driver is up
 500                                 to the driver writer. Language is specified
 501                                 in RFC 4646 or ISO 639-2 language code format.
 502
 503   @param  DriverName[out]       A pointer to the Unicode string to return.
 504                                 This Unicode string is the name of the
 505                                 driver specified by This in the language
 506                                 specified by Language.
 507
 508   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 509                                 This and the language specified by Language was
 510                                 returned in DriverName.
 511
 512   @retval EFI_INVALID_PARAMETER Language is NULL.
 513
 514   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 515
 516   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 517                                 the language specified by Language.
 518
 519 **/
 520 EFI_STATUS
 521 EFIAPI
 522 I2cBusComponentNameGetDriverName (
 523   IN  EFI_COMPONENT_NAME2_PROTOCOL *This,
 524   IN  CHAR8                        *Language,
 525   OUT CHAR16                       **DriverName
 526   );
 527
 528 /**
 529   Retrieves a Unicode string that is the user readable name of the controller
 530   that is being managed by a driver.
 531
 532   This function retrieves the user readable name of the controller specified by
 533   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 534   driver specified by This has a user readable name in the language specified by
 535   Language, then a pointer to the controller name is returned in ControllerName,
 536   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 537   managing the controller specified by ControllerHandle and ChildHandle,
 538   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 539   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 540
 541   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 542                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 543
 544   @param  ControllerHandle[in]  The handle of a controller that the driver
 545                                 specified by This is managing.  This handle
 546                                 specifies the controller whose name is to be
 547                                 returned.
 548
 549   @param  ChildHandle[in]       The handle of the child controller to retrieve
 550                                 the name of.  This is an optional parameter that
 551                                 may be NULL.  It will be NULL for device
 552                                 drivers.  It will also be NULL for a bus drivers
 553                                 that wish to retrieve the name of the bus
 554                                 controller.  It will not be NULL for a bus
 555                                 driver that wishes to retrieve the name of a
 556                                 child controller.
 557
 558   @param  Language[in]          A pointer to a Null-terminated ASCII string
 559                                 array indicating the language.  This is the
 560                                 language of the driver name that the caller is
 561                                 requesting, and it must match one of the
 562                                 languages specified in SupportedLanguages. The
 563                                 number of languages supported by a driver is up
 564                                 to the driver writer. Language is specified in
 565                                 RFC 4646 or ISO 639-2 language code format.
 566
 567   @param  ControllerName[out]   A pointer to the Unicode string to return.
 568                                 This Unicode string is the name of the
 569                                 controller specified by ControllerHandle and
 570                                 ChildHandle in the language specified by
 571                                 Language from the point of view of the driver
 572                                 specified by This.
 573
 574   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 575                                 the language specified by Language for the
 576                                 driver specified by This was returned in
 577                                 DriverName.
 578
 579   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 580
 581   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 582                                 EFI_HANDLE.
 583
 584   @retval EFI_INVALID_PARAMETER Language is NULL.
 585
 586   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 587
 588   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 589                                 managing the controller specified by
 590                                 ControllerHandle and ChildHandle.
 591
 592   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 593                                 the language specified by Language.
 594
 595 **/
 596 EFI_STATUS
 597 EFIAPI
 598 I2cBusComponentNameGetControllerName (
 599   IN  EFI_COMPONENT_NAME2_PROTOCOL                    *This,
 600   IN  EFI_HANDLE                                      ControllerHandle,
 601   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 602   IN  CHAR8                                           *Language,
 603   OUT CHAR16                                          **ControllerName
 604   );
 605
 606 /**
 607   The user entry point for the I2C bus module. The user code starts with
 608   this function.
 609
 610   @param[in] ImageHandle    The firmware allocated handle for the EFI image.
 611   @param[in] SystemTable    A pointer to the EFI System Table.
 612
 613   @retval EFI_SUCCESS       The entry point is executed successfully.
 614   @retval other             Some error occurs when executing this entry point.
 615
 616 **/
 617 EFI_STATUS
 618 EFIAPI
 619 InitializeI2cBus(
 620   IN EFI_HANDLE           ImageHandle,
 621   IN EFI_SYSTEM_TABLE     *SystemTable
 622   );
 623
 624 /**
 625   This is the unload handle for I2C bus module.
 626
 627   Disconnect the driver specified by ImageHandle from all the devices in the handle database.
 628   Uninstall all the protocols installed in the driver entry point.
 629
 630   @param[in] ImageHandle           The drivers' driver image.
 631
 632   @retval    EFI_SUCCESS           The image is unloaded.
 633   @retval    Others                Failed to unload the image.
 634
 635 **/
 636 EFI_STATUS
 637 EFIAPI
 638 I2cBusUnload (
 639   IN EFI_HANDLE             ImageHandle
 640   );
 641
 642 /**
 643   Release all the resources allocated for the I2C device.
 644
 645   This function releases all the resources allocated for the I2C device.
 646
 647   @param  I2cDeviceContext         The I2C child device involved for the operation.
 648
 649 **/
 650 VOID
 651 ReleaseI2cDeviceContext (
 652   IN I2C_DEVICE_CONTEXT          *I2cDeviceContext
 653   );
 654
 655 /**
 656   Complete the current request
 657
 658   @param[in] I2cHost  Address of an I2C_HOST_CONTEXT structure.
 659   @param[in] Status   Status of the I<sub>2</sub>C operation.
 660
 661   @return This routine returns the input status value.
 662
 663 **/
 664 EFI_STATUS
 665 I2cHostRequestComplete (
 666   I2C_HOST_CONTEXT *I2cHost,
 667   EFI_STATUS       Status
 668   );
 669
 670 /**
 671   Enable access to the I2C bus configuration
 672
 673   @param[in] I2cHostContext     Address of an I2C_HOST_CONTEXT structure
 674
 675   @retval EFI_SUCCESS           The operation completed successfully.
 676   @retval EFI_ABORTED           The request did not complete because the driver
 677                                 was shutdown.
 678   @retval EFI_BAD_BUFFER_SIZE   The WriteBytes or ReadBytes buffer size is too large.
 679   @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the operation.
 680                                 This could indicate the slave device is not present.
 681   @retval EFI_INVALID_PARAMETER RequestPacket is NULL
 682   @retval EFI_NO_MAPPING        Invalid I2cBusConfiguration value
 683   @retval EFI_NO_RESPONSE       The I2C device is not responding to the
 684                                 slave address.  EFI_DEVICE_ERROR may also be
 685                                 returned if the controller can not distinguish
 686                                 when the NACK occurred.
 687   @retval EFI_NOT_FOUND         I2C slave address exceeds maximum address
 688   @retval EFI_NOT_READY         I2C bus is busy or operation pending, wait for
 689                                 the event and then read status.
 690   @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C operation
 691   @retval EFI_TIMEOUT           The transaction did not complete within an internally
 692                                 specified timeout period.
 693
 694 **/
 695 EFI_STATUS
 696 I2cHostRequestEnable (
 697   I2C_HOST_CONTEXT *I2cHost
 698   );
 699
 700 /**
 701   Tests to see if this driver supports a given controller. If a child device is provided,
 702   it further tests to see if this driver supports creating a handle for the specified child device.
 703
 704   This function checks to see if the driver specified by This supports the device specified by
 705   ControllerHandle. Drivers will typically use the device path attached to
 706   ControllerHandle and/or the services from the bus I/O abstraction attached to
 707   ControllerHandle to determine if the driver supports ControllerHandle. This function
 708   may be called many times during platform initialization. In order to reduce boot times, the tests
 709   performed by this function must be very small, and take as little time as possible to execute. This
 710   function must not change the state of any hardware devices, and this function must be aware that the
 711   device specified by ControllerHandle may already be managed by the same driver or a
 712   different driver. This function must match its calls to AllocatePages() with FreePages(),
 713   AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
 714   Since ControllerHandle may have been previously started by the same driver, if a protocol is
 715   already in the opened state, then it must not be closed with CloseProtocol(). This is required
 716   to guarantee the state of ControllerHandle is not modified by this function.
 717
 718   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 719   @param[in]  ControllerHandle     The handle of the controller to test. This handle
 720                                    must support a protocol interface that supplies
 721                                    an I/O abstraction to the driver.
 722   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 723                                    parameter is ignored by device drivers, and is optional for bus
 724                                    drivers. For bus drivers, if this parameter is not NULL, then
 725                                    the bus driver must determine if the bus controller specified
 726                                    by ControllerHandle and the child controller specified
 727                                    by RemainingDevicePath are both supported by this
 728                                    bus driver.
 729
 730   @retval EFI_SUCCESS              The device specified by ControllerHandle and
 731                                    RemainingDevicePath is supported by the driver specified by This.
 732   @retval EFI_ALREADY_STARTED      The device specified by ControllerHandle and
 733                                    RemainingDevicePath is already being managed by the driver
 734                                    specified by This.
 735   @retval EFI_ACCESS_DENIED        The device specified by ControllerHandle and
 736                                    RemainingDevicePath is already being managed by a different
 737                                    driver or an application that requires exclusive access.
 738                                    Currently not implemented.
 739   @retval EFI_UNSUPPORTED          The device specified by ControllerHandle and
 740                                    RemainingDevicePath is not supported by the driver specified by This.
 741 **/
 742 EFI_STATUS
 743 EFIAPI
 744 I2cHostDriverSupported (
 745   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 746   IN EFI_HANDLE                   Controller,
 747   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 748   );
 749
 750 /**
 751   Starts a device controller or a bus controller.
 752
 753   The Start() function is designed to be invoked from the EFI boot service ConnectController().
 754   As a result, much of the error checking on the parameters to Start() has been moved into this
 755   common boot service. It is legal to call Start() from other locations,
 756   but the following calling restrictions must be followed, or the system behavior will not be deterministic.
 757   1. ControllerHandle must be a valid EFI_HANDLE.
 758   2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
 759      EFI_DEVICE_PATH_PROTOCOL.
 760   3. Prior to calling Start(), the Supported() function for the driver specified by This must
 761      have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
 762
 763   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 764   @param[in]  ControllerHandle     The handle of the controller to start. This handle
 765                                    must support a protocol interface that supplies
 766                                    an I/O abstraction to the driver.
 767   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 768                                    parameter is ignored by device drivers, and is optional for bus
 769                                    drivers. For a bus driver, if this parameter is NULL, then handles
 770                                    for all the children of Controller are created by this driver.
 771                                    If this parameter is not NULL and the first Device Path Node is
 772                                    not the End of Device Path Node, then only the handle for the
 773                                    child device specified by the first Device Path Node of
 774                                    RemainingDevicePath is created by this driver.
 775                                    If the first Device Path Node of RemainingDevicePath is
 776                                    the End of Device Path Node, no child handle is created by this
 777                                    driver.
 778
 779   @retval EFI_SUCCESS              The device was started.
 780   @retval EFI_DEVICE_ERROR         The device could not be started due to a device error.Currently not implemented.
 781   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.
 782   @retval Others                   The driver failded to start the device.
 783
 784 **/
 785 EFI_STATUS
 786 EFIAPI
 787 I2cHostDriverStart (
 788   IN EFI_DRIVER_BINDING_PROTOCOL        *This,
 789   IN EFI_HANDLE                         Controller,
 790   IN EFI_DEVICE_PATH_PROTOCOL           *RemainingDevicePath
 791   );
 792
 793 /**
 794   Stops a device controller or a bus controller.
 795
 796   The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
 797   As a result, much of the error checking on the parameters to Stop() has been moved
 798   into this common boot service. It is legal to call Stop() from other locations,
 799   but the following calling restrictions must be followed, or the system behavior will not be deterministic.
 800   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
 801      same driver's Start() function.
 802   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
 803      EFI_HANDLE. In addition, all of these handles must have been created in this driver's
 804      Start() function, and the Start() function must have called OpenProtocol() on
 805      ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 806
 807   @param[in]  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 808   @param[in]  ControllerHandle  A handle to the device being stopped. The handle must
 809                                 support a bus specific I/O protocol for the driver
 810                                 to use to stop the device.
 811   @param[in]  NumberOfChildren  The number of child device handles in ChildHandleBuffer.
 812   @param[in]  ChildHandleBuffer An array of child handles to be freed. May be NULL
 813                                 if NumberOfChildren is 0.
 814
 815   @retval EFI_SUCCESS           The device was stopped.
 816   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 817
 818 **/
 819 EFI_STATUS
 820 EFIAPI
 821 I2cHostDriverStop (
 822   IN  EFI_DRIVER_BINDING_PROTOCOL       *This,
 823   IN  EFI_HANDLE                        Controller,
 824   IN  UINTN                             NumberOfChildren,
 825   IN  EFI_HANDLE                        *ChildHandleBuffer
 826   );
 827
 828 /**
 829   Retrieves a Unicode string that is the user readable name of the driver.
 830
 831   This function retrieves the user readable name of a driver in the form of a
 832   Unicode string. If the driver specified by This has a user readable name in
 833   the language specified by Language, then a pointer to the driver name is
 834   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 835   by This does not support the language specified by Language,
 836   then EFI_UNSUPPORTED is returned.
 837
 838   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 839                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 840
 841   @param  Language[in]          A pointer to a Null-terminated ASCII string
 842                                 array indicating the language. This is the
 843                                 language of the driver name that the caller is
 844                                 requesting, and it must match one of the
 845                                 languages specified in SupportedLanguages. The
 846                                 number of languages supported by a driver is up
 847                                 to the driver writer. Language is specified
 848                                 in RFC 4646 or ISO 639-2 language code format.
 849
 850   @param  DriverName[out]       A pointer to the Unicode string to return.
 851                                 This Unicode string is the name of the
 852                                 driver specified by This in the language
 853                                 specified by Language.
 854
 855   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 856                                 This and the language specified by Language was
 857                                 returned in DriverName.
 858
 859   @retval EFI_INVALID_PARAMETER Language is NULL.
 860
 861   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 862
 863   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 864                                 the language specified by Language.
 865
 866 **/
 867 EFI_STATUS
 868 EFIAPI
 869 I2cHostComponentNameGetDriverName (
 870   IN  EFI_COMPONENT_NAME2_PROTOCOL *This,
 871   IN  CHAR8                        *Language,
 872   OUT CHAR16                       **DriverName
 873   );
 874
 875 /**
 876   Retrieves a Unicode string that is the user readable name of the controller
 877   that is being managed by a driver.
 878
 879   This function retrieves the user readable name of the controller specified by
 880   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 881   driver specified by This has a user readable name in the language specified by
 882   Language, then a pointer to the controller name is returned in ControllerName,
 883   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 884   managing the controller specified by ControllerHandle and ChildHandle,
 885   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 886   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 887
 888   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 889                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 890
 891   @param  ControllerHandle[in]  The handle of a controller that the driver
 892                                 specified by This is managing.  This handle
 893                                 specifies the controller whose name is to be
 894                                 returned.
 895
 896   @param  ChildHandle[in]       The handle of the child controller to retrieve
 897                                 the name of.  This is an optional parameter that
 898                                 may be NULL.  It will be NULL for device
 899                                 drivers.  It will also be NULL for a bus drivers
 900                                 that wish to retrieve the name of the bus
 901                                 controller.  It will not be NULL for a bus
 902                                 driver that wishes to retrieve the name of a
 903                                 child controller.
 904
 905   @param  Language[in]          A pointer to a Null-terminated ASCII string
 906                                 array indicating the language.  This is the
 907                                 language of the driver name that the caller is
 908                                 requesting, and it must match one of the
 909                                 languages specified in SupportedLanguages. The
 910                                 number of languages supported by a driver is up
 911                                 to the driver writer. Language is specified in
 912                                 RFC 4646 or ISO 639-2 language code format.
 913
 914   @param  ControllerName[out]   A pointer to the Unicode string to return.
 915                                 This Unicode string is the name of the
 916                                 controller specified by ControllerHandle and
 917                                 ChildHandle in the language specified by
 918                                 Language from the point of view of the driver
 919                                 specified by This.
 920
 921   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 922                                 the language specified by Language for the
 923                                 driver specified by This was returned in
 924                                 DriverName.
 925
 926   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 927
 928   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 929                                 EFI_HANDLE.
 930
 931   @retval EFI_INVALID_PARAMETER Language is NULL.
 932
 933   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 934
 935   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 936                                 managing the controller specified by
 937                                 ControllerHandle and ChildHandle.
 938
 939   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 940                                 the language specified by Language.
 941
 942 **/
 943 EFI_STATUS
 944 EFIAPI
 945 I2cHostComponentNameGetControllerName (
 946   IN  EFI_COMPONENT_NAME2_PROTOCOL                    *This,
 947   IN  EFI_HANDLE                                      ControllerHandle,
 948   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 949   IN  CHAR8                                           *Language,
 950   OUT CHAR16                                          **ControllerName
 951   );
 952
 953 /**
 954   Handle the bus available event
 955
 956   This routine is called at TPL_I2C_SYNC.
 957
 958   @param[in] Event    Address of an EFI_EVENT handle
 959   @param[in] Context  Address of an I2C_HOST_CONTEXT structure
 960
 961 **/
 962 VOID
 963 EFIAPI
 964 I2cHostRequestCompleteEvent (
 965   IN EFI_EVENT Event,
 966   IN VOID *Context
 967   );
 968
 969 /**
 970   Handle the I2C bus configuration available event
 971
 972   This routine is called at TPL_I2C_SYNC.
 973
 974   @param[in] Event    Address of an EFI_EVENT handle
 975   @param[in] Context  Address of an I2C_HOST_CONTEXT structure
 976
 977 **/
 978 VOID
 979 EFIAPI
 980 I2cHostI2cBusConfigurationAvailable (
 981   IN EFI_EVENT Event,
 982   IN VOID *Context
 983   );
 984
 985 /**
 986   Queue an I2C operation for execution on the I2C controller.
 987
 988   This routine must be called at or below TPL_NOTIFY.  For synchronous
 989   requests this routine must be called at or below TPL_CALLBACK.
 990
 991   N.B. The typical consumers of this API are the I2C bus driver and
 992   on rare occasions the I2C test application.  Extreme care must be
 993   taken by other consumers of this API to prevent confusing the
 994   third party I2C drivers due to a state change at the I2C device
 995   which the third party I2C drivers did not initiate.  I2C platform
 996   drivers may use this API within these guidelines.
 997
 998   This layer uses the concept of I2C bus configurations to describe
 999   the I2C bus.  An I2C bus configuration is defined as a unique
1000   setting of the multiplexers and switches in the I2C bus which
1001   enable access to one or more I2C devices.  When using a switch
1002   to divide a bus, due to speed differences, the I2C platform layer
1003   would define an I2C bus configuration for the I2C devices on each
1004   side of the switch.  When using a multiplexer, the I2C platform
1005   layer defines an I2C bus configuration for each of the selector
1006   values required to control the multiplexer.  See Figure 1 in the
1007   <a href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I<sup>2</sup>C
1008   Specification</a> for a complex I2C bus configuration.
1009
1010   The I2C host driver processes all operations in FIFO order.  Prior to
1011   performing the operation, the I2C host driver calls the I2C platform
1012   driver to reconfigure the switches and multiplexers in the I2C bus
1013   enabling access to the specified I2C device.  The I2C platform driver
1014   also selects the maximum bus speed for the device.  After the I2C bus
1015   is configured, the I2C host driver calls the I2C port driver to
1016   initialize the I2C controller and start the I2C operation.
1017
1018   @param[in] This             Address of an EFI_I2C_HOST_PROTOCOL instance.
1019   @param[in] I2cBusConfiguration  I2C bus configuration to access the I2C
1020                                   device.
1021   @param[in] SlaveAddress     Address of the device on the I2C bus.
1022   @param[in] Event            Event to set for asynchronous operations,
1023                               NULL for synchronous operations
1024   @param[in] RequestPacket    Address of an EFI_I2C_REQUEST_PACKET
1025                               structure describing the I2C operation
1026   @param[out] I2cStatus       Optional buffer to receive the I2C operation
1027                               completion status
1028
1029   @retval EFI_SUCCESS           The operation completed successfully.
1030   @retval EFI_ABORTED           The request did not complete because the driver
1031                                 was shutdown.
1032   @retval EFI_BAD_BUFFER_SIZE   The WriteBytes or ReadBytes buffer size is too large.
1033   @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the operation.
1034                                 This could indicate the slave device is not present.
1035   @retval EFI_INVALID_PARAMETER RequestPacket is NULL
1036   @retval EFI_INVALID_PARAMETER TPL is too high
1037   @retval EFI_NO_MAPPING        Invalid I2cBusConfiguration value
1038   @retval EFI_NO_RESPONSE       The I2C device is not responding to the
1039                                 slave address.  EFI_DEVICE_ERROR may also be
1040                                 returned if the controller can not distinguish
1041                                 when the NACK occurred.
1042   @retval EFI_NOT_FOUND         I2C slave address exceeds maximum address
1043   @retval EFI_NOT_READY         I2C bus is busy or operation pending, wait for
1044                                 the event and then read status pointed to by
1045                                 the request packet.
1046   @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C operation
1047   @retval EFI_TIMEOUT           The transaction did not complete within an internally
1048                                 specified timeout period.
1049
1050 **/
1051 EFI_STATUS
1052 EFIAPI
1053 I2cHostQueueRequest (
1054   IN CONST EFI_I2C_HOST_PROTOCOL  *This,
1055   IN UINTN                        I2cBusConfiguration,
1056   IN UINTN                        SlaveAddress,
1057   IN EFI_EVENT                    Event            OPTIONAL,
1058   IN EFI_I2C_REQUEST_PACKET       *RequestPacket,
1059   OUT EFI_STATUS                  *I2cStatus       OPTIONAL
1060   );
1061
1062 /**
1063   The user Entry Point for I2C host module. The user code starts with this function.
1064
1065   @param[in] ImageHandle    The firmware allocated handle for the EFI image.
1066   @param[in] SystemTable    A pointer to the EFI System Table.
1067
1068   @retval EFI_SUCCESS       The entry point is executed successfully.
1069   @retval other             Some error occurs when executing this entry point.
1070
1071 **/
1072 EFI_STATUS
1073 EFIAPI
1074 InitializeI2cHost(
1075   IN EFI_HANDLE           ImageHandle,
1076   IN EFI_SYSTEM_TABLE     *SystemTable
1077   );
1078
1079 /**
1080   This is the unload handle for I2C host module.
1081
1082   Disconnect the driver specified by ImageHandle from all the devices in the handle database.
1083   Uninstall all the protocols installed in the driver entry point.
1084
1085   @param[in] ImageHandle           The drivers' driver image.
1086
1087   @retval    EFI_SUCCESS           The image is unloaded.
1088   @retval    Others                Failed to unload the image.
1089
1090 **/
1091 EFI_STATUS
1092 EFIAPI
1093 I2cHostUnload (
1094   IN EFI_HANDLE             ImageHandle
1095   );
1096
1097 #endif  //  __I2C_DXE_H__