Linux-man Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH] move_pages.2: Returning positive value is a new error case
@ 2020-01-29 18:30 Yang Shi
  2020-01-29 18:58 ` Michal Hocko
  2020-01-31 10:49 ` David Hildenbrand
  0 siblings, 2 replies; 6+ messages in thread
From: Yang Shi @ 2020-01-29 18:30 UTC (permalink / raw)
  To: mhocko, mtk.manpages, akpm
  Cc: yang.shi, linux-man, linux-api, linux-mm, linux-kernel

Since commit a49bd4d71637 ("mm, numa: rework do_pages_move"),
the semantic of move_pages() has changed to return the number of
non-migrated pages if they were result of a non-fatal reasons (usually a
busy page).  This was an unintentional change that hasn't been noticed
except for LTP tests which checked for the documented behavior.

There are two ways to go around this change.  We can even get back to the
original behavior and return -EAGAIN whenever migrate_pages is not able
to migrate pages due to non-fatal reasons.  Another option would be to
simply continue with the changed semantic and extend move_pages
documentation to clarify that -errno is returned on an invalid input or
when migration simply cannot succeed (e.g. -ENOMEM, -EBUSY) or the
number of pages that couldn't have been migrated due to ephemeral
reasons (e.g. page is pinned or locked for other reasons).

We decided to keep the second option in kernel because this behavior is in
place for some time without anybody complaining and possibly new users
depending on it.  Also it allows to have a slightly easier error handling
as the caller knows that it is worth to retry when err > 0.

Update man pages to reflect the new semantic.

Cc: Michal Hocko <mhocko@suse.com>
Cc: Michael Kerrisk <mtk.manpages@gmail.com>
Signed-off-by: Yang Shi <yang.shi@linux.alibaba.com>
---
 man2/move_pages.2 | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/man2/move_pages.2 b/man2/move_pages.2
index 1bf1053..c6cf3f8 100644
--- a/man2/move_pages.2
+++ b/man2/move_pages.2
@@ -164,9 +164,13 @@ returns zero.
 .\" do the right thing?
 On error, it returns \-1, and sets
 .I errno
-to indicate the error.
+to indicate the error. Or positive value to report the number of
+non-migrated pages.
 .SH ERRORS
 .TP
+.B Positive value
+The number of non-migrated pages if they were result of a non-fatal
+reasons since version 4.17.
 .B E2BIG
 Too many pages to move.
 Since Linux 2.6.29,
-- 
1.8.3.1


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH] move_pages.2: Returning positive value is a new error case
  2020-01-29 18:30 [PATCH] move_pages.2: Returning positive value is a new error case Yang Shi
@ 2020-01-29 18:58 ` Michal Hocko
  2020-01-29 19:05   ` Yang Shi
  2020-01-31 10:49 ` David Hildenbrand
  1 sibling, 1 reply; 6+ messages in thread
From: Michal Hocko @ 2020-01-29 18:58 UTC (permalink / raw)
  To: Yang Shi; +Cc: mtk.manpages, akpm, linux-man, linux-api, linux-mm, linux-kernel

On Thu 30-01-20 02:30:32, Yang Shi wrote:
> Since commit a49bd4d71637 ("mm, numa: rework do_pages_move"),
> the semantic of move_pages() has changed to return the number of
> non-migrated pages if they were result of a non-fatal reasons (usually a
> busy page).  This was an unintentional change that hasn't been noticed
> except for LTP tests which checked for the documented behavior.
> 
> There are two ways to go around this change.  We can even get back to the
> original behavior and return -EAGAIN whenever migrate_pages is not able
> to migrate pages due to non-fatal reasons.  Another option would be to
> simply continue with the changed semantic and extend move_pages
> documentation to clarify that -errno is returned on an invalid input or
> when migration simply cannot succeed (e.g. -ENOMEM, -EBUSY) or the
> number of pages that couldn't have been migrated due to ephemeral
> reasons (e.g. page is pinned or locked for other reasons).
> 
> We decided to keep the second option in kernel because this behavior is in
> place for some time without anybody complaining and possibly new users
> depending on it.  Also it allows to have a slightly easier error handling
> as the caller knows that it is worth to retry when err > 0.
> 
> Update man pages to reflect the new semantic.

Thanks a lot! Looks good to me. I would just add a note that it is
generally recommended to pre-initialize status array by -1 to have a
reliable way to check which pages have been migrated. The man page says
"The array contains valid values only if move_pages() did not return an
error."

I would just add. "Pre initialization of the array to -1 or similar
value which cannot represent a real numa node could help to identify
pages that have been migrated".

> Cc: Michal Hocko <mhocko@suse.com>
> Cc: Michael Kerrisk <mtk.manpages@gmail.com>
> Signed-off-by: Yang Shi <yang.shi@linux.alibaba.com>

Acked-by: Michal Hocko <mhocko@suse.com>

> ---
>  man2/move_pages.2 | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
> 
> diff --git a/man2/move_pages.2 b/man2/move_pages.2
> index 1bf1053..c6cf3f8 100644
> --- a/man2/move_pages.2
> +++ b/man2/move_pages.2
> @@ -164,9 +164,13 @@ returns zero.
>  .\" do the right thing?
>  On error, it returns \-1, and sets
>  .I errno
> -to indicate the error.
> +to indicate the error. Or positive value to report the number of
> +non-migrated pages.
>  .SH ERRORS
>  .TP
> +.B Positive value
> +The number of non-migrated pages if they were result of a non-fatal
> +reasons since version 4.17.
>  .B E2BIG
>  Too many pages to move.
>  Since Linux 2.6.29,
> -- 
> 1.8.3.1

-- 
Michal Hocko
SUSE Labs

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH] move_pages.2: Returning positive value is a new error case
  2020-01-29 18:58 ` Michal Hocko
