kern/47115: rules for mutex_owned, rw_write_held, &c., are not clear

[Taylor R Campbell <campbell+netbsd%mumble.net@localhost>]

>Number:         47115
>Category:       kern
>Synopsis:       rules for mutex_owned, rw_write_held, &c., are not clear
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    kern-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Tue Oct 23 20:25:00 +0000 2012
>Originator:     Taylor R Campbell <campbell+netbsd%mumble.net@localhost>
>Release:        NetBSD 6.99.14
>Organization:
>Environment:
Architecture: any
Machine: any
>Description:

        The rules for using the routines mutex_owned, rw_write_held,
        rw_read_held, VOP_ISLOCKED, and so on, are not self-evident (at
        least to mere mortals such as me), and the intent does not seem
        to be reflected accurately in the man pages, as a private
        discussion among several developers revealed.

        These things are clear:

        . It's kosher to kassert any of these positively.
        . Kasserting !rw_read_held or !VOP_ISLOCKED is wrong.
        . Non-diagnostic uses of these are bogus.
        . We have a lot of uses in tree that are wrong or unclear.

        These things are not so clear:

        . Is KASSERT(VOP_ISLOCKED(vp) != LK_EXCLUSIVE) kosher?
        . Is kasserting !mutex_owned or !rw_write_held kosher?
        . How are the rules different for a spin vs adaptive mutex?
        . and maybe others.

        The vop issue should largely go away once we take a chainsaw to
        the whole vop protocol, but that won't happen for a little
        while.

>How-To-Repeat:

        Read some code and find negative kassertions.  Ask developers
        whether they are OK.  Fail to reach a consensus.  Throw up
        hands and hit the big red SEND-PR button with them.  (Reattach
        hands to wrists once they have plummeted back to the table from
        the ceiling.  Clean up the ensuing mess.)

>Fix:

        Yes, please!