Emulex Logo
OneCore™ Storage SDK Release 11.2
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SLI-4 APIs
iSCSI SLI-4

iSCSI SLI-4

The iSCSI SLI-4 component implements the commands and processing defined by the SLI-4 Architecture Specification and the SLI-4 iSCSI Command Reference through a lightly-abstracted API. The primary objective of this component is to provide a mechanism to access the Emulex SLI-4 hardware without enforcing a specific policy.

All meaningful communication between the driver and hardware occurs via queues. To issue commands and work requests to the hardware, the driver writes work queue entries (WQEs). Conversely, to get information about asynchronous events (for example, link events or previously submitted commands), the driver reads queue entries created by the hardware. The SLI component defines a set of common queue operations used to interact with the hardware, simplifying some of the underlying interface complexities. You can use the queue API to perform the following operations:
  • Allocating a queue type with the given number of entries. Since most queues are closely coupled to an associated queue (for example, a completion queue is tied to an event queue), this interface allows specifying the associated queue.
  • Freeing a previously-allocated queue.
  • Determining if the next queue entry is valid (that is, the hardware has written a new entry).
  • Reading the next valid entry from the queue to a supplied buffer.
  • Writing an entry from a supplied buffer to the next available queue location.
The SLI-4 documentation defines registers that are predominantly used in conjunction with the previously mentioned queue operations. One exception to this characterization of SLI-4 registers is the bootstrap mailbox register (bmbx). The bootstrap mailbox register allows the driver to send commands before any of the other queues exist. Similar to the standard queue operations, the SLI component encapsulates the standard mechanism used to communicate via the bootstrap mailbox.

The OneCore Storage driver writes two types of queue entries: commands and I/O work requests. In both cases, the SLI-4 component provides helper functions to correctly format these queue entries.

The basic format of the command helper functions includes:
  • A name corresponding to the SLI-4 documentation. For example, the helper function for the FW_INITIALIZE mailbox command is sli_cmd_fw_initialize().
  • A buffer to hold the formatted queue entry.
  • The size of the allocated buffer.
  • Parameter options, where appropriate. For example, the ISCSI_TCP_DISCONNECT command requires a value for the connection handle. Therefore, the sli_cmd_iscsi_tcp_disconnect function provides an additional parameter to supply the value.
The basic format of the I/O work request helper functions follow a similar format, and includes:
  • A name corresponding to the SLI-4 documentation. For example, the helper function to create an INITIATOR_WRITE_COMMAND WQE is sli_be3_wqe_ini_write().
  • A buffer to hold the formatted queue entry.
  • The size of the allocated buffer.
  • Parameterized command options where appropriate. For example, the INITIATOR_WRITE_COMMAND WQE requires values for the LUN, expected transfer length, and so on. Therefore, the sli_be3_wqe_ini_write function has additional parameters for these fields.
Once formatted with a helper function, the queue entry can be passed to sli_queue_write() to post it to the hardware.

Note: The formatted command buffers may also be passed to the hardware through the bootstrap mailbox interface (sli_bmbx_command()).

The SLI-4 component provides assistance in decoding entries created by the hardware and read by the driver. In some cases, a SLI-4 function receives the raw buffer as input, and then returns more relevant values. For example, the sli_cq_parse() function receives the completion queue entry as input, and then returns the completion type and queue ID. In other cases, the parsing function decodes the queue entry, and then returns the results through registered callback functions. For example, the sli_cqe_async() helper function decodes asynchronous events, such as link events The drivers can register callback functions for each of these events using the SLI component.

In contrast to SLI-2 and SLI-3 drivers, SLI-4 drivers play a greater role in the allocation and assignment of hardware resources (for example, XRI, RPI, and VPI). However, the inner workings of these resources differ between different hardware. The SLI-4 component encapsulates these differences and presents a common interface to upper layers. The API presents a simple allocate or free interface.

The SLI-4 Architecture Specification covers a range of hardware, each with different capabilities. The SLI component API provides functions to manage these differences. These functions allow drivers to query hardware capabilities (for example, the maximum SGL length), as well as configure capabilities (for example, setting the maximum number of connections or I/O objects).