[PATCH 3/3] PM / Docs: Recommend the use of [un]lock_system_sleep() over mutex_[un]lock(&pm_mutex)

[Srivatsa S. Bhat]

On 12/05/2011 11:13 PM, Tejun Heo wrote:

> Hello,
> 
> On Mon, Dec 05, 2011 at 11:08:38PM +0530, Srivatsa S. Bhat wrote:
>> Sorry, I didn't get what you meant here. Are you talking about what
>> needs to be added/changed in the documentation or, are you referring
>> to the code itself and are saying that we must make these APIs
>> internal to the PM alone?
> 
> Ooh, sorry about not being clear.  I meant pm_mutex itself.  There's
> no reason to expose that outside of pm, right?  And in the
> documentation, we can just require use of the APIs instead of pm_mutex
> itself.
> 


Yes, that sounds good. No need for giving unnecessary choices :-)
But I had worded the documentation that way with the intention of
explaining why calling mutex_lock() over pm_mutex can be disastrous (which
I mentioned in the commit message as one of the goals of the patch).
I didn't mean it to give the user 2 choices and say please use
[un]lock_system_sleep() preferably.

Although, we have to notice that unless somebody is acquainted with
these APIs, the first instinct would probably be to directly use
mutex_lock(), until they look up the documentation (hopefully).
So, IMHO, it would do good to keep the explanation in the docs as
it is, in this patch. What do you think?

Regards,
Srivatsa S. Bhat