man.bsd.lv manual page server

INITIALISATION

An HBA driver has to allocate and initialize to 0 a struct scsipi_adapter and fill in the following members:

The following callbacks should be provided through the struct scsipi_adapter:

The HBA driver has to allocate and initialize to 0 one struct scsipi_channel per channel and fill in the following members:

The HBA driver attaches the SCSI or ATAPI bus (depending on the setting of chan_bustype) by passing a pointer to the struct scsipi_channel to the autoconf(9) machinery. The print function shall be either scsiprint() or atapiprint().

OTHER DATA STRUCTURES

When scanning the bus, the scsipi system allocates a struct scsipi_periph for each device probed. The interesting fields are:

A SCSI or ATAPI request is passed to the HBA through a struct scsipi_xfer. The HBA driver has access to the following data:

FUNCTIONS AND CALLBACKS

(*adapt_request)(struct scsipi_channel *chan, scsipi_adapter_req_t req, void *arg)

Used by the mid-layer to transmit a request to the adapter. req can be one of:

ADAPTER_REQ_RUN_XFER

request the adapter to send a command to the device. arg is a pointer to the struct scsipi_xfer. Once the xfer is complete the HBA driver shall call scsipi_done() with updated status and error information.

ADAPTER_REQ_GROW_RESOURCES

ask the adapter to increase resources of the channel (grow adapt_openings or chan_openings) if possible. Support of this feature is optional. This request is called from the kernel completion thread. arg must be ignored.

ADAPTER_REQ_SET_XFER_MODE

set the xfer mode for a I_T Nexus. This will be called once all LUNs of a target have been probed. arg points to a struct scsipi_xfer_mode defined as follows:

int xm_target

target for I_T Nexus

int xm_mode

bitmask of device capabilities

int xm_period

sync period

int xm_offset

sync offset

xm_period and xm_offset shall be ignored for ADAPTER_REQ_SET_XFER_MODE. xm_mode holds the following bits:

PERIPH_CAP_SYNC

ST synchronous transfers

PERIPH_CAP_WIDE16

ST 16 bit wide transfers

PERIPH_CAP_WIDE32

ST 32 bit wide transfers

PERIPH_CAP_DT

DT transfers

PERIPH_CAP_TQING

tagged queuing

Whenever the xfer mode changes, the driver should call scsipi_async_event() to notify the mid-layer.

adapt_request() may be called from interrupt context.

adapt_minphys()

pointer to the driver's minphys function. If the driver can handle transfers of size MAXPHYS, this can point to minphys().

adapt_ioctl()

ioctl function for the channel. The only ioctl supported at this level is SCBUSIORESET for which the HBA driver shall issue a SCSI reset on the channel.

int adapt_enable(struct device *dev, int enable)

Disable the adapter if enable is zero, or enable it if non-zero. Returns 0 if operation is successful, or error from <sys/errno.h>. This callback is optional, and is useful mostly for hot-plug devices. For example, this callback would power on or off the relevant PCMCIA socket for a PCMCIA controller. scsipi_adapter_addref() and scsipi_adapter_delref() maintain a reference count, the enable callback is called appropriately for the first reference and the last reference.

int adapt_getgeom(struct scsipi_periph *periph, struct disk_parms *params, u_long sectors)

Optional callback, used by high-level drivers to get the fictitious geometry used by the controller's firmware for the specified periph. Returns 0 if successful. See Adaptec drivers for details.

int adapt_accesschk(struct scsipi_periph *periph, struct scsipi_inquiry_pattern *inqbuf)

Optional callback; if present the mid-layer uses it to check if it can attach a driver to the specified periph. If the callback returns a non-zero value, the periph is ignored by the scsipi code. This callback is used by adapters which want to drive some devices themselves, for example hardware RAID controllers.

scsipi_async_event(struct scsipi_channel *chan, scsipi_async_event_t event, void *arg)

Asynchronous event notification for the mid-layer. event can be one of:

ASYNC_EVENT_MAX_OPENINGS

set max openings for a periph. Argument is a struct scsipi_max_openings with at least the following members:

int mo_target

 

