start(D2sdi)
start --
perform second stage initialization and registration of a Host Bus Adapter
Synopsis (Not in current SDI version
See
start(D2)
for synopsis
and general usage information
about this entry point.
Description
start(D2sdi)
performs Host Bus Adapter (HBA)-specific
initialization and allocation of data structures (command
blocks, queues, and so on).
It is also used to register
the HBA controller withSDI.
Return values
On success, the
start( )
entry point returns 0, indicating that the controller
is registered with SDI.
On failure, it returns -1,
indicating that no controller was found,
no devices are attached,
or some other error condition occurred.
The driver should free any memory
that was allocated for the HBA controller
and then return.
Usage
This part of the initialization is performed
for non-loadable drivers
with system interrupts enabled
and must conform to the conditions defined on the
start(D2)
manual page.
The
start( )
routine is called once and must perform second
phase initialization for each configured controller.
The prefixcntls contain the number of configured
controllers, and prefixidata[] contains the
controller-specific configuration data.
start(D2sdi)
has two main purposes:
-
Perform HBA-specific initialization and allocation
of data structures (command blocks, queues, and so on)
that is not performed by the first phase initialization,
init(D2sdi).
-
Notify the SDI subsystem
whether the HBA controller is present.
If the controller is present,
the routine must register the controller with SDI
by calling the
sdi_gethbano(D3sdi)
function to get the external HBA number
that is used by the system to generate the node name.
After all controller initialization is complete, the
start( )
entry point routine must call the
sdi_register(D3sdi)
function to enter
the controller into the HBA_tbl switch table,
which is SDI's interface to the driver.
In addition, the controller and its devices are entered into
the SDI equipped device table (EDT).
The HBA's
start( )
routine lets the SDI driver know
whether the HBA controller is present.
-
If the controller is present, and at least one device is found,
the start routine must register the controller with SDI by
first calling
sdi_gethbano(D3sdi),
then calling the
sdi_register(D3sdi)
function.
The sdi_gethbano returns
the "external" HBA number
that is used by the system to generate the node name.
The HBA driver needs this number
to generate the mapping from the external number
to its own internal number.
The
sdi_register( )
routine is called after all the controller
initialization has been completed.
The HBA drivers typically use a pair of arrays to map the
external HBA number (returned from sdi_gethbano)
to the internal HBA number, and vice versa.
These arrays must be sized to match
the maximum number of HBAs allowed.
For compatibility reasons the arrays
must be kept in the driver's
Space.c(DSP/4dsp)
file, and sized
to the maximum HBAs defined by SDI_MAX_HBAS.
For example:
char prefix_gtol[SDI_MAX_HBAS];
char prefix_ltog[SDI_MAX_HBAS];
The HBA driver must be prepared to handle commands
through the HBA's
icmd(D2sdi)
routine when sdi_register is called,
since SDI begins the inquiry commands at this time.
The inquiries occur synchronously,
with SDI examining the inquiry data on the return call,
therefore the HBA driver is expected to
delay-wait
the inquiry responses.
Because the HBA driver typically uses
the same routines during inquiry processing
as it does during the normal command processing,
an inittime flag can be used internally
to distinguish the difference.
Interrupts are enabled during start processing,
so the HBA driver
can take advantage of this fact during inquiry processing.
A successful registry of the HBA enters this controller into
the HBA_tbl switch table,
which is SDI's interface to the driver.
In addition, the controller and devices are entered into the
SDI equipped device table (EDT).
-
If the controller is registered with SDI, the
start( )
routine should return a 0.
-
If no controller is found
or any other error condition is detected such that the controller
is not registered,
the start routine should return -1.
-
If the start routine returns -1,
any memory allocated for HBA card detection
should be freed.
The
init(D2sdi)
and
start(D2sdi)
routines are passed no arguments.
The
init(D2sdi)
and
start(D2sdi)
routines are called once,
either at early
init time, if the controller is the boot controller,
or during a later stage of the system initialization,
when the loadable HBAs are loaded.
An internal for loop in each routine
executes the initialization
of each configured controller.
The number of configured controllers
is put into xxx_cntls by the kernel configuration tools.
The xxx_idata structure,
defined in the HBA module's
Space.c(DSP/4dsp)
file contains the controller specific data,
such as the base I/O address,
interrupt request vector,
and DMA channel number.
HBA translate routine
Since many HBA devices require the physical address of the
command block, the
xlat(D2sdi)
(translate) routine allows each
HBA driver to facilitate its own needs.
The arguments passed to the translate
routine are struct hbadata *
,
the buffer flags, and the proc pointer.
Depending on the type of I/O (determined by the flags),
the proc pointer
is used for
vtop(D3)
translation from virtual to physical addresses.
Version applicability
sdi:
1, 2, 3, 4
HBA drivers
with DDI versions prior to version 8.
Differences between versions
DDI 8 drivers should perform
the initialization done in the
start( )
routine in the CFG_ADD subfunction of the
config(D2sdi)
entry point routine.
See Also
init(D2),
init(D2sdi),
sdi_gethbano(D3sdi),
sdi_register(D3sdi),
start(D2)
19 June 2005
© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005