[arc-discuss] Re: ARB rabbit holes (was: Requesting PSARC/2007/124 details)

[James Carlson]

Dale Ghent writes:
> It has been established that:
> 
>    1) The VFS/vnode interfaces are described as "non-public" and  
> unfit for external-to-ON consumption
>    2) "Source code is not documentation"
>    3) (Paraphrasing yourself) "ARC documents are not documentation"

For that third point, ARC documents are not reference documentation in
the same sense that man pages are.

Man pages are the _official_ documentation in Solaris.  (Other systems
have other kinds of official documentation.)  The key distinction is
that we have documented commitments to stability for things in the man
pages.  We don't otherwise.

Interfaces that are "public" in the ARC taxonomy have associated
reference documentation.  Those that are private do not.

> While it is generally accepted that:
> 
>    1) Third party file systems for Solaris are both common and  
> established thingys.

Indeed.

> So what's the deal here? What's the avenue for discussion on this  
> specific topic?

I think the first stop is the folks who "own" and maintain those
interfaces.  You need to get them to agree to nail the jello to the
wall before you can actually make these things stable.

For third parties that have some sort of relationship with Sun, that
would have historically have been through two mechanisms: filing an
RFE ("please make this thing stable") and dealing with some sort of
sales or account manager.

Obviously, other than the RFE part (which is pretty clear), that
doesn't translate well into OpenSolaris.  Nor does the "go talk to the
owner" bit translate, as we don't seem to publish any owners.  (!)

Fortunately, in this particular case, I think the answer is to go to
the UFS community, where common file system things (including VFS) are
discussed:

  http://www.opensolaris.org/os/community/ufs/

> You can Kevin started talking about consolidations  
> and C-Teams and... geez, who knows what ever else is involved.... but  
> the simple fact is that I wouldn't know what a "C-Team" or whatever  
> is even if it took me out to dinner. I don't know the history as to  
> why VFS specifically has been kept non-public, but I'd like to both  
> find out why, and change it if possible.
> 
> The second edition of Solaris Internals does a fine job at  
> documenting VFS/vnode. Call that public documentation for lack of a  
> better word.

There are many books, whitepapers, blogs, and other sources of
information that talk about Solaris in detail.  It's still not
documentation in architectural terms.

> Obviously, it is now out of date as of 2007/124 putback.  
> Bummer.

True.  And as a Consolidation Private interfaces, there can be
arbitrary changes to it at any time and without notice.

-- 
James Carlson, Solaris Networking              <james.d.carlson at sun.com>
Sun Microsystems / 1 Network Drive         71.232W   Vox +1 781 442 2084
MS UBUR02-212 / Burlington MA 01803-2757   42.496N   Fax +1 781 442 1677