[PATCH v2] docs: driver-api: device-io: Split out relaxed access mention

[PATCH v2] docs: driver-api: device-io: Split out relaxed access mention

[Andrew Davis]

We list all the normal non-relaxed device io functions first, but also
list just the "read" versions of the relaxed device io functions.
Instead of adding the "write" versions to that list, fix a statement
below which should describe the relaxed versions so it is understood
that both read and write have relaxed versions.

Signed-off-by: Andrew Davis <afd@ti.com>
---

Changes for v2:
 - None, rebase on v7.0-rc2 and resend

 Documentation/driver-api/device-io.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst
index d1aaa961cac4d..5b94973f44762 100644
--- a/Documentation/driver-api/device-io.rst
+++ b/Documentation/driver-api/device-io.rst
@@ -56,7 +56,6 @@ Both read and write accesses are supported; there is no prefetch support
 at this time.
 
 The functions are named readb(), readw(), readl(), readq(),
-readb_relaxed(), readw_relaxed(), readl_relaxed(), readq_relaxed(),
 writeb(), writew(), writel() and writeq().
 
 Some devices (such as framebuffers) would like to use larger transfers than
@@ -67,7 +66,7 @@ guaranteed to copy data in order.
 
 The read and write functions are defined to be ordered. That is the
 compiler is not permitted to reorder the I/O sequence. When the ordering
-can be compiler optimised, you can use __readb() and friends to
+can be compiler optimised, you can use readb_relaxed() and friends to
 indicate the relaxed ordering. Use this with care.
 
 While the basic functions are defined to be synchronous with respect to
-- 
2.39.2

Re: [PATCH v2] docs: driver-api: device-io: Split out relaxed access mention

[Jonathan Corbet]

Andrew Davis <afd@ti.com> writes:

> We list all the normal non-relaxed device io functions first, but also
> list just the "read" versions of the relaxed device io functions.
> Instead of adding the "write" versions to that list, fix a statement
> below which should describe the relaxed versions so it is understood
> that both read and write have relaxed versions.
>
> Signed-off-by: Andrew Davis <afd@ti.com>
> ---
>
> Changes for v2:
>  - None, rebase on v7.0-rc2 and resend
>
>  Documentation/driver-api/device-io.rst | 3 +--
>  1 file changed, 1 insertion(+), 2 deletions(-)
>
> diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst
> index d1aaa961cac4d..5b94973f44762 100644
> --- a/Documentation/driver-api/device-io.rst
> +++ b/Documentation/driver-api/device-io.rst
> @@ -56,7 +56,6 @@ Both read and write accesses are supported; there is no prefetch support
>  at this time.
>  
>  The functions are named readb(), readw(), readl(), readq(),
> -readb_relaxed(), readw_relaxed(), readl_relaxed(), readq_relaxed(),
>  writeb(), writew(), writel() and writeq().
>  
>  Some devices (such as framebuffers) would like to use larger transfers than
> @@ -67,7 +66,7 @@ guaranteed to copy data in order.
>  
>  The read and write functions are defined to be ordered. That is the
>  compiler is not permitted to reorder the I/O sequence. When the ordering
> -can be compiler optimised, you can use __readb() and friends to
> +can be compiler optimised, you can use readb_relaxed() and friends to
>  indicate the relaxed ordering. Use this with care.

...and we really think it's better to not just list the functions that
are available?

Among other things, the list would then automatically link to the
documentation for each function ... assuming, of course, that we ever
got around to documenting them...

Thanks,

jon

Re: [PATCH v2] docs: driver-api: device-io: Split out relaxed access mention

[Andrew Davis]

On 3/9/26 11:21 AM, Jonathan Corbet wrote:
> Andrew Davis <afd@ti.com> writes:
> 
>> We list all the normal non-relaxed device io functions first, but also
>> list just the "read" versions of the relaxed device io functions.
>> Instead of adding the "write" versions to that list, fix a statement
>> below which should describe the relaxed versions so it is understood
>> that both read and write have relaxed versions.
>>
>> Signed-off-by: Andrew Davis <afd@ti.com>
>> ---
>>
>> Changes for v2:
>>   - None, rebase on v7.0-rc2 and resend
>>
>>   Documentation/driver-api/device-io.rst | 3 +--
>>   1 file changed, 1 insertion(+), 2 deletions(-)
>>
>> diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst
>> index d1aaa961cac4d..5b94973f44762 100644
>> --- a/Documentation/driver-api/device-io.rst
>> +++ b/Documentation/driver-api/device-io.rst
>> @@ -56,7 +56,6 @@ Both read and write accesses are supported; there is no prefetch support
>>   at this time.
>>   
>>   The functions are named readb(), readw(), readl(), readq(),
>> -readb_relaxed(), readw_relaxed(), readl_relaxed(), readq_relaxed(),
>>   writeb(), writew(), writel() and writeq().
>>   
>>   Some devices (such as framebuffers) would like to use larger transfers than
>> @@ -67,7 +66,7 @@ guaranteed to copy data in order.
>>   
>>   The read and write functions are defined to be ordered. That is the
>>   compiler is not permitted to reorder the I/O sequence. When the ordering
>> -can be compiler optimised, you can use __readb() and friends to
>> +can be compiler optimised, you can use readb_relaxed() and friends to
>>   indicate the relaxed ordering. Use this with care.
> 
> ...and we really think it's better to not just list the functions that
> are available?
> 

They are listed, down below in the section that explains the _relaxed() part[0]

Up here at the top, only the regular non-postfixed versions are listed, except
the "read" relaxed, but not the "write" ones. To be consistent I removed those.

Maybe it would be better to remove the whole list here at the top since the
documentation has been expanded and this list up here is now nowhere near
comprehensive of all the variations available.

Andrew

[0] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/driver-api/device-io.rst?h=v7.0-rc1#n179

> Among other things, the list would then automatically link to the
> documentation for each function ... assuming, of course, that we ever
> got around to documenting them...
> 
> Thanks,
> 
> jon