[PATCH v2 1/3] loop.4: Document LO_FLAGS_DIRECT_IO flag

[PATCH v2 1/3] loop.4: Document LO_FLAGS_DIRECT_IO flag

[Yang Xu]

Signed-off-by: Yang Xu <xuyang2018.jy@cn.fujitsu.com>
---
 man4/loop.4 | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/man4/loop.4 b/man4/loop.4
index a3c59310d..1f8a31ac7 100644
--- a/man4/loop.4
+++ b/man4/loop.4
@@ -130,6 +130,10 @@ The loopback device will autodestruct on last close.
 .BR LO_FLAGS_PARTSCAN " (since Linux 3.2)"
 .\" commit e03c8dd14915fabc101aa495828d58598dc5af98
 Allow automatic partition scanning.
+.TP
+.BR LO_FLAGS_DIRECT_IO " (since Linux 4.10)"
+.\" commit 2e5ab5f379f96a6207c45be40c357ebb1beb8ef3
+Use direct io mode to access backing file.
 .RE
 .TP
 .B LOOP_GET_STATUS
-- 
2.23.0

[PATCH v2 2/3] loop.4: add some details about lo_flag

[Yang Xu]

Signed-off-by: Yang Xu <xuyang2018.jy@cn.fujitsu.com>
---
 man4/loop.4 | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/man4/loop.4 b/man4/loop.4
index 1f8a31ac7..41abe0122 100644
--- a/man4/loop.4
+++ b/man4/loop.4
@@ -136,6 +136,9 @@ Allow automatic partition scanning.
 Use direct io mode to access backing file.
 .RE
 .TP
+.I The LOOP_SET_STATUS can not set the first and last flag because
+they are both set from kernel.
+.TP
 .B LOOP_GET_STATUS
 Get the status of the loop device.
 The (third)
-- 
2.23.0

[PATCH v2 3/3] loop.4: Document loop_configure ioctl

[Yang Xu]

Signed-off-by: Yang Xu <xuyang2018.jy@cn.fujitsu.com>
---
 man4/loop.4 | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/man4/loop.4 b/man4/loop.4
index 41abe0122..44dfd9a8c 100644
--- a/man4/loop.4
+++ b/man4/loop.4
@@ -181,6 +181,41 @@ This value must be a power of two in the range
 otherwise, an
 .B EINVAL
 error results.
+.TP
+.BR LOOP_CONFIGURE " (since Linux 5.8)"
+.\" commit 3448914e8cc550ba792d4ccc74471d1ca4293aae
+Setup and configure all loop device parameters using the (third)
+.BR ioctl (2)
+argument at once.
+This argument is a pointer to
+.I loop_config
+structure, defined in
+.I <linux/loop.h>
+as:
+.IP
+.in +4n
+.EX
+struct loop_config {
+     __u32               fd;
+     __u32               block_size;
+     struct loop_info64  info;
+     __u64               __reserved[8];
+};
+.EE
+.in
+.IP
+In addition to doing what
+.BR LOOP_SET_STATUS
+can do,
+.BR LOOP_CONFIGURE
+can also be used to set the correct block size immediately
+by setting loop_config.block_size. Explicitly request
+direct I/O mode by setting
+.BR LO_FLAGS_DIRECT_IO
+in loop_config.info.lo_flags. Explicitly request read-only
+mode by setting
+.BR LO_FLAGS_READ_ONLY
+in loop_config.info.lo_flags.
 .PP
 Since Linux 2.6, there are two new
 .BR ioctl (2)
-- 
2.23.0

AW: [PATCH v2 2/3] loop.4: add some details about lo_flag

[Walter Harms]

Hi,
IMHO "first" and "last" is something that should be avoided in documentation
because the meaning may change in future releases.
I guess you want to say: lo_number and reserved ?

re,
 wh
________________________________________
Von: linux-man-owner@vger.kernel.org [linux-man-owner@vger.kernel.org] im Auftrag von Yang Xu [xuyang2018.jy@cn.fujitsu.com]
Gesendet: Donnerstag, 6. August 2020 11:48
An: linux-man@vger.kernel.org
Cc: Yang Xu
Betreff: [PATCH v2 2/3] loop.4: add some details about lo_flag

