Re: [RFC PATCH 00/10] isci: core

[Dan Williams <dan.j.williams@intel.com>]

On Sun, 2011-03-27 at 15:32 -0700, Christoph Hellwig wrote:
> Btw, the naming scheme in the driver seems utterly confusing,
> with prefixed split between isci_, sci_ and scic_, where a lot of
> the latter also have a second sds_ or controller_ prefix.  Especially
> the use of controller_ in a lot of the nomenclature seems very
> confusing to me.  Is there a scheme behind all this?
> 

Yes, it needs to be documented, but there is some method behind the
confusion.

The expectation is that the lldd need not understand core internals
outside of a set of interface functions.  Any functions prefixed
scic_sds_ are meant to only be called by other core routines.  We have
broken that rule in places where it added unnecessary indirection, like
the isr handlers and phy enable/disable interface (should probably go
back and make those consistent before the final merge).

Core data-structure definitions are also hidden from the lldd.  All it
has access to are the forward declared structure types.

Any functions prefixed with isci_ belong to the lldd, and to remove
indirection we are teaching the core to call lldd routines and native
Linux routines directly (the bulk of the upstream cleanup effort is
covered by this theme).

During this effort it was found that local variable instances had
inconsistent, sometimes overly verbose (contributing to 80 column
collisions), and sometimes ambiguous names so we are using the following
scheme going forward and converting routines in the course of doing
other cleanups.

object            | lldd instance | core instance
------------------|---------------|---------------
controller / host | ihost         | scic
task / request    | ireq          | sci_req, stp_req, ssp_req, smp_req
sas device        | idev          | sci_dev
sas phy           | iphy          | sci_phy
sas port          | iport         | sci_port