lib/libc/arm/gen/arm_drain_writebuf.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_DRAIN_WRITEBUF 2
  28 .Os
  29 .Sh NAME
  30 .Nm arm_drain_writebuf
  31 .Nd drain pending writes from cores and caches
  32 .Sh LIBRARY
  33 .Lb libc
  34 .Sh SYNOPSIS
  35 .In machine/sysarch.h
  36 .Ft int
  37 .Fn arm_drain_writebuf void
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 system call causes all pending writes from ARM cores and caches to be
  42 written out to main memory or memory-mapped I/O registers.
  43 Not all hardware supports buffered writes; on such systems the
  44 .Nm
  45 function is a no-op.
  46 .Pp
  47 On ARMv5 systems, this executes a cp15 coprocessor
  48 .Dq drain write buffer
  49 operation.
  50 On ARMv6 and ARMv7 systems, this executes a
  51 .Dq DSB SY
  52 synchronization barrier, followed by an L2 cache drain on
  53 systems where the DSB does not include L2 automatically.
  54 .Pp
  55 .Nm
  56 attempts to wait for the drain operation to complete, but cannot
  57 guarantee the writes have reached their ultimate destination on all hardware.
  58 For example, on an ARMv7 system,
  59 .Nm
  60 tells the L2 cache controller to drain its buffers, and it waits until
  61 the controller indicates that operation is complete.
  62 However, all the L2 controller knows is that the data was accepted for
  63 delivery by the AXI bus.
  64 If the ultimate destination of the write is a device on a subordinate
  65 bus connected to the AXI bus, more buffering or other delays may occur
  66 on that subordinate bus.
  67 The only way to be certain a pending write has reached its
  68 ultimate destination is to issue a read from that destination after
  69 .Nm
  70 returns.
  71 .Sh RETURN VALUES
  72 The
  73 .Nm
  74 system call cannot fail, and always returns 0.
  75 .Sh AUTHORS
  76 This man page was written by
  77 .An Ian Lepore .