@ 2020-01-29 19:05   ` Yang Shi
  2020-01-29 19:11     ` Michal Hocko
  0 siblings, 1 reply; 6+ messages in thread
From: Yang Shi @ 2020-01-29 19:05 UTC (permalink / raw)
  To: Michal Hocko
  Cc: mtk.manpages, akpm, linux-man, linux-api, linux-mm, linux-kernel



On 1/29/20 10:58 AM, Michal Hocko wrote:
> On Thu 30-01-20 02:30:32, Yang Shi wrote:
>> Since commit a49bd4d71637 ("mm, numa: rework do_pages_move"),
>> the semantic of move_pages() has changed to return the number of
>> non-migrated pages if they were result of a non-fatal reasons (usually a
>> busy page).  This was an unintentional change that hasn't been noticed
>> except for LTP tests which checked for the documented behavior.
>>
>> There are two ways to go around this change.  We can even get back to the
>> original behavior and return -EAGAIN whenever migrate_pages is not able
>> to migrate pages due to non-fatal reasons.  Another option would be to
>> simply continue with the changed semantic and extend move_pages
>> documentation to clarify that -errno is returned on an invalid input or
>> when migration simply cannot succeed (e.g. -ENOMEM, -EBUSY) or the
>> number of pages that couldn't have been migrated due to ephemeral
>> reasons (e.g. page is pinned or locked for other reasons).
>>
>> We decided to keep the second option in kernel because this behavior is in
>> place for some time without anybody complaining and possibly new users
>> depending on it.  Also it allows to have a slightly easier error handling
>> as the caller knows that it is worth to retry when err > 0.
>>
>> Update man pages to reflect the new semantic.
> Thanks a lot! Looks good to me. I would just add a note that it is
> generally recommended to pre-initialize status array by -1 to have a
> reliable way to check which pages have been migrated. The man page says
> "The array contains valid values only if move_pages() did not return an
> error."
>
> I would just add. "Pre initialization of the array to -1 or similar
> value which cannot represent a real numa node could help to identify
> pages that have been migrated".

Sure. Adding this note right after the explanation of positive value 
error seems fine?

>
>> Cc: Michal Hocko <mhocko@suse.com>
>> Cc: Michael Kerrisk <mtk.manpages@gmail.com>
>> Signed-off-by: Yang Shi <yang.shi@linux.alibaba.com>
> Acked-by: Michal Hocko <mhocko@suse.com>
>
>> ---
>>   man2/move_pages.2 | 6 +++++-
>>   1 file changed, 5 insertions(+), 1 deletion(-)
>>
>> diff --git a/man2/move_pages.2 b/man2/move_pages.2
>> index 1bf1053..c6cf3f8 100644
>> --- a/man2/move_pages.2
>> +++ b/man2/move_pages.2
>> @@ -164,9 +164,13 @@ returns zero.
>>   .\" do the right thing?
>>   On error, it returns \-1, and sets
>>   .I errno
>> -to indicate the error.
>> +to indicate the error. Or positive value to report the number of
>> +non-migrated pages.
>>   .SH ERRORS
>>   .TP
>> +.B Positive value
>> +The number of non-migrated pages if they were result of a non-fatal
>> +reasons since version 4.17.
>>   .B E2BIG
>>   Too many pages to move.
>>   Since Linux 2.6.29,
>> -- 
>> 1.8.3.1


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH] move_pages.2: Returning positive value is a new error case
  2020-01-29 19:05   ` Yang Shi
@ 2020-01-29 19:11     ` Michal Hocko
  0 siblings, 0 replies; 6+ messages in thread
