man2/cacheflush.2

   1 .\" Written by Ralf Baechle (ralf@waldorf-gmbh.de),
   2 .\" Copyright (c) 1994, 1995 Waldorf GMBH
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   5 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\"
  10 .\" The GNU General Public License's references to "object code"
  11 .\" and "executables" are to be interpreted as the output of any
  12 .\" document formatting or typesetting system, including
  13 .\" intermediate and printed output.
  14 .\"
  15 .\" This manual is distributed in the hope that it will be useful,
  16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\" GNU General Public License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public
  21 .\" License along with this manual; if not, see
  22 .\" <http://www.gnu.org/licenses/>.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH CACHEFLUSH 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 cacheflush \- flush contents of instruction and/or data cache
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <sys/cachectl.h>
  31 .PP
  32 .BI "int cacheflush(void *" addr ", int "nbytes ", int "cache );
  33 .fi
  34 .PP
  35 .IR Note :
  36 On some architectures,
  37 there is no glibc wrapper for this system call; see NOTES.
  38 .SH DESCRIPTION
  39 .BR cacheflush ()
  40 flushes the contents of the indicated cache(s) for the
  41 user addresses in the range
  42 .I addr
  43 to
  44 .IR (addr+nbytes\-1) .
  45 .I cache
  46 may be one of:
  47 .TP
  48 .B ICACHE
  49 Flush the instruction cache.
  50 .TP
  51 .B DCACHE
  52 Write back to memory and invalidate the affected valid cache lines.
  53 .TP
  54 .B BCACHE
  55 Same as
  56 .BR (ICACHE|DCACHE) .
  57 .SH RETURN VALUE
  58 .BR cacheflush ()
  59 returns 0 on success.
  60 On error, it returns \-1 and sets
  61 .I errno
  62 to indicate the error.
  63 .SH ERRORS
  64 .TP
  65 .B EFAULT
  66 Some or all of the address range
  67 .I addr
  68 to
  69 .I (addr+nbytes\-1)
  70 is not accessible.
  71 .TP
  72 .B EINVAL
  73 .I cache
  74 is not one of
  75 .BR ICACHE ,
  76 .BR DCACHE ,
  77 or
  78 .BR BCACHE
  79 (but see BUGS).
  80 .SH CONFORMING TO
  81 Historically, this system call was available on all MIPS UNIX variants
  82 including RISC/os, IRIX, Ultrix, NetBSD, OpenBSD, and FreeBSD
  83 (and also on some non-UNIX MIPS operating systems), so that
  84 the existence of this call in MIPS operating systems is a de-facto
  85 standard.
  86 .SS Caveat
  87 .BR cacheflush ()
  88 should not be used in programs intended to be portable.
  89 On Linux, this call first appeared on the MIPS architecture,
  90 but nowadays, Linux provides a
  91 .BR cacheflush ()
  92 system call on some other architectures, but with different arguments.
  93 .SH NOTES
  94 .SS Architecture-specific variants
  95 Glibc provides a wrapper for this system call,
  96 with the prototype shown in SYNOPSIS,
  97 for the following architectures:
  98 ARC, CSKY, MIPS, and NIOS2.
  99 .PP
 100 On some other architectures,
 101 Linux provides this system call, with different arguments:
 102 .TP
 103 M68K:
 104 .nf
 105 .BI "int cacheflush(unsigned long " addr ", int " scope ", int " cache ,
 106 .BI "               unsigned long " len );
 107 .fi
 108 .TP
 109 SH:
 110 .nf
 111 .BI "int cacheflush(unsigned long " addr ", unsigned long " len ", int " op );
 112 .fi
 113 .TP
 114 NDS32:
 115 .nf
 116 .BI "int cacheflush(unsigned int " start ", unsigned int " end ", int " cache );
 117 .fi
 118 .PP
 119 On the above architectures,
 120 glibc does not provide a wrapper for this system call; call it using
 121 .BR syscall (2).
 122 .SS GCC alternative
 123 Unless you need the finer grained control that this system call provides,
 124 you probably want to use the GCC built-in function
 125 .BR __builtin___clear_cache (),
 126 which provides a portable interface
 127 across platforms supported by GCC and compatible compilers:
 128 .PP
 129 .in +4n
 130 .EX
 131 .BI "void __builtin___clear_cache(void *" begin ", void *" end );
 132 .EE
 133 .in
 134 .PP
 135 On platforms that don't require instruction cache flushes,
 136 .BR __builtin___clear_cache ()
 137 has no effect.
 138 .PP
 139 .IR Note :
 140 On some GCC-compatible compilers,
 141 the prototype for this built-in function uses
 142 .I char *
 143 instead of
 144 .I void *
 145 for the parameters.
 146 .SH BUGS
 147 Linux kernels older than version 2.6.11 ignore the
 148 .I addr
 149 and
 150 .I nbytes
 151 arguments, making this function fairly expensive.
 152 Therefore, the whole cache is always flushed.
 153 .PP
 154 This function always behaves as if
 155 .BR BCACHE
 156 has been passed for the
 157 .I cache
 158 argument and does not do any error checking on the
 159 .I cache
 160 argument.