[patch] removing EINVAL error from cacheflush() man page

[patch] removing EINVAL error from cacheflush() man page

[Maxin John]

Hi,

The cacheflush() man page states that cacheflush() will set  EINVAL if
cache parameter is not one of ICACHE, DCACHE, or BCACHE. I have tried
to verify this behavior in linux-2.6.29.1 and observed that this check
is not implemented in the kernel. Based on this observation, I have
proposed one patch to LKML and the details are available in the below
listed URL:

http://lkml.org/lkml/2009/4/9/203

At first, this patch
(mips-cacheflush-system-call-not-returning-einval-checkpatch-fixes.patch)
 was added to the -mm tree and later dropped. Mr. Ralf Baechle and Mr.
Andrew Morton have expressed their views on why it was dropped.

Ralf Baechle :
"There is no point in checking the arguments which are being ignored anyway."

Andrew Morton:
"
> There is no point in checking the arguments which are being ignored
> anyway.
>
Well, there _is_ a point.  So that people don't write buggy userspace
which "seems" to work, but which will fail if at some time in the
future we _do_ start using the argument.  ie: for
future-compatibility.
But it's too late to fix that up now."

The reference to -EINVAL  is present from the very first release of
cacheflush() man page :
man-pages-1.10.tar.gz which was released on Jan 15  1996.
Thanks to Mr. Michael Kerrisk for providing the URL which helped me to
trace out the  history of cacheflush() man page:
ftp://ftp.win.tue.nl/pub/linux-local/manpages.archive/

Based on this, I think , we should modify the cacheflush() man page.

Signed-off-by: Maxin B. John <maxin.john-qujY0cBTTHtBDgjK7y7TUQ@public.gmane.org>
--------
diff -uNr man-pages-3.21-orig/man2/cacheflush.2 man-pages-3.21/man2/cacheflush.2
--- man-pages-3.21-orig/man2/cacheflush.2       2009-04-15
21:35:32.000000000 +0530
+++ man-pages-3.21/man2/cacheflush.2    2009-05-07 15:06:31.350544848 +0530
@@ -63,14 +63,6 @@
 to
 .I (addr+nbytes-1)
 is not accessible.
-.TP
-.B EINVAL
-.I cache
-is not one of
-.BR ICACHE ,
-.BR DCACHE ,
-or
-.BR BCACHE .
 .SH CONFORMING TO
 This Linux-specific system call is only available on MIPS based systems.
 .\" FIXME This system call was only on MIPS back in 1.2 days, but
~
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] removing EINVAL error from cacheflush() man page

[Ralf Baechle]

On Thu, May 07, 2009 at 03:10:19PM +0530, Maxin John wrote:

The man page indeed deserved some polishing 15 years after I wrote it.
Guess I have to thank Maxin for kicking me to finally do that :-)

Unlike to his patch I've chosen to document the actual behaviour in the
BUGS section and elaborated on the history of the call on MIPS and
differences on other architectures.  In this context I found it preferable
to not delete the section about error returns for invalid cache args.

  Ralf

--- cacheflush.2.orig	2009-05-07 11:12:34.000000000 +0100
+++ cacheflush.2	2009-05-07 11:49:34.000000000 +0100
@@ -1,5 +1,6 @@
-.\" Written by Ralf Baechle (ralf-NfzSNkFSoiNlEiWPh9xO2Q@public.gmane.org),
+.\" Written by Ralf Baechle (ralf-6z/3iImG2C8G8FEW9MqTrA@public.gmane.org),
 .\" Copyright (c) 1994, 1995 Waldorf GMBH
+.\" Copyright (c) 2009 Wind River Systems
 .\"
 .\" This is free documentation; you can redistribute it and/or
 .\" modify it under the terms of the GNU General Public License as
@@ -21,7 +22,7 @@
 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
 .\" USA.
 .\"
-.TH CACHEFLUSH 2 2007-05-26 "Linux" "Linux Programmer's Manual"
+.TH CACHEFLUSH 2 2009-05-07 "Linux" "Linux Programmer's Manual"
 .SH NAME
 cacheflush \- flush contents of instruction and/or data cache
 .SH SYNOPSIS
@@ -73,18 +74,35 @@
 .BR BCACHE .
 .SH CONFORMING TO
 This Linux-specific system call is only available on MIPS based systems.
-.\" FIXME This system call was only on MIPS back in 1.2 days, but
-.\" by now it is on a number of other architectures (but not i386).
-.\" Investigate the details and update this page.
-It should not be used in programs intended to be portable.
+Historically the system calls was available on all MIPS UNIX variants
+including RISC/os, IRIX, Ultrix, NetBSD, OpenBSD and FreeBSD as well as
+some non-UNIX MIPS operating systems have implemented
+.BR cacheflush ()
+that the existence of this call in MIPS operating systems is a de-facto
+standard.
+.SH CAVEAT
+.BR cacheflush ()
+should not be used in programs intended to be portable.
+Linux on several other architectures does support a
+.BR cacheflush ()
+systems call but with different arguments.
 .\" Irix 6.5 appears to have a cacheflush() syscall -- mtk
 .SH BUGS