From: Michal Hocko @ 2020-01-29 19:11 UTC (permalink / raw)
  To: Yang Shi; +Cc: mtk.manpages, akpm, linux-man, linux-api, linux-mm, linux-kernel

On Wed 29-01-20 11:05:11, Yang Shi wrote:
> 
> 
> On 1/29/20 10:58 AM, Michal Hocko wrote:
> > On Thu 30-01-20 02:30:32, Yang Shi wrote:
> > > Since commit a49bd4d71637 ("mm, numa: rework do_pages_move"),
> > > the semantic of move_pages() has changed to return the number of
> > > non-migrated pages if they were result of a non-fatal reasons (usually a
> > > busy page).  This was an unintentional change that hasn't been noticed
> > > except for LTP tests which checked for the documented behavior.
> > > 
> > > There are two ways to go around this change.  We can even get back to the
> > > original behavior and return -EAGAIN whenever migrate_pages is not able
> > > to migrate pages due to non-fatal reasons.  Another option would be to
> > > simply continue with the changed semantic and extend move_pages
> > > documentation to clarify that -errno is returned on an invalid input or
> > > when migration simply cannot succeed (e.g. -ENOMEM, -EBUSY) or the
> > > number of pages that couldn't have been migrated due to ephemeral
> > > reasons (e.g. page is pinned or locked for other reasons).
> > > 
> > > We decided to keep the second option in kernel because this behavior is in
> > > place for some time without anybody complaining and possibly new users
> > > depending on it.  Also it allows to have a slightly easier error handling
> > > as the caller knows that it is worth to retry when err > 0.
> > > 
> > > Update man pages to reflect the new semantic.
> > Thanks a lot! Looks good to me. I would just add a note that it is
> > generally recommended to pre-initialize status array by -1 to have a
> > reliable way to check which pages have been migrated. The man page says
> > "The array contains valid values only if move_pages() did not return an
> > error."
> > 
> > I would just add. "Pre initialization of the array to -1 or similar
> > value which cannot represent a real numa node could help to identify
> > pages that have been migrated".
> 
> Sure. Adding this note right after the explanation of positive value error
> seems fine?

I would just follow up on the existing note about valid values.

-- 
Michal Hocko
SUSE Labs

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH] move_pages.2: Returning positive value is a new error case
  2020-01-29 18:30 [PATCH] move_pages.2: Returning positive value is a new error case Yang Shi
  2020-01-29 18:58 ` Michal Hocko
@ 2020-01-31 10:49 ` David Hildenbrand
  2020-01-31 19:40   ` Yang Shi
  1 sibling, 1 reply; 6+ messages in thread
From: David Hildenbrand @ 2020-01-31 10:49 UTC (permalink / raw)
  To: Yang Shi, mhocko, mtk.manpages, akpm
  Cc: linux-man, linux-api, linux-mm, linux-kernel

On 29.01.20 19:30, Yang Shi wrote:
> Since commit a49bd4d71637 ("mm, numa: rework do_pages_move"),
> the semantic of move_pages() has changed to return the number of
> non-migrated pages if they were result of a non-fatal reasons (usually a
> busy page).  This was an unintentional change that hasn't been noticed
> except for LTP tests which checked for the documented behavior.
> 
> There are two ways to go around this change.  We can even get back to the
> original behavior and return -EAGAIN whenever migrate_pages is not able
> to migrate pages due to non-fatal reasons.  Another option would be to
> simply continue with the changed semantic and extend move_pages
> documentation to clarify that -errno is returned on an invalid input or
> when migration simply cannot succeed (e.g. -ENOMEM, -EBUSY) or the
> number of pages that couldn't have been migrated due to ephemeral
> reasons (e.g. page is pinned or locked for other reasons).
> 
> We decided to keep the second option in kernel because this behavior is in
> place for some time without anybody complaining and possibly new users
> depending on it.  Also it allows to have a slightly easier error handling
> as the caller knows that it is worth to retry when err > 0.
> 
> Update man pages to reflect the new semantic.
> 
> Cc: Michal Hocko <mhocko@suse.com>
> Cc: Michael Kerrisk <mtk.manpages@gmail.com>
> Signed-off-by: Yang Shi <yang.shi@linux.alibaba.com>
> ---
>  man2/move_pages.2 | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
> 
> diff --git a/man2/move_pages.2 b/man2/move_pages.2
> index 1bf1053..c6cf3f8 100644
> --- a/man2/move_pages.2
> +++ b/man2/move_pages.2
> @@ -164,9 +164,13 @@ returns zero.
>  .\" do the right thing?
>  On error, it returns \-1, and sets
>  .I errno
> -to indicate the error.
> +to indicate the error. Or positive value to report the number of
> +non-migrated pages.

"If a positive value is returned, it's the number of non-migrated pages".

>  .SH ERRORS
>  .TP
> +.B Positive value
> +The number of non-migrated pages if they were result of a non-fatal
> +reasons since version 4.17.

s/result/the result/ ?

s/a reasons/reasons/ ?

s/since version 4.17/(since 4.17)/ ?

>  .B E2BIG
>  Too many pages to move.
>  Since Linux 2.6.29,
> 


-- 
Thanks,

David / dhildenb


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH] move_pages.2: Returning positive value is a new error case
  2020-01-31 10:49 ` David Hildenbrand
