Re: [PATCH v5 09/13] docs/devel/reset.txt: add doc about Resettable interface

[Damien Hedde]

On 11/29/19 8:00 PM, Peter Maydell wrote:
> On Fri, 18 Oct 2019 at 16:07, Damien Hedde <address@hidden> wrote:
>>
>> Signed-off-by: Damien Hedde <address@hidden>
> 
> Subject line still says ".txt".
> 
>> ---
>>
>> +Polling the reset state
>> +.......................
>> +
>> +Resettable interface provides the ``resettable_is_in_reset()`` function.
>> +This function returns true if the object parameter is currently under reset.
>> +
>> +An object is under reset from the beginning of the *init* phase to the end 
>> of
>> +the *exit* phase. During all three phases, the function will return that the
>> +object is in reset.
>> +
>> +This function may be used if behavior has to be adapted when receiving 
>> external
>> +interaction while in reset state. Note that until migration of the reset 
>> state
>> +is supported, an object should not be left in reset. So apart from being
>> +currently executing one of a reset phase, the only cases when this
>> +function should return true is if an external interaction is made during 
>> *hold*
>> +or *exit* phase of another object in the same reset group.
> 
> This paragraph feels a bit unclear to me but I'm not sure how to improve it.
> 

If I add an example like this is it better ?

This function may be used if the object behavior has to be adapted
while in reset state. For example if a device has an irq input,
it will probably need to ignore it while in reset; then it can for
example check the reset state at the beginning of the irq callback.

Note that until migration of the reset state is supported, an object
should not be left in reset. So apart from being currently executing
one of the reset phases, the only cases when this function will return
true is if an external interaction (like changing an io) is made during
*hold* or *exit* phase of another object in the same reset group.

--
Damien