[Scummvm-cvs-logs] scummvm master -> 5757fc577e2b69716814ceef8b357c20e74fff0c

[djwillis]

This automated email contains information about 1 new commit which have been
pushed to the 'scummvm' repo located at https://github.com/scummvm/scummvm .

Summary:
5757fc577e GPH: Add note to the README stored with 'mmuhack.o' for the GP2X


Commit: 5757fc577e2b69716814ceef8b357c20e74fff0c
    https://github.com/scummvm/scummvm/commit/5757fc577e2b69716814ceef8b357c20e74fff0c
Author: David-John Willis (John.Willis at Distant-earth.com)
Date: 2011-07-07T09:42:24-07:00

Commit Message:
GPH: Add note to the README stored with 'mmuhack.o' for the GP2X
     explaining why the binary object is in the source tree.

Changed paths:
  A backends/platform/gph/devices/gp2x/mmuhack/README
  R backends/platform/gph/devices/gp2x/mmuhack/readme.txt



diff --git a/backends/platform/gph/devices/gp2x/mmuhack/README b/backends/platform/gph/devices/gp2x/mmuhack/README
new file mode 100644
index 0000000..6db7d81
--- /dev/null
+++ b/backends/platform/gph/devices/gp2x/mmuhack/README
@@ -0,0 +1,116 @@
+PLEASE NOTE: 
+
+The binary object 'mmuhack.o' is stored in the source tree as it is very awkward to
+build it manually each time and would require the use of 2 toolchains to do so.
+
+Notes on how to rebuild from the included source can be found below.
+
+About
+-----
+
+This is a module for GP2X 2.4 based Linux kernel, created for developers to use in their
+programs.
+
+Normally the upper 32MB is uncached. This means that reads/writes on the memory
+are always done via the physical memory modules rather than the much faster
+memory built into the processor (called 'cache'). Access to the upper 32MB can
+be sped up by Squidge's MMU hack. The easiest way to use the MMU hack is to add
+and load the MMU hack kernel module into your program.
+
+Note: Building this module requries a GP2X 'kernel' toolchain (i.e. GCC 2.95.*
+for the GP2X stock, 3.* for Open2X).
+
+You can't build this module with the GCC 4 based application toolchains.
+
+Operation
+---------
+
+When loaded into kernel, this module creates /dev/mmuhack device. Whenever
+a program opens that device using open() call, the module traverses all
+memory, which was allocated in 0x02000000-0x03ffffff range by the program via
+using mmap() system call. While doing that, it marks all encountered memory
+as bufferable and cacheable.
+
+The most common use of this is to remove the framebuffer access bottleneck.
+Note that, however, by making the framebuffer cacheable you can cause display
+artifacts. This can happen because parts of your framebuffer may stay in CPU
+cache and not to be written back to the physical memory. The display
+controller only fetches data from the physical memory, so you get incomplete
+image (the memory will most likely contain data from previous frame, so these
+artifacts are better visible during fade effects). The easy way to fix this
+is by using a special ARM Linux system call, which flushes the cache (forces
+the CPU to write data in cache to the physical memory (see section "Flushing
+the cache")).
+
+Using this module affects the whole upper memory area. But in some situations
+this may be not desirable, for example when using ARM940 core in your program
+(ether using 940 libraries like ogg940 and gpu940, or using your custom code,
+which needs uncacheable memory for communication and such). If you need part
+of your upper memory to be cached, and other part not, you should mmap() that
+memory (which you want to be uncached) _after_ doing open("/dev/mmuhack").
+Another way is to modify mmuhack.c to suit your needs and rebuild the module.
+
+
+Usage
+-----
+
+The very first thing to do is to load the kernel module (mmuhack.o) into the
+running kernel. But before that you should try to unload mmuhack module,
+because other program might have left a different version loaded with
+different memory configuration, which may not suit your program.
+
+system("/sbin/rmmod mmuhack");
+system("/sbin/insmod mmuhack.o");
+
+Now you can assume the module is loaded into kernel and open /dev/mmuhack
+device. You don't need to worry about previous calls failing, because in that
+case open() will simply fail and nothing bad will happen.
+
+IMPORTANT: you _must_ do the open() call _after_ you initialize your graphics
+library or allocate your memory, because it can only work with memory which is
+already allocated, it won't affect memory you or your lib allocates after the
+open() call.
+
+int mmufd = open("/dev/mmuhack", O_RDWR);
+if(mmufd < 0)
+{
+  printf("MMU hack failed");
+}
+else
+{
+  printf("MMU hack loaded");
+  close(mmufd);
+}
+
+If the above call succeeded, you are all done.
+I recommend to unload the module when your program exits, because the other
+program may want to load a different mmuhack.o and may fail, because you left
+your mmuhack.o loaded (it does not get unloaded automatically on exit).
+
+system("/sbin/rmmod mmuhack");
+
+
+Flushing the cache
+------------------
+
+If using mmuhack.o causes your program to display artifacts (see "Operation"
+section for explanation), you will need to flush the CPU cache. This should
+be done after finishing every frame and just before flipping your display
+buffer/surface. You will need to add flush_uppermem_cache.s file to your
+Makefile/project and add a call to flush_uppermem_cache() just before final
+framebuffer flip or blit.
+
+flush_uppermem_cache() has 3 parameters. First param is the start address,
+second param is the end address, third one should always be 0. The addresses
+should be virtual ones (most often pointers to the start/end of your
+framebuffer). Example:
+
+flush_uppermem_cache(screen_surface->pixels, screen_surface->pixels + 320*240, 0);
+
+
+Credits
+-------
+
+Original idea/implementation: Squidge (this whole thing is also known as squidgehack)
+Kernel module: NK
+Documentation: notaz
diff --git a/backends/platform/gph/devices/gp2x/mmuhack/readme.txt b/backends/platform/gph/devices/gp2x/mmuhack/readme.txt
deleted file mode 100644
index bea49d7..0000000
--- a/backends/platform/gph/devices/gp2x/mmuhack/readme.txt
+++ /dev/null
@@ -1,110 +0,0 @@
-About
------
-
-This is a module for GP2X 2.4 based Linux kernel, created for developers to use in their
-programs.
-
-Normally the upper 32MB is uncached. This means that reads/writes on the memory
-are always done via the physical memory modules rather than the much faster
-memory built into the processor (called 'cache'). Access to the upper 32MB can
-be sped up by Squidge's MMU hack. The easiest way to use the MMU hack is to add
-and load the MMU hack kernel module into your program.
-
-Note: Building this module requries a GP2X 'kernel' toolchain (i.e. GCC 2.95.*
-for the GP2X stock, 3.* for Open2X).
-
-You can't build this module with the GCC 4 based application toolchains.
-
-Operation
----------
-
-When loaded into kernel, this module creates /dev/mmuhack device. Whenever
-a program opens that device using open() call, the module traverses all
-memory, which was allocated in 0x02000000-0x03ffffff range by the program via
-using mmap() system call. While doing that, it marks all encountered memory
-as bufferable and cacheable.
-
-The most common use of this is to remove the framebuffer access bottleneck.
-Note that, however, by making the framebuffer cacheable you can cause display
-artifacts. This can happen because parts of your framebuffer may stay in CPU
-cache and not to be written back to the physical memory. The display
-controller only fetches data from the physical memory, so you get incomplete
-image (the memory will most likely contain data from previous frame, so these
-artifacts are better visible during fade effects). The easy way to fix this
-is by using a special ARM Linux system call, which flushes the cache (forces
-the CPU to write data in cache to the physical memory (see section "Flushing
-the cache")).
-
-Using this module affects the whole upper memory area. But in some situations
-this may be not desirable, for example when using ARM940 core in your program
-(ether using 940 libraries like ogg940 and gpu940, or using your custom code,
-which needs uncacheable memory for communication and such). If you need part
-of your upper memory to be cached, and other part not, you should mmap() that
-memory (which you want to be uncached) _after_ doing open("/dev/mmuhack").
-Another way is to modify mmuhack.c to suit your needs and rebuild the module.
-
-
-Usage
------
-
-The very first thing to do is to load the kernel module (mmuhack.o) into the
-running kernel. But before that you should try to unload mmuhack module,
-because other program might have left a different version loaded with
-different memory configuration, which may not suit your program.
-
-system("/sbin/rmmod mmuhack");
-system("/sbin/insmod mmuhack.o");
-
-Now you can assume the module is loaded into kernel and open /dev/mmuhack
-device. You don't need to worry about previous calls failing, because in that
-case open() will simply fail and nothing bad will happen.
-
-IMPORTANT: you _must_ do the open() call _after_ you initialize your graphics
-library or allocate your memory, because it can only work with memory which is
-already allocated, it won't affect memory you or your lib allocates after the
-open() call.
-
-int mmufd = open("/dev/mmuhack", O_RDWR);
-if(mmufd < 0)
-{
-  printf("MMU hack failed");
-}
-else
-{
-  printf("MMU hack loaded");
-  close(mmufd);
-}
-
-If the above call succeeded, you are all done.
-I recommend to unload the module when your program exits, because the other
-program may want to load a different mmuhack.o and may fail, because you left
-your mmuhack.o loaded (it does not get unloaded automatically on exit).
-
-system("/sbin/rmmod mmuhack");
-
-
-Flushing the cache
-------------------
-
-If using mmuhack.o causes your program to display artifacts (see "Operation"
-section for explanation), you will need to flush the CPU cache. This should
-be done after finishing every frame and just before flipping your display
-buffer/surface. You will need to add flush_uppermem_cache.s file to your
-Makefile/project and add a call to flush_uppermem_cache() just before final
-framebuffer flip or blit.
-
-flush_uppermem_cache() has 3 parameters. First param is the start address,
-second param is the end address, third one should always be 0. The addresses
-should be virtual ones (most often pointers to the start/end of your
-framebuffer). Example:
-
-flush_uppermem_cache(screen_surface->pixels, screen_surface->pixels + 320*240, 0);
-
-
-Credits
--------
-
-Original idea/implementation: Squidge (this whole thing is also known as squidgehack)
-Kernel module: NK
-Documentation: notaz
-