int mo_lun

 

int mo_openings

 

Not all periphs may allow openings to increase; if not allowed the request is silently ignored.

ASYNC_EVENT_XFER_MODE

update the xfer mode for an I_T nexus. Argument is a struct scsipi_xfer_mode properly filled in. An ASYNC_EVENT_XFER_MODE call with PERIPH_CAP_TQING set in xm_mode is mandatory to activate tagged queuing.

ASYNC_EVENT_RESET

channel has been reset. No argument. HBA drivers have to issue ASYNC_EVENT_RESET events if they rely on the mid-layer for SCSI CHECK CONDITION handling.

scsipi_done(struct scsipi_xfer *xs)

shall be called by the HBA when the xfer is complete, or when it needs to be requeued by the mid-layer. error in the scsipi_xfer shall be set to one of the following:

XS_NOERROR

xfer completed without error.

XS_SENSE

Check the returned SCSI sense for the error.

XS_SHORTSENSE

Check the ATAPI sense for the error.

XS_DRIVER_STUFFUP

Driver failed to perform operation.

XS_RESOURCE_SHORTAGE

Adapter resource shortage. The mid-layer will retry the command after some delay.

XS_SELTIMEOUT

The device timed out while trying to send the command

XS_TIMEOUT

The command was accepted by the device, but it didn't complete in allowed time.

XS_BUSY

The mid-layer will check status for additional details:

SCSI_CHECK

SCSI check condition. The mid-layer will freeze the periph queue and issue a REQUEST SENSE command. If the HBA supports tagged queuing, it shall remove and requeue any command not yet accepted by the HBA (or at last make sure no more commands will be sent to the device before the REQUEST SENSE is complete).

SCSI_QUEUE_FULL

The mid layer will adjust the periph's openings and requeue the command.

SCSI_BUSY

The mid-layer will requeue the xfer after delay.

XS_RESET

xfer destroyed by a reset; the mid-layer will requeue it.

XS_REQUEUE

Ask the mid-layer to requeue this command immediately.

The adapter should not reference an xfer once scsipi_done(xfer) has been called, unless the xfer had XS_CTL_POLL set.

scsipi_done() will call the adapt_request() callback again only if called with xs->error set to XS_NOERROR, and xfer doesn't have XS_CTL_POLL set. All other error conditions are handled by a kernel thread (once the HBA's interrupt handler has returned).

scsipi_printaddr(struct scsipi_periph *periph)

print a kernel message with the periph's name, in the form device(controller:channel:target:lun).

scsipi_channel_freeze(struct scsipi_channel *chan, int count)

Freeze the specified channel (requests are queued but not sent to HBA). The channel's freeze counter is increased by count.

scsipi_channel_thaw(struct scsipi_channel *chan, int count)

Decrement the channel's freeze counter by count and process the queue if the counter goes to 0. In order to preserve command ordering, HBA drivers should not call scsipi_channel_thaw() before calling scsipi_done() for all commands in the HBA's queue which need to be requeued.

scsipi_periph_timed_thaw(void *arg)

Call scsipi_channel_thaw(arg, 1). Intended to be used as callout(9) callback.

scsipi_periph_freeze(struct scsipi_periph *periph, int count)

 

scsipi_periph_thaw(struct scsipi_periph *periph)

 

scsipi_periph_timed_thaw(void *arg)

Same as the channel counterparts, but only for one specific peripheral.

scsipi_target_detach(struct scsipi_channel *chan, int target, int lun, int flags)

detach the periph associated with this I_T_L nexus. Both target and lun may be wildcarded using the magic value -1. flags is passed to config_detach() . Returns 0 if successful, or error code if a device couldn't be removed.

scsipi_thread_call_callback(struct scsipi_channel *chan, void (*callback)(struct scsipi_channel *, void *), void *arg)

callback() will be called with chan and arg as arguments, from the channel completion thread. The callback is run at IPL_BIO with the channel lock held. scsipi_thread_call_callback() will freeze the channel by one, it's up to the caller to thaw it when appropriate. Returns 0 if the callback was properly recorded, or EBUSY if the channel has already a callback pending.