-The current implementation ignores the
+Kernels older than 2.6.11 ignores the
 .I addr
 and
 .I nbytes
 arguments.
-Therefore, the whole cache is always flushed.
+Therefore, the whole cache is always flushed making this function fairly
+expensive.
+
+This function is always behaving as if
+.BR BCACHE
+has been passed for the
+.I cache
+argument and does not do any error checking on the
+.I cache
+argument.
 .SH COLOPHON
 This page is part of release 3.09 of the Linux
 .I man-pages
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] removing EINVAL error from cacheflush() man page

[Maxin John]

Dear Mr.Ralf,

>On Thu, May 7, 2009 at 4:38 PM, Ralf Baechle <ralf-6z/3iImG2C8G8FEW9MqTrA@public.gmane.org> wrote:
>> On Thu, May 07, 2009 at 03:10:19PM +0530, Maxin John wrote:

Thank you very much for modifying the cacheflush() man page.

>      Linux on several other architectures does support a  cacheflush()  sys-
>       tems call but with different arguments.

In LTP mailing list, Mr.Carmelo has reported that sh4 architecture
supports sys_cacheflush syscall:
http://www.mail-archive.com/ltp-list-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org/msg06430.html

Thanks once again for modifying the man page. The modified
cacheflush() man page makes me happier :)

Best Regards,
Maxin B. John
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] removing EINVAL error from cacheflush() man page

[Michael Kerrisk (man-pages)]

On 05/07/2009 01:08 PM, Ralf Baechle wrote:
> On Thu, May 07, 2009 at 03:10:19PM +0530, Maxin John wrote:
> 
> The man page indeed deserved some polishing 15 years after I wrote it.
> Guess I have to thank Maxin for kicking me to finally do that :-)
> 
> Unlike to his patch I've chosen to document the actual behaviour in the
> BUGS section and elaborated on the history of the call on MIPS and
> differences on other architectures.  In this context I found it preferable
> to not delete the section about error returns for invalid cache args.

Edited this patch, and applied.

Cheers,

Michael


> --- cacheflush.2.orig	2009-05-07 11:12:34.000000000 +0100
> +++ cacheflush.2	2009-05-07 11:49:34.000000000 +0100
> @@ -1,5 +1,6 @@
> -.\" Written by Ralf Baechle (ralf-NfzSNkFSoiNlEiWPh9xO2Q@public.gmane.org),
> +.\" Written by Ralf Baechle (ralf-6z/3iImG2C8G8FEW9MqTrA@public.gmane.org),
>  .\" Copyright (c) 1994, 1995 Waldorf GMBH
> +.\" Copyright (c) 2009 Wind River Systems
>  .\"
>  .\" This is free documentation; you can redistribute it and/or
>  .\" modify it under the terms of the GNU General Public License as
> @@ -21,7 +22,7 @@
>  .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
>  .\" USA.
>  .\"
> -.TH CACHEFLUSH 2 2007-05-26 "Linux" "Linux Programmer's Manual"
> +.TH CACHEFLUSH 2 2009-05-07 "Linux" "Linux Programmer's Manual"
>  .SH NAME
>  cacheflush \- flush contents of instruction and/or data cache
>  .SH SYNOPSIS
> @@ -73,18 +74,35 @@
>  .BR BCACHE .
>  .SH CONFORMING TO
>  This Linux-specific system call is only available on MIPS based systems.
> -.\" FIXME This system call was only on MIPS back in 1.2 days, but
> -.\" by now it is on a number of other architectures (but not i386).
> -.\" Investigate the details and update this page.
> -It should not be used in programs intended to be portable.
> +Historically the system calls was available on all MIPS UNIX variants
> +including RISC/os, IRIX, Ultrix, NetBSD, OpenBSD and FreeBSD as well as
> +some non-UNIX MIPS operating systems have implemented
> +.BR cacheflush ()
> +that the existence of this call in MIPS operating systems is a de-facto
> +standard.
> +.SH CAVEAT
> +.BR cacheflush ()
> +should not be used in programs intended to be portable.
> +Linux on several other architectures does support a
> +.BR cacheflush ()
> +systems call but with different arguments.
>  .\" Irix 6.5 appears to have a cacheflush() syscall -- mtk
>  .SH BUGS
> -The current implementation ignores the
> +Kernels older than 2.6.11 ignores the
>  .I addr
>  and
>  .I nbytes
>  arguments.
> -Therefore, the whole cache is always flushed.
> +Therefore, the whole cache is always flushed making this function fairly
> +expensive.
> +
> +This function is always behaving as if
> +.BR BCACHE
> +has been passed for the
> +.I cache
> +argument and does not do any error checking on the
> +.I cache
> +argument.
>  .SH COLOPHON
>  This page is part of release 3.09 of the Linux
>  .I man-pages
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html