Intel's XScale Microarchitecture provides support for locking of data
and instructions into the appropriate caches. This  file provides
an overview of the API that has been developed to take advantage of this
feature from kernel space. Note that there is NO support for user space
cache locking.

For example usage of this code, grab:

	ftp://source.mvista.com/pub/xscale/cache-test.c

If you have any questions, comments, patches, etc, please contact me.

Deepak Saxena <dsaxena@mvista.com>

API DESCRIPTION 


I. Header File

   #include <asm/xscale-lock.h>

II. Cache Capability Discovery

   SYNOPSIS

   int cache_query(u8 cache_type, 
                           struct cache_capabilities *pcache);

   struct cache_capabilities
   {
      u32   flags;      /* Flags defining capabilities  */
      u32   cache_size; /* Cache size in K (1024 bytes) */
      u32   max_lock;   /* Maximum lockable region in K */
   }

   /*
    * Flags
    */
   
   /*
    * Bit 0: Cache lockability
    * Bits 1-31: Reserved for future use
    */
   #define CACHE_LOCKABLE    0x00000001   /* Cache can be locked */

   /*
    * Cache Types
    */
   #define ICACHE            0x00
   #define DCACHE            0x01

   DESCRIPTION

   This function fills out the pcache capability identifier for the 
   requested cache. cache_type is either DCACHE or ICACHE. This 
   function is not very useful at the moment as all XScale CPU's
   have the same size Cache, but is is provided for future XScale
   based processors that may have larger cache sizes.

   RETURN VALUE

   This function returns 0 if no error occurs, otherwise it returns
   a negative, errno compatible value.

      -EIO   Unknown hardware error    

III. Cache Locking

   SYNOPSIS
    
   int cache_lock(void *addr, u32 len, u8 cache_type, const char *desc);

   DESCRIPTION

   This function locks a physically contigous portion of memory starting
   at the virtual address pointed to by addr into the cache referenced
   by cache_type.  

   The address of the data/instruction that is to be locked must be
   aligned on a cache line boundary (L1_CACHE_ALIGNEMENT).
 
   The desc parameter is an optional (pass NULL if not used) human readable
   descriptor of the locked memory region that is used by the cache 
   management code to build the /proc/cache_locks table.

   Note that this function does not check whether the address is valid
   or not before locking it into the cache.  That duty is up to the
   caller.  Also, it does not check for duplicate or overlaping 
   entries.

   RETURN VALUE

   If the function is successful in locking the entry into cache, a
   zero is returned.

   If an error occurs, an appropriate error value is returned.

      -EINVAL   The memory address provided was not cache line aligned
      -ENOMEM   Could not allocate memory to complete operation
      -ENOSPC   Not enough space left on cache to lock in requested region
      -EIO      Unknown error

III. Cache Unlocking

   SYNOPSIS

   int cache_unlock(void *addr)

   DESCRIPTION

   This function unlocks a portion of memory that was previously locked
   into either the I or D cache.

   RETURN VALUE

   If the entry is cleanly unlocked from the cache, a 0 is returned.
   In the case of an error, an appropriate error is returned.

      -ENOENT    No entry with given address associated with this cache
      -EIO       Unknown error