From 5757fc577e2b69716814ceef8b357c20e74fff0c Mon Sep 17 00:00:00 2001 From: David-John Willis Date: Thu, 7 Jul 2011 17:42:24 +0100 Subject: GPH: Add note to the README stored with 'mmuhack.o' for the GP2X explaining why the binary object is in the source tree. --- backends/platform/gph/devices/gp2x/mmuhack/README | 116 +++++++++++++++++++++ .../platform/gph/devices/gp2x/mmuhack/readme.txt | 110 ------------------- 2 files changed, 116 insertions(+), 110 deletions(-) create mode 100644 backends/platform/gph/devices/gp2x/mmuhack/README delete mode 100644 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 0000000000..6db7d81845 --- /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 bea49d7d6d..0000000000 --- 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 - -- cgit v1.2.3