lib/libc/arm/gen/arm_sync_icache.2

   1 .\" Copyright (c) 2019 Ian Lepore <ian@FreeBSD.org>
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  13 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  14 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  15 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  16 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  17 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  18 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  19 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  20 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  21 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  22 .\" SUCH DAMAGE.
  23 .\"
  24 .\" $FreeBSD$
  25 .\"
  26 .Dd July 10, 2019
  27 .Dt ARM_sync_icache 2
  28 .Os
  29 .Sh NAME
  30 .Nm arm_sync_icache
  31 .Nd synchronize the data and instruction caches
  32 .Sh LIBRARY
  33 .Lb libc
  34 .Sh SYNOPSIS
  35 .In machine/sysarch.h
  36 .Ft int
  37 .Fn arm_sync_icache "u_int addr" "int len"
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 system call synchronizes the contents of any data and instructions caches
  42 with the contents of main memory for the given range.
  43 Use this after loading executable code or modifying existing code in memory,
  44 before attempting to execute that code.
  45 .Pp
  46 The
  47 .Va addr
  48 and
  49 .Va len
  50 arguments do not need to be aligned to any particular boundary, but
  51 cache operations will affect entire cache lines, even those which are only
  52 partially overlapped by the given range.
  53 .Pp
  54 This takes one or more of the following actions, depending on the requirements
  55 of the hardware:
  56 .Bl -bullet
  57 .It
  58 Write dirty data cache lines within the range back to main memory.
  59 .It
  60 Invalidate existing instruction cache contents for the range.
  61 .It
  62 Invalidate branch prediction caches for the range.
  63 .El
  64 .Pp
  65 On hardware which supports multiple synchronization points for cache
  66 operations, the caches are maintained to the point of unification,
  67 making the data in the range coherent amongst all cores.
  68 .Sh RETURN VALUES
  69 The
  70 .Nm
  71 system call always returns 0.
  72 .Sh ERRORS
  73 If a call refers to memory which the calling process does not have rights
  74 to access, or if the
  75 .Va len
  76 argument is negative, a SIGSEGV signal is delivered to the calling thread.
  77 .Sh AUTHORS
  78 This man page was written by
  79 .An Ian Lepore .