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.