Signed-off-by: Yang Xu <xuyang2018.jy@cn.fujitsu.com>
---
 man4/loop.4 | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/man4/loop.4 b/man4/loop.4
index 1f8a31ac7..41abe0122 100644
--- a/man4/loop.4
+++ b/man4/loop.4
@@ -136,6 +136,9 @@ Allow automatic partition scanning.
 Use direct io mode to access backing file.
 .RE
 .TP
+.I The LOOP_SET_STATUS can not set the first and last flag because
+they are both set from kernel.
+.TP
 .B LOOP_GET_STATUS
 Get the status of the loop device.
 The (third)
--
2.23.0

Re: AW: [PATCH v2 2/3] loop.4: add some details about lo_flag

[Yang Xu]

Hi Walter

> Hi,
> IMHO "first" and "last" is something that should be avoided in documentation
> because the meaning may change in future releases.
Thanks, I see.
> I guess you want to say: lo_number and reserved ?
No, I just said the loop_set_status ioctl can not set read-only and 
direct io flag.

Best Regards
Yang Xu
> 
> re,
>   wh
> ________________________________________
> Von: linux-man-owner@vger.kernel.org [linux-man-owner@vger.kernel.org] im Auftrag von Yang Xu [xuyang2018.jy@cn.fujitsu.com]
> Gesendet: Donnerstag, 6. August 2020 11:48
> An: linux-man@vger.kernel.org
> Cc: Yang Xu
> Betreff: [PATCH v2 2/3] loop.4: add some details about lo_flag
> 
> Signed-off-by: Yang Xu <xuyang2018.jy@cn.fujitsu.com>
> ---
>   man4/loop.4 | 3 +++
>   1 file changed, 3 insertions(+)
> 
> diff --git a/man4/loop.4 b/man4/loop.4
> index 1f8a31ac7..41abe0122 100644
> --- a/man4/loop.4
> +++ b/man4/loop.4
> @@ -136,6 +136,9 @@ Allow automatic partition scanning.
>   Use direct io mode to access backing file.
>   .RE
>   .TP
> +.I The LOOP_SET_STATUS can not set the first and last flag because
> +they are both set from kernel.
> +.TP
>   .B LOOP_GET_STATUS
>   Get the status of the loop device.
>   The (third)
> --
> 2.23.0
> 
> 
> 
> 
> 

AW: AW: [PATCH v2 2/3] loop.4: add some details about lo_flag

[Walter Harms]

ok, i understand now (i hope).

maybe this version is more clear:

The LOOP_SET_STATUS can neither set the 
.B lo_flags  
LO_FLAGS_READ_ONLY  nor the LO_FLAGS_DIRECT_IO 
because they are exclusively set from kernel.

hope that helps
wh

________________________________________
Von: linux-man-owner@vger.kernel.org [linux-man-owner@vger.kernel.org] im Auftrag von Yang Xu [xuyang2018.jy@cn.fujitsu.com]
Gesendet: Montag, 10. August 2020 08:53
An: Walter Harms; linux-man@vger.kernel.org
Betreff: Re: AW: [PATCH v2 2/3] loop.4: add some details about lo_flag

Hi Walter

> Hi,
> IMHO "first" and "last" is something that should be avoided in documentation
> because the meaning may change in future releases.
Thanks, I see.
> I guess you want to say: lo_number and reserved ?
No, I just said the loop_set_status ioctl can not set read-only and
direct io flag.

Best Regards
Yang Xu
>
> re,
>   wh
> ________________________________________
> Von: linux-man-owner@vger.kernel.org [linux-man-owner@vger.kernel.org] im Auftrag von Yang Xu [xuyang2018.jy@cn.fujitsu.com]
> Gesendet: Donnerstag, 6. August 2020 11:48
> An: linux-man@vger.kernel.org
> Cc: Yang Xu
> Betreff: [PATCH v2 2/3] loop.4: add some details about lo_flag
>
> Signed-off-by: Yang Xu <xuyang2018.jy@cn.fujitsu.com>
> ---
>   man4/loop.4 | 3 +++
>   1 file changed, 3 insertions(+)
>
> diff --git a/man4/loop.4 b/man4/loop.4
> index 1f8a31ac7..41abe0122 100644
> --- a/man4/loop.4
> +++ b/man4/loop.4
> @@ -136,6 +136,9 @@ Allow automatic partition scanning.
>   Use direct io mode to access backing file.
>   .RE
>   .TP
> +.I The LOOP_SET_STATUS can not set the first and last flag because
> +they are both set from kernel.
> +.TP
>   .B LOOP_GET_STATUS
>   Get the status of the loop device.
>   The (third)
> --
> 2.23.0
>
>
>
>
>

