These abstractions are used in tandem with SCSI complex
addressing. A device driver that uses these interfaces generally passes both
SCSI_HBA_HBA flag and the
SCSI_HBA_ADDR_COMPLEX in the
hba_flags argument to
Consider a device that has two physical ports, and thus two phys. Each phy has four lanes, thus we describe the phy as having a mask of 0xf. Each bit in the mask corresponds to a specific lane. In this example, each phy would be represented in the system by an iport and may enumerate a different device for each lane of the phy. If an expander is attached to one or more of the lanes of a phy, then additional devices will be enumerated under the expander and be added to that phy's iport.
Another example to consider is when each lane of a phy is directly connected to a single disk through a passive backplane. In this case, each lane may represent its own iport, since the management of each is independent, basically there are many devices each with a mask of 0x1.
iports do not need to map to a physical phy. Some HBAs support a combination of both physical and virtual devices. In that case, the driver may create two different iports, one for the physical devices and one for the virtual devices.
One property of iports is that they're attached separately from the main device and therefore have their own scsi_hba_tran(9S) structure. As a result, that means that a driver can provide different entry points for each iport, especially if they represent different classes of resources, for example one iport for all physical devices and one for all virtual devices. This allows for a driver to return different capabilities, among other behaviors and entry points, for these different iports. One specific case of this is that while physical devices may provide a means to get to a SCSI WWN, virtual devices may not have a WWN and instead must use a different addressing format.
iports are considered children of the device driver that attach
them, but they are bound to the same driver. This means that when an iport
is created, the attach(9E) and
probe(9E) entry points of the parent
driver (usually indicated by passing a dev_info
structure) will be called. Similarly, when an iport is removed from the
system, then the driver's detach(9E)
entry point will be called. A driver can determine whether an iport is being
attached or not by calling the
function. The value will return
NULL if the
attaching device represents the driver.
To manage iports, drivers have two different options. If the set of iport an HBA supports are static, then they should use the scsi_hba_iport_register(9F) function to register an iport.
If instead, the set of iports are dynamic and map to the coming and going of phys discovered by the driver (or some other dynamic source), then the driver should use the iportmap set of functions. See the section phymap and iportmap for more information.
By using a target map, the operating system will take responsibility for notifying the driver when devices have come and gone from a target map, once it has settled, and it will also take responsibility for having device nodes come and go, meaning that the device driver does not need to know anything about the devices tree or worry about other parts of being a nexus driver.
Target maps come in two forms which change how the HBA driver is responsible for reporting changes:
In the full-set mode, the driver always reports the full set of current devices that it sees. When the driver finishes the report, the operating system will inform the driver of addresses that were added and addresses that were removed. These addresses correspond to newly found devices and recently removed devices, respectively. The full-set mode allows for a simpler device driver, particularly if addition and removal notifications may be dropped by the hardware.
When using the per-address mode of a target map, the HBA driver is responsible for indicating which addresses have come and gone from the system.
In either mode, the driver will receive two callbacks, if they have been registered when the target map was created. The first callback fires before a target driver like sd, ses, etc. is attached. The second callback fires after the corresponding driver has been attached. These allow the HBA driver to perform any operations that are required on the devices.
Each target map has two different sets of devices that it manages in this form. The devices are separated into the following groups:
All SATA, SCSI, SAS, SES, etc. devices all are considered part of the first category.
The following functions are used to manage target maps operating in full-set mode:
The following functions are used to manage target maps operating in per-address mode:
The iportmap is used to maintain a dynamic set of iports related to a device. The iports are each identified by an address, which is generally a unit address string. For example, when a new phy is added to the phymap which represents a new SAS port being used, then a corresponding iport will be created and associated with that entry from the phymap. Once the iport has been created, a normal target map can be created on top of it to handle detected SCSI and SMP devices.
Both the phymap and iportmap operate in a similar fashion to the per-address mode of a tgtmap. Entries can be added and removed through direct functions. The phymap provides callbacks similar to the tgtmap; however, the iportmap does not. This is because when an iport is added or removed, a new node is added to the devices tree and the driver's attach(9E) entry point is called with a new dev_info_t structure representing the iport.
During the phymap callback, the HBA driver should create a new iport with the unit address passed in from the callback function. This relationship is important when taking advantage of the ability to map between an iport and the set of phys that it represents.
The following functions are used to manage iportmaps:
The following functions are used to manage phymaps:
When this flag is set, the HBA driver must treat the SCSI address as an opaque structure. Once in this mode, the driver may get and set a private data structure on the SCSI device. This is facilitated by the scsi_device_hba_private_set(9F) and scsi_device_hba_private_get(9F) functions. In addition, the system provides a means to map between the scsi_address(9S) structure and the corresponding scsi_device(9S) structure. This is performed by the scsi_device_unit_address(9F) function.
|April 18, 2017||OmniOS|