lib/librte_eal/include/generic/rte_prefetch.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2010-2015 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_PREFETCH_H_
   6 #define _RTE_PREFETCH_H_
   7
   8 #include <rte_compat.h>
   9
  10 /**
  11  * @file
  12  *
  13  * Prefetch operations.
  14  *
  15  * This file defines an API for prefetch macros / inline-functions,
  16  * which are architecture-dependent. Prefetching occurs when a
  17  * processor requests an instruction or data from memory to cache
  18  * before it is actually needed, potentially speeding up the execution of the
  19  * program.
  20  */
  21
  22 /**
  23  * Prefetch a cache line into all cache levels.
  24  * @param p
  25  *   Address to prefetch
  26  */
  27 static inline void rte_prefetch0(const volatile void *p);
  28
  29 /**
  30  * Prefetch a cache line into all cache levels except the 0th cache level.
  31  * @param p
  32  *   Address to prefetch
  33  */
  34 static inline void rte_prefetch1(const volatile void *p);
  35
  36 /**
  37  * Prefetch a cache line into all cache levels except the 0th and 1th cache
  38  * levels.
  39  * @param p
  40  *   Address to prefetch
  41  */
  42 static inline void rte_prefetch2(const volatile void *p);
  43
  44 /**
  45  * Prefetch a cache line into all cache levels (non-temporal/transient version)
  46  *
  47  * The non-temporal prefetch is intended as a prefetch hint that processor will
  48  * use the prefetched data only once or short period, unlike the
  49  * rte_prefetch0() function which imply that prefetched data to use repeatedly.
  50  *
  51  * @param p
  52  *   Address to prefetch
  53  */
  54 static inline void rte_prefetch_non_temporal(const volatile void *p);
  55
  56 /**
  57  * @warning
  58  * @b EXPERIMENTAL: this API may change, or be removed, without prior notice
  59  *
  60  * Prefetch a cache line into all cache levels, with intention to write. This
  61  * prefetch variant hints to the CPU that the program is expecting to write to
  62  * the cache line being prefetched.
  63  *
  64  * @param p Address to prefetch
  65  */
  66 __rte_experimental
  67 static inline void
  68 rte_prefetch0_write(const void *p)
  69 {
  70         /* 1 indicates intention to write, 3 sets target cache level to L1. See
  71          * GCC docs where these integer constants are described in more detail:
  72          *  https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html
  73          */
  74         __builtin_prefetch(p, 1, 3);
  75 }
  76
  77 /**
  78  * @warning
  79  * @b EXPERIMENTAL: this API may change, or be removed, without prior notice
  80  *
  81  * Prefetch a cache line into all cache levels, except the 0th, with intention
  82  * to write. This prefetch variant hints to the CPU that the program is
  83  * expecting to write to the cache line being prefetched.
  84  *
  85  * @param p Address to prefetch
  86  */
  87 __rte_experimental
  88 static inline void
  89 rte_prefetch1_write(const void *p)
  90 {
  91         /* 1 indicates intention to write, 2 sets target cache level to L2. See
  92          * GCC docs where these integer constants are described in more detail:
  93          *  https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html
  94          */
  95         __builtin_prefetch(p, 1, 2);
  96 }
  97
  98 /**
  99  * @warning
 100  * @b EXPERIMENTAL: this API may change, or be removed, without prior notice
 101  *
 102  * Prefetch a cache line into all cache levels, except the 0th and 1st, with
 103  * intention to write. This prefetch variant hints to the CPU that the program
 104  * is expecting to write to the cache line being prefetched.
 105  *
 106  * @param p Address to prefetch
 107  */
 108 __rte_experimental
 109 static inline void
 110 rte_prefetch2_write(const void *p)
 111 {
 112         /* 1 indicates intention to write, 1 sets target cache level to L3. See
 113          * GCC docs where these integer constants are described in more detail:
 114          *  https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html
 115          */
 116         __builtin_prefetch(p, 1, 1);
 117 }
 118
 119 /**
 120  * @warning
 121  * @b EXPERIMENTAL: this API may change, or be removed, without prior notice
 122  *
 123  * Demote a cache line to a more distant level of cache from the processor.
 124  * CLDEMOTE hints to hardware to move (demote) a cache line from the closest to
 125  * the processor to a level more distant from the processor. It is a hint and
 126  * not guaranteed. rte_cldemote is intended to move the cache line to the more
 127  * remote cache, where it expects sharing to be efficient and to indicate that
 128  * a line may be accessed by a different core in the future.
 129  *
 130  * @param p
 131  *   Address to demote
 132  */
 133 __rte_experimental
 134 static inline void
 135 rte_cldemote(const volatile void *p);
 136
 137 #endif /* _RTE_PREFETCH_H_ */