README

   1 About
   2 -----
   3
   4 wARM is a combination of library and Linux kernel module for ARM processor
   5 control. It was created because ARM processor allows to perform certain
   6 operations in privileged modes only, and ARM Linux kernel is only providing
   7 limited functionality through some private system calls. The code was
   8 developed for GPH GP2X/Wiz consoles, but it should be possible to use it
   9 on other ARM Linux systems (probably with modifications).
  10
  11 Currently wARM provides various cache control operations and supports only
  12 ARM9 family processors.
  13
  14
  15 Usage
  16 -----
  17
  18 The library consists of just 2 files: warm.c and warm.h, which should be
  19 compiled into your program. The library performs module loading and
  20 communication with it all by itself, you just need to call the right
  21 functions. You will need to have a matching kernel module available for
  22 kernel running on your device, several precompiled modules can be found
  23 in bin/ directory:
  24
  25   warm_2.4.25.o        - for GP2X F100/F200 GPH firmwares
  26   warm_2.4.26-open2x.o - for GP2X F100/F200 Open2x firmware
  27   warm_2.6.24.ko       - for Wiz GPH firmwares
  28
  29 When the module is loaded into kernel, it creates /proc/warm file, which
  30 can be read for some information about the CPU.
  31
  32
  33 API
  34 ---
  35
  36 warm_init   - must be called on startup. You must do it with current working
  37               directory set to where kernel module can be found.
  38
  39 warm_finish - should be called before exit to close internal files and unload
  40               the module.
  41
  42 warm_cache_op_range -
  43               call to perform cache invalidation or clean operations (can
  44               specify both with binary or - '|') for virtual address ranges.
  45               In all cases write buffer is flushed (no operation can be
  46               specified to just flush the write buffer).
  47
  48 warm_cache_op_all -
  49               same as above, only affects the whole cache.
  50
  51 warm_change_cb_range -
  52               set or clear C and/or B bits for memory region (if is_set is
  53               nonzero, sets, else clears). The meaning of C and B bit
  54               combinations is processor specific, for ARM9 C enables both
  55               caching and buffering, B enables write buffer (when C is
  56               cleared), or enables write-back caching (when C is set).
  57               Note that in some cases the region needs to be accessed
  58               before calling this function, so that kernel maps actual pages.
  59
  60 warm_change_cb_upper -
  61               same as above, only affects "upper" memory (RAM memory above
  62               Linux accessible range, can be found in GP2X and Wiz).
  63
  64 warm_virt2phys -
  65               Converts virtual address to physical address. Note that the
  66               returned address is only valid for one page where the address
  67               points to (4KB in Linux). Next page will most likely point to
  68               completely different physical memory location, instead of next
  69               one.
  70
  71 note: all operations except warm_cache_op_all() affect calling process only.
  72
  73
  74 License
  75 -------
  76
  77  * Copyright (c) Gražvydas "notaz" Ignotas, 2009
  78  * notasas a gmail d com
  79  *
  80  * Redistribution and use in source and binary forms, with or without
  81  * modification, are permitted provided that the following conditions are met:
  82  *     * Redistributions of source code must retain the above copyright
  83  *       notice, this list of conditions and the following disclaimer.
  84  *     * Redistributions in binary form must reproduce the above copyright
  85  *       notice, this list of conditions and the following disclaimer in the
  86  *       documentation and/or other materials provided with the distribution.
  87  *     * Neither the name of the organization nor the
  88  *       names of its contributors may be used to endorse or promote products
  89  *       derived from this software without specific prior written permission.
  90  *
  91  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  92  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  93  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  94  * ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
  95  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  96  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  97  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  98  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  99  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 100  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 101