SVR5

biostart(D2)

biostart -- start an I/O transfer

Synopsis

   #include <sys/ddi.h>
   
   void prefixbiostart(void *idata, channel_t channel, buf_t *bp);

Description

The driver's biostart( ) entry point routine is called to begin an asynchronous I/O transfer for a non-STREAMS device. The buf(D4) buffer header structure describes the details of the I/O request, contains a reference to the actual transfer data buffer, and provides a place for the driver to maintain state information during the I/O processing.

Arguments

idata: For hardware drivers, a pointer to the device-specific instance data as output by the CFG_ADD subfunction of the config(D2) entry point routine. See ``Device instance'' in HDK Technical Reference.
channel: Channel number used to select subcomponents and/or operating modes of this device instance. See ``Channel number'' in HDK Technical Reference.
bp: Pointer to the buf(D4) buffer header structure.

Return values

None.

Usage

This entry point routine is required and used only for non-STREAMS drivers. All read/write I/O requests come through this entry point. It is only called when the device is open.

The I/O request described by bp and the associated physical data buffer are guaranteed to meet the constraints required by the driver for this device instance. The driver informs the core kernel of its buffer constraints with the DI_RBCBP (for B_READ requests) and DI_WBCBP (for B_WRITE requests) subfunctions of the devinfo(D2) entry point routine.

The starting device offset for the I/O transfer is given by the bp->b_blkno and bp->b_blkoff members of the buf(D4) structure and is guaranteed to be non-negative. The number of bytes to transfer is given by the bp->b_bcount member. If the driver informs the core kernel of its device's size with the DI_SIZE subfunction of the devinfo(D2) routine, the device offset range is guaranteed not to extend beyond the end of the device.

If the driver does not report its device's size, the driver itself must check for end-of-media. It does this by setting the bp->b_resid member to the number of bytes beyond the end of the device. It must also call the bioerror(D3) function to fail the transfer with the ENXIO error number, unless the B_READ flag is set in the bp->b_flags member and the starting device offset is exactly at the end of the device.

If there is any valid data to transfer, the driver may either start the device I/O immediately or queue it for later processing. The driver then returns from this entry point routine. At a later time, when the I/O has completed or failed, the driver must call the biodone(D3) function to inform the caller of the completion. If the request does not actually require any I/O, the driver may call biodone( ) before returning.

Before calling biodone( ), the driver must reflect the status of the transfer into the buffer header. It must set the bp->b_resid member to the number of bytes not transferred for any reason. If no bytes were transferred, bp->b_resid must be set to the initial value of the bp->b_bcount member; if all of the data bytes were transferred, bp->b_resid must be set to 0. If some portion of the data failed to be transferred because of some error condition, call the bioerror(D3) funtion to store the appropriate error number from errnos(D5) in the buffer header.

See the description of the b_addrtype member of the buf(D4) structure for a description of how to access the actual transfer data in the buffer.

Context and synchronization

Blockable context. The driver can block but cannot do operations such as copyout(D3) that require access to the requesting process's address space.

Hardware applicability

All

Version applicability

ddi: 8, 8mp

Differences between versions

The biostart( ) routine is not supported in DDI versions prior to version 8. Use the read(D2), write(D2), and strategy(D2) entry points instead. The read( ), write( ), and strategy( ) routines must explicitly call buf_breakup(D3) or its equivalent for DDI versions prior to DDI 8. This is done implicitly by the kernel for DDI 8 drivers when biostart( ) is called.

External dependencies

Drivers must declare this entry point routine in the d_biostart member of their drvops(D4) structure.

References

do_biostart(D3), uiobuf(D3)