Documentation/arm/XScale/cache-lock.txt

   1
   2 Intel's XScale Microarchitecture provides support for locking of data
   3 and instructions into the appropriate caches. This  file provides
   4 an overview of the API that has been developed to take advantage of this
   5 feature from kernel space. Note that there is NO support for user space
   6 cache locking.
   7
   8 For example usage of this code, grab:
   9
  10         ftp://source.mvista.com/pub/xscale/cache-test.c
  11
  12 If you have any questions, comments, patches, etc, please contact me.
  13
  14 Deepak Saxena <dsaxena@mvista.com>
  15
  16 API DESCRIPTION
  17
  18
  19 I. Header File
  20
  21    #include <asm/xscale-lock.h>
  22
  23 II. Cache Capability Discovery
  24
  25    SYNOPSIS
  26
  27    int cache_query(u8 cache_type,
  28                            struct cache_capabilities *pcache);
  29
  30    struct cache_capabilities
  31    {
  32       u32   flags;      /* Flags defining capabilities  */
  33       u32   cache_size; /* Cache size in K (1024 bytes) */
  34       u32   max_lock;   /* Maximum lockable region in K */
  35    }
  36
  37    /*
  38     * Flags
  39     */
  40
  41    /*
  42     * Bit 0: Cache lockability
  43     * Bits 1-31: Reserved for future use
  44     */
  45    #define CACHE_LOCKABLE    0x00000001   /* Cache can be locked */
  46
  47    /*
  48     * Cache Types
  49     */
  50    #define ICACHE            0x00
  51    #define DCACHE            0x01
  52
  53    DESCRIPTION
  54
  55    This function fills out the pcache capability identifier for the
  56    requested cache. cache_type is either DCACHE or ICACHE. This
  57    function is not very useful at the moment as all XScale CPU's
  58    have the same size Cache, but is is provided for future XScale
  59    based processors that may have larger cache sizes.
  60
  61    RETURN VALUE
  62
  63    This function returns 0 if no error occurs, otherwise it returns
  64    a negative, errno compatible value.
  65
  66       -EIO   Unknown hardware error
  67
  68 III. Cache Locking
  69
  70    SYNOPSIS
  71
  72    int cache_lock(void *addr, u32 len, u8 cache_type, const char *desc);
  73
  74    DESCRIPTION
  75
  76    This function locks a physically contigous portion of memory starting
  77    at the virtual address pointed to by addr into the cache referenced
  78    by cache_type.
  79
  80    The address of the data/instruction that is to be locked must be
  81    aligned on a cache line boundary (L1_CACHE_ALIGNEMENT).
  82
  83    The desc parameter is an optional (pass NULL if not used) human readable
  84    descriptor of the locked memory region that is used by the cache
  85    management code to build the /proc/cache_locks table.
  86
  87    Note that this function does not check whether the address is valid
  88    or not before locking it into the cache.  That duty is up to the
  89    caller.  Also, it does not check for duplicate or overlaping
  90    entries.
  91
  92    RETURN VALUE
  93
  94    If the function is successful in locking the entry into cache, a
  95    zero is returned.
  96
  97    If an error occurs, an appropriate error value is returned.
  98
  99       -EINVAL   The memory address provided was not cache line aligned
 100       -ENOMEM   Could not allocate memory to complete operation
 101       -ENOSPC   Not enough space left on cache to lock in requested region
 102       -EIO      Unknown error
 103
 104 III. Cache Unlocking
 105
 106    SYNOPSIS
 107
 108    int cache_unlock(void *addr)
 109
 110    DESCRIPTION
 111
 112    This function unlocks a portion of memory that was previously locked
 113    into either the I or D cache.
 114
 115    RETURN VALUE
 116
 117    If the entry is cleanly unlocked from the cache, a 0 is returned.
 118    In the case of an error, an appropriate error is returned.
 119
 120       -ENOENT    No entry with given address associated with this cache
 121       -EIO       Unknown error
 122
 123