@ 2020-01-31 19:40   ` Yang Shi
  0 siblings, 0 replies; 6+ messages in thread
From: Yang Shi @ 2020-01-31 19:40 UTC (permalink / raw)
  To: David Hildenbrand, mhocko, mtk.manpages, akpm
  Cc: linux-man, linux-api, linux-mm, linux-kernel



On 1/31/20 2:49 AM, David Hildenbrand wrote:
> On 29.01.20 19:30, Yang Shi wrote:
>> Since commit a49bd4d71637 ("mm, numa: rework do_pages_move"),
>> the semantic of move_pages() has changed to return the number of
>> non-migrated pages if they were result of a non-fatal reasons (usually a
>> busy page).  This was an unintentional change that hasn't been noticed
>> except for LTP tests which checked for the documented behavior.
>>
>> There are two ways to go around this change.  We can even get back to the
>> original behavior and return -EAGAIN whenever migrate_pages is not able
>> to migrate pages due to non-fatal reasons.  Another option would be to
>> simply continue with the changed semantic and extend move_pages
>> documentation to clarify that -errno is returned on an invalid input or
>> when migration simply cannot succeed (e.g. -ENOMEM, -EBUSY) or the
>> number of pages that couldn't have been migrated due to ephemeral
>> reasons (e.g. page is pinned or locked for other reasons).
>>
>> We decided to keep the second option in kernel because this behavior is in
>> place for some time without anybody complaining and possibly new users
>> depending on it.  Also it allows to have a slightly easier error handling
>> as the caller knows that it is worth to retry when err > 0.
>>
>> Update man pages to reflect the new semantic.
>>
>> Cc: Michal Hocko <mhocko@suse.com>
>> Cc: Michael Kerrisk <mtk.manpages@gmail.com>
>> Signed-off-by: Yang Shi <yang.shi@linux.alibaba.com>
>> ---
>>   man2/move_pages.2 | 6 +++++-
>>   1 file changed, 5 insertions(+), 1 deletion(-)
>>
>> diff --git a/man2/move_pages.2 b/man2/move_pages.2
>> index 1bf1053..c6cf3f8 100644
>> --- a/man2/move_pages.2
>> +++ b/man2/move_pages.2
>> @@ -164,9 +164,13 @@ returns zero.
>>   .\" do the right thing?
>>   On error, it returns \-1, and sets
>>   .I errno
>> -to indicate the error.
>> +to indicate the error. Or positive value to report the number of
>> +non-migrated pages.
> "If a positive value is returned, it's the number of non-migrated pages".
>
>>   .SH ERRORS
>>   .TP
>> +.B Positive value
>> +The number of non-migrated pages if they were result of a non-fatal
>> +reasons since version 4.17.
> s/result/the result/ ?
>
> s/a reasons/reasons/ ?
>
> s/since version 4.17/(since 4.17)/ ?

Thanks. Will fix in new version.

>
>>   .B E2BIG
>>   Too many pages to move.
>>   Since Linux 2.6.29,
>>
>


^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, back to index

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-01-29 18:30 [PATCH] move_pages.2: Returning positive value is a new error case Yang Shi
2020-01-29 18:58 ` Michal Hocko
2020-01-29 19:05   ` Yang Shi
2020-01-29 19:11     ` Michal Hocko
2020-01-31 10:49 ` David Hildenbrand
2020-01-31 19:40   ` Yang Shi

Linux-man Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-man/0 linux-man/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-man linux-man/ https://lore.kernel.org/linux-man \
		linux-man@vger.kernel.org
	public-inbox-index linux-man

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-man


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git