I am sponsoring the following fasttrack for myself. Micro/patch binding
is requested. The timer is set to expire on March 4 2009.
-Chris
Template Version: @(#)sac_nextcase %I% %G% SMI
This information is Copyright 2009 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
scsi_device property interfaces
1.2. Name of Document Author/Supplier:
Author: Chris Horne
1.3. Date of This Document:
22 February, 2009
4.0 Technical Description
4.1 Background
MPxIO [2] makes a distinction between a 'path' to a device and
device 'identity': the same device identity can be accessed via
multiple paths. When an MPxIO device is enumerated by Solaris,
'identity' is represented by a 'client' devinfo child of a vHCI
(virtual Host Controller Interconnect), and paths are represented
by pathinfo children of the pHCI (physical Host Controller
Interconnects) transports through which the device can be
physically accessed. Like devinfo nodes, each pathinfo node has a
unit-address relative to the pHCI transport. The vHCI nexus is
responsible for managing the physical paths, and multiplexing
transport service operations between the client driver and paths.
For SCSA, each initiator port of a physical SCSI HBA, where an
initiator port is the 'I' of SCSI defined I-T-L nexus model,
represents a distinct pHCI transport. Paths are managed by
scsi_vhci nexus code. The scsi_vhci code multiplexes
scsi_transport(9F) requests from the sd(7D) client driver to SCSA
HBA pHCI I-T-L paths.
4.2 Problem
The distinction between 'path' .vs. 'identity' noted above affects
properties: some properties provide device identity information,
and others provide path information. For example,
inquiry-device-type(9P) is related to identity, while transport
unit-address properties are always related to path.
When a SCSA HBA driver needs to reference a property of a path,
currently private mdi_ interfaces must be used. In order to use
these private mdi_ interfaces, further private knowledge is needed
to determine if a scsi_device(9S) structure is related to a devinfo
node or a pathinfo node (and to obtain a pointer to the pathinfo
node).
In the future, when devinfo/pathinfo enumeration is performed by
the SCSA framework, without improved scsi_device_*() property
interfaces a SCSA HBA driver would still need to use the private
knowledge mentioned above in code that needs to access path
properties (like tran_tgt_init(9E)). A driver may also want to
establish path properties for consumption by management
applications using libdevinfo(3LIB).
4.3 Proposed Solution
To allow SCSA HBA drivers to indicate the path .vs. identity
association of a property, without exposing details of the private
mdi_ and scsi_device(9S) implementations, a new set of
scsi_device_prop_*() interfaces is proposed.
With these interfaces, the caller uses "struct scsi_device *"
handle, and indicates the desired association with a flag
argument: SCSI_DEVICE_PROP_PATH or SCSI_DEVICE_PROP_DEVICE.
The implementation of these new scsi_device_prop*() interfaces,
based on the devinfo.vs.pathinfo orientation of the scsi_device
structure and the flag argument, will redirect the property
operation to the correct ddi_prop_*(9F) or mdi_prop_*() interface
(without exposing mdi_ interfaces or additional scsi_device(9S)
implementation details to the SCSA HBA driver).
When the SCSA framework code implementing a scsi_device_prop_*()
interface ends up calling a ddi_prop_*(9F) interface, no specific
dev_t association is used (code choses DDI_DEV_T_ANY/DDI_DEV_T_NONE
as appropriate). When the SCSA framework code implementing
scsi_device_prop_*() interface ends up calling a ddi_prop_*(9F)
interface that accepts the DDI_PROP_DONTPASS and DDI_PROP_NOTPROM,
both flags are passed. The mdi_prop_*() interfaces don't take dev_t
or DDI_PROP_* flag arguments.
Since there is no mdi_prop_exists() function, I chose to not
include scsi_device_prop_exists() in this proposal. If this is a
problem, it can be added in the future.
In addition to the property interfaces, for consumers that want the
entire unit-address, without needing to request the multiple path
properties associated with a unit-address, a new
scsi_device_unit_address() function is proposed.
4.5 Interfaces:
All interfaces are currently proposed as 'Consolidation Private',
but promotion to 'stable' is expected after we have more
experience. An initial draft of the man pages are provided.
------------------------------------------------------------------
Interface Name Comm.Lev. Comments
------------------------------------------------------------------
Cons.Private
(all interfaces below)
SCSI_DEVICE_PROP_DEVICE property-of-device flag
argument to
scsi_device_prop* below
SCSI_DEVICE_PROP_PATH property-of-path flag
argument to
scsi_device_prop* below
peer of...
(all interfaces below)
scsi_device_prop_get_int() ddi_prop_get_int(9F)
scsi_device_prop_get_int64() ddi_prop_get_int64(9F)
scsi_device_prop_lookup_byte_array() ddi_prop_lookup_byte_array(9F)
mdi_prop_lookup_byte_array()
scsi_device_prop_lookup_int_array() ddi_prop_lookup_int_array(9F)
mdi_prop_lookup_int_array()
scsi_device_prop_lookup_string() ddi_prop_lookup_string(9F)
mdi_prop_lookup_string()
scsi_device_prop_lookup_string_array() ddi_prop_lookup_string_array(9F)
mdi_prop_lookup_string_array
scsi_device_prop_free() ddi_prop_free(9F)
mdi_prop_free()
scsi_device_prop_update_byte_array() ddi_prop_update_byte_array(9F)
mdi_prop_update_byte_array()
scsi_device_prop_update_int() ddi_prop_update_int(9F)
mdi_prop_update_int()
scsi_device_prop_update_int64() ddi_prop_update_int64(9F)
mdi_prop_update_int64()
scsi_device_prop_update_int_array() ddi_prop_update_int_array(9F)
mdi_prop_update_int_array()
scsi_device_prop_update_string() ddi_prop_update_string(9F)
mdi_prop_update_string()
scsi_device_prop_update_string_array() ddi_prop_update_string_array(9F)
mdi_prop_update_string_array()
scsi_device_prop_remove() ddi_prop_remove(9F)
mdi_prop_remove()
scsi_device_unit_address() return unit address
associated with a
scsi_device structure.
Prototypes (defined in <sys/scsi/device.h>)
int scsi_device_prop_get_int(struct scsi_device *,
uint_t flags, char *name, int);
int64_t scsi_device_prop_get_int64(struct scsi_device *,
uint_t flags, char *name, int64_t);
int scsi_device_prop_lookup_byte_array(struct scsi_device *,
uint_t flags, char *name, uchar_t **, uint_t *);
int scsi_device_prop_lookup_int_array(struct scsi_device *,
uint_t flags, char *name, int **, uint_t *);
int scsi_device_prop_lookup_string(struct scsi_device *,
uint_t flags, char *name, char **);
int scsi_device_prop_lookup_string_array(struct scsi_device *,
uint_t flags, char *name, char ***, uint_t *);
void scsi_device_prop_free(struct scsi_device *,
uint_t flags, void *);
int scsi_device_prop_update_byte_array(struct scsi_device *,
uint_t flags, char *name, uchar_t *, uint_t);
int scsi_device_prop_update_int(struct scsi_device *,
uint_t flags, char *name, int);
int scsi_device_prop_update_int64(struct scsi_device *,
uint_t flags, char *name, int64_t);
int scsi_device_prop_update_int_array(struct scsi_device *,
uint_t flags, char *name, int *, uint_t);
int scsi_device_prop_update_string(struct scsi_device *,
uint_t flags, char *name, char *);
int scsi_device_prop_update_string_array(struct scsi_device *,
uint_t flags, char *name, char **, uint_t);
int scsi_device_prop_remove(struct scsi_device *,
uint_t flags, char *name);
char *scsi_device_unit_address(struct scsi_device *);
4.6 Man pages
The following new man pages, available in the case materials
directory, provide more details about the interfaces above.
scsi_device_prop_get_int.9f
scsi_device_prop_lookup_byte_array.9f
scsi_device_prop_update_byte_array.9f
scsi_device_prop_remove.9f
scsi_device_unit_address.9f
4.7 Release Binding
Micro/patch binding is requested.
4.8 References
[1] DDI Interfaces for PCI (ddi_prop_*())
http://sac.sfbay/PSARC/1994/075
http://www.opensolaris.org/os/community/arc/caselog/1994/075
[2] Multiplexed I/O Framework (mdi_prop_*())
http://sac.sfbay/PSARC/1999/647
http://www.opensolaris.org/os/community/arc/caselog/1999/647
[3] 64-bit Property Interfaces (ddi_prop_*())
http://sac.sfbay/PSARC/2001/186
http://www.opensolaris.org/os/community/arc/caselog/2001/186
[4] LDF: Layered Driver Framework (ldi_prop_*())
http://sac.sfbay/PSARC/2001/769
http://www.opensolaris.org/os/community/arc/caselog/2001/769
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