Re: AW: AW: [PATCH v2 2/3] loop.4: add some details about lo_flag

[Yang Xu]

Hi  Walter


> ok, i understand now (i hope).
> 
> maybe this version is more clear:
> 
> The LOOP_SET_STATUS can neither set the
> .B lo_flags
> LO_FLAGS_READ_ONLY  nor the LO_FLAGS_DIRECT_IO
> because they are exclusively set from kernel.
Sorry for the late reply.
I think it is better.
Thanks.
Let's wait for Michael's review.

Best Regards
Yang Xu
> 
> hope that helps
> wh
> 
> ________________________________________
> Von: linux-man-owner@vger.kernel.org [linux-man-owner@vger.kernel.org] im Auftrag von Yang Xu [xuyang2018.jy@cn.fujitsu.com]
> Gesendet: Montag, 10. August 2020 08:53
> An: Walter Harms; linux-man@vger.kernel.org
> Betreff: Re: AW: [PATCH v2 2/3] loop.4: add some details about lo_flag
> 
> Hi Walter
> 
>> Hi,
>> IMHO "first" and "last" is something that should be avoided in documentation
>> because the meaning may change in future releases.
> Thanks, I see.
>> I guess you want to say: lo_number and reserved ?
> No, I just said the loop_set_status ioctl can not set read-only and
> direct io flag.
> 
> Best Regards
> Yang Xu
>>
>> re,
>>    wh
>> ________________________________________
>> Von: linux-man-owner@vger.kernel.org [linux-man-owner@vger.kernel.org] im Auftrag von Yang Xu [xuyang2018.jy@cn.fujitsu.com]
>> Gesendet: Donnerstag, 6. August 2020 11:48
>> An: linux-man@vger.kernel.org
>> Cc: Yang Xu
>> Betreff: [PATCH v2 2/3] loop.4: add some details about lo_flag
>>
>> Signed-off-by: Yang Xu <xuyang2018.jy@cn.fujitsu.com>
>> ---
>>    man4/loop.4 | 3 +++
>>    1 file changed, 3 insertions(+)
>>
>> diff --git a/man4/loop.4 b/man4/loop.4
>> index 1f8a31ac7..41abe0122 100644
>> --- a/man4/loop.4
>> +++ b/man4/loop.4
>> @@ -136,6 +136,9 @@ Allow automatic partition scanning.
>>    Use direct io mode to access backing file.
>>    .RE
>>    .TP
>> +.I The LOOP_SET_STATUS can not set the first and last flag because
>> +they are both set from kernel.
>> +.TP
>>    .B LOOP_GET_STATUS
>>    Get the status of the loop device.
>>    The (third)
>> --
>> 2.23.0
>>
>>
>>
>>
>>
> 
> 
> 
> 

Re: [PATCH v2 1/3] loop.4: Document LO_FLAGS_DIRECT_IO flag

[Michael Kerrisk (man-pages)]

On 8/6/20 11:48 AM, Yang Xu wrote:
> Signed-off-by: Yang Xu <xuyang2018.jy@cn.fujitsu.com>
> ---
>  man4/loop.4 | 4 ++++
>  1 file changed, 4 insertions(+)

Thanks, Yang Xu. Patch applied.

Cheers,

Michael

> 
> diff --git a/man4/loop.4 b/man4/loop.4
> index a3c59310d..1f8a31ac7 100644
> --- a/man4/loop.4
> +++ b/man4/loop.4
> @@ -130,6 +130,10 @@ The loopback device will autodestruct on last close.
>  .BR LO_FLAGS_PARTSCAN " (since Linux 3.2)"
>  .\" commit e03c8dd14915fabc101aa495828d58598dc5af98
>  Allow automatic partition scanning.
> +.TP
> +.BR LO_FLAGS_DIRECT_IO " (since Linux 4.10)"
> +.\" commit 2e5ab5f379f96a6207c45be40c357ebb1beb8ef3
> +Use direct io mode to access backing file.
>  .RE
>  .TP
>  .B LOOP_GET_STATUS
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: AW: AW: [PATCH v2 2/3] loop.4: add some details about lo_flag

