I am sponsoring the following fasttrack for Matthew Jacob. Micro/patch
binding is requested. I believe the case qualifies for self review
(since all the interfaces are Consolidation Private) and have filed it
as Closed Approved Automatic. If there is a request, I'd be happy to
convert it to a fasttrack and set the timer to enable further
discussion.
-Chris
1. Introduction
1.1. Project/Component Working Name:
ndi flavors
1.2. Name of Document Author/Supplier:
Author: Matthew Jacob
1.3. Date of This Document:
Tue Feb 10 11:47:14 PST 2009
4. Technical Description
4.1 Background:
Associated with each device node is private data that may be
accessed via ddi_[gs]et_private_state(9F). The meaning of that data
is known to the driver that sets such data, but also by other parts
of the system where (formal or otherwise) contracts have
established what this private data points to.
4.2 Problem:
One example of this is the usage of SCSA HBA nexus drivers' private
data pointer by common framework SCSA code. This contains a pointer
to a scsi_hba_tran(9S) structure. This is well known amongst
multiple parts of the system.
This becomes a problem when a SCSA HBA nexus driver needs to
support more than just one kind (flavor) of child (i.e. more that
just scsi_device(9S) children). Where does the nexus store
information relevant to a specific kind (flavor) of child?
A previous attempt has been made to address this problem via
extensions to the scsi_hba_tran(9S) structure [1]. However, this
only provided an out for one additional flavor of child, and for
SCSA only. Additionally, code complexity was added by requiring
indirection through the existing unrelated structure with various
ad hoc mechanisms for determining when such dereference was
needed.
4.3 Proposal:
The proposal is to allow a nexus driver to declare, at attach time,
how many flavors of children they support and to ask the DDI
framework to create private pointer storage for any flavors beyond
the standard vanilla flavor (which uses the existing
ddi_[gs]et_private_state(9F) private data storage mechanism).
The proposal also provides interfaces so a nexus driver can set the
flavor of its children.
Then, in any code that requires child flavor-specific private data
held in the nexus to be retrieved, the child's flavor can be used
to select the correct private data.
The number of flavors for each nexus driver is generally up to that
nexus driver. However, in the case of SCSA HBA drivers, the SCSA
framework itself will define a specific set of flavors and what
they mean.
The initial putback of the new interfaces will convert the SMP
support delivered by [1] to use the new ndi_flavor* interfaces as
well as extend the SMP attach framework to be more of a peer to the
SCSI attach framework.
In addition, SCSA work in progress will be using the ndi_flavor*
interfaces to identify device nodes associated with the dynamic
enumeration of initiator ports (ala mscsi/iport).
4.4 Proposed Interfaces:
------------------------------------------------------------------
Interface Name Comm.Lev. Comments
------------------------------------------------------------------
ndi_flavorv_alloc() Cons.Private allocate extra flavor
pointer storage
ndi_flavorv_set() " set private data pointer
for a specific flavor
ndi_flavorv_get() " get ""
ndi_flavor_set() " set the flavor of a dip
(the child)
ndi_flavor_get() " get the flavor of a dip
(the child)
sas_hba_tran_t " SMP specific transport
structure
smp_tran_alloc() " allocate an SMP
specific transport
structure
smp_attach_setup() " attach and set up an
allocated SMP transport
structure
smp_tran_free() " free an SMP transport
structure
4.5 Interface Prototypes:
Defined in sunndi.h:
void ndi_flavorv_alloc(dev_info_t *, int);
void ndi_flavorv_set(dev_info_t *, ndi_flavor_t, void *);
void *ndi_flavorv_get(dev_info_t *, ndi_flavor_t);
void ndi_flavor_set(dev_info_t *, ndi_flavor_t);
ndi_flavor_t ndi_flavor_get(dev_info_t *);
NOTE: It is not an error to call ndi_flavorv_alloc() multiple times
as long as the number of defined flavors stays the same.
NOTE: there is no ndi_flavorv_free() function as the underlying
framework will free any allocations when the dev_info detaches.
Defined in sas_transport.h:
sas_hba_tran_t *sas_hba_tran_alloc(dev_info_t *dip, int flags);
int sas_hba_attach_setup(dev_info_t *dip,
sas_hba_tran_t *smp);
void sas_hba_tran_free(sas_hba_tran_t *smp);
4.4 SCSA Example (fragments):
All HBA drivers, from their attach(9E) implementation, call
scsi_hba_tran_alloc(9F) (or sas_hba_tran_alloc()). In the SCSA
framework code implementing *_tran_alloc() two things happen.
First, the *_tran_alloc() implementation may call
ndi_flavorv_alloc() to reserve space for all SCSA supported
flavors. Second, ndi_flavor_set() will be called to plumb
*_tran_alloc()'s flavor of tran. Storage allocated by the
ndi_flavorv_alloc() call will be freed by the IO framework when the
node detaches.
When a child of a non-SCSAv3 HBA driver is created via bus_config
operations, the flavor of the child may be set:
if (child_is_smp) {
ndi_flavor_set(dip, SCSA_FLAVOR_SMP);
}
In the future, with SCSAv3, establishing the flavor of a child will
be done by SCSA itself.
In the implementation of flavor-specific tran functions called by
target drivers, flavors can be used to select the correct transport
operation vector.
sas_hba_tran_t *tran = ndi_flavorv_get(self, SCSA_FLAVOR_SMP);
When common SCSA scsi_hba.c code needs to perform different
operations based on flavor of an enumerated child:
switch (ndi_flavor_get(child) {
case XXX:
_xxx_(); /* xxx flavor */
break;
case YYY:
_yyy_(); /* yyy flavor */
break;
}
With SCSA, the 'vanilla' flavor is associated with scsi_device(9S)
child using scsi_hba_tran(9S) transport services.
NOTE: For SCSAv3, the ndi_flavor* interfaces will only be used
within the common SCSA framework code. There is no intent to make
the ndi_flavor* interfaces public as part of the SCSAv3.
4.5 Alternatives:
No reasonable alternatives to solve the problem have been found.
Since all proposed interfaces are Private, this case is not
preventing a future project from implementing more sophisticated
ways of plumbing flavor-specific transport services.
4.6 Man Pages
These are private interfaces that, like all other ndi_* functions
and interfaces defined by [1], have no man pages.
4.7 Release Binding
Micro/patch binding is requested.
4.8 References
[1] PSARC case that introduced smp transport extensions
Serial Attached SCSI (SAS) Management Protocol (SMP) support for Solaris
http://sac.sfbay/PSARC/2007/595
http://www.opensolaris.org/os/community/arc/caselog/PSARC/2007/595
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: Automatic
6.6. ARC Exposure: open