[Michael Kerrisk (man-pages)]

Hello Yang Xu,

On Tue, 8 Sep 2020 at 11:55, Yang Xu <xuyang2018.jy@cn.fujitsu.com> wrote:
>
> Hi  Walter
>
>
> > ok, i understand now (i hope).
> >
> > maybe this version is more clear:
> >
> > The LOOP_SET_STATUS can neither set the
> > .B lo_flags
> > LO_FLAGS_READ_ONLY  nor the LO_FLAGS_DIRECT_IO
> > because they are exclusively set from kernel.
> Sorry for the late reply.
> I think it is better.
> Thanks.
> Let's wait for Michael's review.

I think it is probably better as Walter suggests. Could you redraft
the patch please?

Thanks,

Michael



--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH v2 3/3] loop.4: Document loop_configure ioctl

[Michael Kerrisk (man-pages)]

Hello Yang Xu,

On 8/6/20 11:48 AM, Yang Xu wrote:
> Signed-off-by: Yang Xu <xuyang2018.jy@cn.fujitsu.com>
> ---
>  man4/loop.4 | 35 +++++++++++++++++++++++++++++++++++
>  1 file changed, 35 insertions(+)
> 
> diff --git a/man4/loop.4 b/man4/loop.4
> index 41abe0122..44dfd9a8c 100644
> --- a/man4/loop.4
> +++ b/man4/loop.4
> @@ -181,6 +181,41 @@ This value must be a power of two in the range
>  otherwise, an
>  .B EINVAL
>  error results.
> +.TP
> +.BR LOOP_CONFIGURE " (since Linux 5.8)"
> +.\" commit 3448914e8cc550ba792d4ccc74471d1ca4293aae
> +Setup and configure all loop device parameters using the (third)
> +.BR ioctl (2)
> +argument at once.

I suggest rewording as

[[
Setup and configure all loop device parameters in a single step using
the (third)
.BR ioctl (2)
argument.
]]

> +This argument is a pointer to

s/to/to a/

> +.I loop_config
> +structure, defined in
> +.I <linux/loop.h>
> +as:
> +.IP
> +.in +4n
> +.EX
> +struct loop_config {
> +     __u32               fd;
> +     __u32               block_size;
> +     struct loop_info64  info;
> +     __u64               __reserved[8];
> +};
> +.EE
> +.in
> +.IP
> +In addition to doing what
> +.BR LOOP_SET_STATUS
> +can do,
> +.BR LOOP_CONFIGURE
> +can also be used to set the correct block size immediately
> +by setting loop_config.block_size. Explicitly request
> +direct I/O mode by setting
> +.BR LO_FLAGS_DIRECT_IO
> +in loop_config.info.lo_flags. Explicitly request read-only
> +mode by setting
> +.BR LO_FLAGS_READ_ONLY
> +in loop_config.info.lo_flags.

On an earlier version of this patch, I commented that this piece is
unclear (the language is difficult to understand). If I correctly
guess what you are trying to say, then I think it would be better
worded as something like:

[[
In addition to doing what
.BR LOOP_SET_STATUS
can do,
.BR LOOP_CONFIGURE
can also be used to the following:
.IP * 2
Set the correct block size immediately by setting
.IR loop_config.block_size ;
.IP *
explicitly request direct I/O mode by setting
.BR LO_FLAGS_DIRECT_IO
in loop_config.info.lo_flags;
.IP *
explicitly request read-only mode by setting
.BR LO_FLAGS_READ_ONLY
in
.IR loop_config.info.lo_flags .
]]

In other words, I think you mean to say that LOOP_CONFIGURE can be used
to any one of the things in the list, right?

If I'm right, could you redraft the patch please. If I'm not right, I
think we better discuss some more how the text should look :-).

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: AW: AW: [PATCH v2 2/3] loop.4: add some details about lo_flag

[Yang Xu]

Hi Michael


> Hello Yang Xu,
> 
> On Tue, 8 Sep 2020 at 11:55, Yang Xu <xuyang2018.jy@cn.fujitsu.com> wrote:
>>
>> Hi  Walter
>>
>>
>>> ok, i understand now (i hope).
>>>
>>> maybe this version is more clear:
>>>
>>> The LOOP_SET_STATUS can neither set the
>>> .B lo_flags
>>> LO_FLAGS_READ_ONLY  nor the LO_FLAGS_DIRECT_IO
>>> because they are exclusively set from kernel.
>> Sorry for the late reply.
>> I think it is better.
>> Thanks.
>> Let's wait for Michael's review.
> 
> I think it is probably better as Walter suggests. Could you redraft
> the patch please?
Will do it on v3.
> 
> Thanks,
> 
> Michael
> 
> 
> 
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/
> 
> 

Re: [PATCH v2 3/3] loop.4: Document loop_configure ioctl

[Yang Xu]

Hi Michael


> Hello Yang Xu,
> 
> On 8/6/20 11:48 AM, Yang Xu wrote:
>> Signed-off-by: Yang Xu <xuyang2018.jy@cn.fujitsu.com>
>> ---
>>   man4/loop.4 | 35 +++++++++++++++++++++++++++++++++++
>>   1 file changed, 35 insertions(+)
>>
>> diff --git a/man4/loop.4 b/man4/loop.4
>> index 41abe0122..44dfd9a8c 100644
>> --- a/man4/loop.4
>> +++ b/man4/loop.4
>> @@ -181,6 +181,41 @@ This value must be a power of two in the range
>>   otherwise, an
>>   .B EINVAL
>>   error results.
>> +.TP
>> +.BR LOOP_CONFIGURE " (since Linux 5.8)"
>> +.\" commit 3448914e8cc550ba792d4ccc74471d1ca4293aae
>> +Setup and configure all loop device parameters using the (third)
>> +.BR ioctl (2)
>> +argument at once.
> 
> I suggest rewording as
> 
> [[
> Setup and configure all loop device parameters in a single step using
> the (third)
> .BR ioctl (2)
> argument.
> ]]
> 
>> +This argument is a pointer to
> 
> s/to/to a/
> Will do these on v3.
>> +.I loop_config
>> +structure, defined in
>> +.I <linux/loop.h>
>> +as:
>> +.IP
>> +.in +4n
>> +.EX
>> +struct loop_config {
>> +     __u32               fd;
>> +     __u32               block_size;
>> +     struct loop_info64  info;
>> +     __u64               __reserved[8];
>> +};
>> +.EE
>> +.in
>> +.IP
>> +In addition to doing what
>> +.BR LOOP_SET_STATUS
>> +can do,
>> +.BR LOOP_CONFIGURE
>> +can also be used to set the correct block size immediately
>> +by setting loop_config.block_size. Explicitly request
>> +direct I/O mode by setting
>> +.BR LO_FLAGS_DIRECT_IO
>> +in loop_config.info.lo_flags. Explicitly request read-only
>> +mode by setting
>> +.BR LO_FLAGS_READ_ONLY
>> +in loop_config.info.lo_flags.
> 
> On an earlier version of this patch, I commented that this piece is
> unclear (the language is difficult to understand). If I correctly
> guess what you are trying to say, then I think it would be better
> worded as something like:
> 
> [[
> In addition to doing what
> .BR LOOP_SET_STATUS
> can do,
> .BR LOOP_CONFIGURE
> can also be used to the following:
> .IP * 2
> Set the correct block size immediately by setting
> .IR loop_config.block_size ;
> .IP *
> explicitly request direct I/O mode by setting
> .BR LO_FLAGS_DIRECT_IO
> in loop_config.info.lo_flags;
> .IP *
> explicitly request read-only mode by setting
> .BR LO_FLAGS_READ_ONLY
> in
> .IR loop_config.info.lo_flags .
> ]]
> 
> In other words, I think you mean to say that LOOP_CONFIGURE can be used
> to any one of the things in the list, right?
Yes. you are right.
> 
> If I'm right, could you redraft the patch please. If I'm not right, I
> think we better discuss some more how the text should look :-).Will do it on v3.
> 
> Thanks,
> 
> Michael
>