The mmu.library project © 1998 the mmu.library development group, THOR ----------------------------------------------------------------------------- What is this: ------------- The mmu.library provides functions for MMU related operations as write- or read-protecting certain areas of memory for a given set of tasks, or marking memory regions as "swapped" virtual memory support. It offers an abstraction level on top of the actual MMU and a unified interface for MMU purposes. The MMU lib does NOT implement virtual memory, that's the purpose of another library - the memory.library. There's no much reason why any application except the memory.library and probably some debugging tools should call this library directly. The memory.library functions on top of this library should suffer for "all day purposes". The goal of the mmu.library is to provide an "abstraction layer" on top of the hardware, to allow programs to make use of the memory management hardware of the more advanced members of the MC68K processor family. Programs using the functions of the mmu.library do not need to modify the MMU tables directly and hence will not conflict with each other. The mmu.library interface provides all necessary functions to do that. This will allow programs like Enforcer and VMM to cooperate nicely with each other, provided both use this library. Since writing the mmu.library is a tough job, I need your help! I've only a single oldish MC68030 40Mhz system at home, but the mmu.library is supposed to support all members of the MC68K family (the 68851, 68040 and 68060 MMUs). Since I don't have a testing system available, I need your help - writing system software without being able to debug is "a bit" tricky. What can I do as a non-developer: --------------------------------- Simple. Stop all disk access, copy the archive to the RAM-Disk, then open a shell and enter assign LIBS: ram: add then run the "MMUScan" program. Watch what happens: The program should output a list like the following: 68030 MMU detected. MMU page size is 0x400 bytes. User root pointer: 0x800000020023f870 Supervisor root pointer: 0x0000000000000000 Data Transparent translation 0: 0xffff0777 Data Transparent translation 1: 0xffff0777 Inst Transparent translation 0: 0x00000000 Inst Transparent translation 1: 0x00000000 Memory region: 00000000 to 000003ff invalid, ID 00000000 Memory region: 00000400 to 001fffff cache inhibited Memory region: 00200000 to 009fffff copyback cache mode Memory region: 00a00000 to 00bbffff invalid, ID 00000000 Memory region: 00bc0000 to 00bfffff cache inhibited Memory region: 00c00000 to 00d7ffff invalid, ID 00000000 Memory region: 00d80000 to 00dfffff cache inhibited Memory region: 00e00000 to 00e7ffff invalid, ID 00000000 Memory region: 00e80000 to 00ebffff cache inhibited Memory region: 00ec0000 to 00efffff invalid, ID 00000000 Memory region: 00f00000 to 00ffffff write protected Memory region: 01000000 to ffffffff invalid, ID 00000000 Please copy this output into a file and sent it to my place by Email: thor@math.tu-berlin.de Then enter: avail flush to remove the library again. Watch out for possible crashes or other problems. If anything goes wrong, please write down the guru number and contact me. The email is above. What can I do as developer: --------------------------- What about joining the mmu.library development group? This is just a couple of people contributing to this library by writing code and exchanging their wisdom by EMail. It's a non-profit organization that works on the development of this library. If, whenever, this library becomes a commercial product, you'll get paid, of course. However, the current library, as it is, is planned to be freeware, so don't expect money. It doesn't look like there's currently a market for this library project, unfortunately. Contact me at thor@math.tu-berlin.de if you want to join this group. What can be done just now is to run this library on your machine and find and correct bugs. As I said, I haven't tested the 68851, the 68040 and 68060 parts at all. The source of the library is included to help you debugging it, but please don't make modifications without contacting me. What is required to build the library: -------------------------------------- The library is build by two assemblers, the DevPac and the Freeware assembler PhxAss which can be found on the AmiNet. I still prefer the DevPac because it's Macro capabilities, even though it doesn't support all the 68060 functions I need to get hands on. Hence, the general-purpose functions of the library are assembled with DevPac - the .asm files - , the processor specific routines - in the .a files - use the PhxAss, however. A make utitilty would do good, the makefile is included. A C compiler is needed to compile the example program "MMUScan". Every C compiler should do fine. What is in this distribution: ----------------------------- Autodocs: The preliminary version of the autodocs of the mmu.library and the memory library, as well as a file describing some planned implementation details. Include: The includes for a C compiler as well as the ".fd" file for the library functions written so far. In detail: mmu/mmubase.h The library base as well as the defines describing the MMU types found. mmu/context.h Describing the main structure of the mmu.library, the context. This defines, too, the memory properties that can be set by the MMU, as non-cacheable or write protected. mmu/config.h Describes an internal-use-only MMU configuration structure. A final edition of this library won't include this file. mmu/alerts.h Defines the guru-mediations that can be thrown by the library. mmu_lib.fd The function descriptor file written so far. clib Prototypes for the library functions. pragmas Pragmas for the library functions. Created with FDToPragma. Should work with every compiler. proto Prototypes for the library, includes the clib and the pragma file. C_Sources: C sources of sample programs. That's currently only the MMUScan program that prints the MMU configuration, the page size, the type of the MMU found and its hardware configuration. MMUScan: The ready-for-use MMUScan program. Quite long because I compiled this with the standard link-library I/O functions. Could be done much better, but this is only a test program anyways. Lib_Sources: The library sources. This is more or less a direct copy from my harddisk. Includes the assembly sources, the assembly headers used to assemble this, the Makefile and the object files if you don't want to re-assemble everything. Contains, too, some startup- files used for my assembler setup. Not necessarely required. Needless to say that everything in here is "private" in the sense that no program using the mmu.library should depend on the implenentation details defined by these files. The ".a" files are assembled by PhxAss, ".asm" is done by "DevPac" and ".i" are the includes. In detail: Project-Startup: Makes necessary assignments and copies the sources into a temporary directory. Run at my system as soon as I launch the assembler. Shell-Startup2: A shell script run by the "Project-Startup" that makes a few additional setups. Makefile: The makefile used to assemble and link this program. mu_version.i: Defines the version of this library. mu_lib.i: The detailed library header structure. mu_lib.asm: The library initialization and shutdown code, the resident structure of the library and some few stub funtions. mu_alerts.i: Defines the gurus thrown by the library. mu_detect.a: The MMU auto detection logic. Should work fine (better than the enforcer code which crashes on a plain MC68020 without MMU...) mu_service.asm: Service routines. Currently, a routine to allocate library aligned to page boundaries. Not yet used, but still there. mu_pool.asm: Memory pool functions. Since the exec functions are bugged unless SetPatch is installed, I prefer using my own. mu_context.i: Describes the MMU library main structure, the (MMU)-Context, as well as the MMU memory property flags and the map node structure used for the abstraction level of the MMU tables. mu_context.asm: Context management and manipulation functions, including a function that builds the default MMU mapping if no MMU table was found. mu_loadlib.asm: This is not linked to the library. It's a tiny assembly source that loads the library to allow a standard debugger to step thru. mu_parse040.asm: Parses the 68040 MMU table and builds the abstract MMU mapping from it. mu_parse060.asm: Ditto, but for the 68060 MMU. Looks almost the same, even though there are some slight differences. mu_parse030.asm: Ditto, but for the 68030 and 68851 MMU. This should even support long descriptor tables and limit fields, even though I haven't found a program that builds these MMU tables. mu_851.a: 68851 specific routines, load and save the MMU configuration. mu_030.a: 68030 specific routines. mu_040.a: 68040 specific routines. mu_060.a: 68060 specific routines. Asm_Includes: I'm usually too lazy to include the system header files when writing in assembly. It usually takes ages to include them... These includes just define the library offsets of some standard libraries without the anoying "_LVO" I can't stand (what is this supposed to do help?). It also defines a set of sophisticated macros for the DevPac assembler (Macros.asm). An older version of these can be found on my web page. Unfortunately, the PhxAss Assembler isn't powerful enough to assemble these. (Sigh.) Known bugs and problems of this implementation: ----------------------------------------------- Things that require testing: - 68851, 68040 and 68060 code completely untested. I NEED YOUR HELP! - 68030 MMU table scan with long descriptors untested. - Parsing of the transparent translation registers untested. - Parsing of setups which make use of a distinct user/supervisor MMU table. Things not yet implemented: - Building and modification of MMU tables. - The exception handler (tricky!) Things the current design does not allow: - MMU tables using the function codes. The amiga design shouldn't allow this anyways, but I don't know whether there's a board that makes use of them. - Transparent translation registers that are function-code specific. See the remark above. (Supervisor-specific mappings should work fine, though!) - The current design implements the function of the transparent translation registers into the MMU mapping, will then build a new MMU table and disables the TTx registers. However, this is almost, but not completely the same. The MMU can be disabled with the external MMUDIS pin, the transparent translation can't. I don't know whether there's a board that makes use of this function. - The current implementation does not yet check completely whether an "EC" type processor (without an MMU) is on-board. This check should work for the 68060 since there's a hardware register for it, but I haven't implemented the tests for the '030 and '040 yet. However, all this is documented on the Motorola Web page, shouldn't be a problem as soon as the MMU table builder and the exception handler is up and running. - The current design doesn't allow the page size to be adjusted. It is fixed on startup and then constant for all MMU tables to be build. If an already existent MMU table is found, its page size will be used. This design was choosen to allow sharing MMU tables amongst contexts for shared and public memory. Even though the page size is fixed, the GetPageSize() call REQUIRES a context pointer for future upwards compatibility. I would really enjoy if someone (Ralph Schmidt?) could give me some internal information about the P5 boards and their MMU usage. Especially, the function calls and the design of the 68040 and 68060 library would be of great help, as well as some specifics of the DMA problems of the Enforcer and the various versions of the 68060 library (Michael Sinsz should know this?). Any kind of information will be appreciated! Debugging: ---------- Yes, that's a problem of its own. Obviously, the MMU library uses some "heavy magic" supervisor code which is not available for a standard monitor. Even though the DevPac "MonAm" is a nice and powerful debugger, it's not powerful enough for these tricks. There's currently - up to my knowledge - only one debugger that can do this for you, and that's my own... (-; Check the Aminet and my web-page for COP, then read the documentation. If, after reading, you STILL want to use it, you're the right guy for this job... (-; Recommended reading: -------------------- The following books are recommended reading: Motorola 68030 Enhanced 32-bit Microprocessor User's Manual MC68030UM/AD Rev.3 Motorola 68040 User's Manual M68040UM/AD Rev.1 Motorola 68060 User's Manual M68060UM/AD Rev.1 Motorola M68000 Family Programmer's Reference Manual M68000PM/AD Rev.1 Amiga Hardware Reference Manual, 3rd ed. Addison-Wesley Publishing Company, Inc. ISBN 0-201-56776-8 Amiga ROM Kernal Reference Manual, 3rd ed., Volume "Libraries" Addison-Wesley Publising Company, Inc. ISBN 0-201-56774-1 The Amiga Guru Book, 2nd Ed. Ralph Babel, Taunusstein 1989,1993 Additional sources: The Amiga Developer CD V1.1 (V1.2 is already available) Final words: ------------ The mmu.library and the memory library will be my last project for the Amiga. It depends a bit on what happens with the Amiga in the next two years whether a PPC version of this library is required or not; hence, after all, this can't be much more than a toy project that came several years too late. However, as it looks now, Amiga goes PC. However, I'm currently not willing to support this step and the Intel/Microsoft illnesses. \begin{sarcastic} While Commodore just dug the grave for the Amiga, Gateway is turning it into a zombie. \end{sarcastic} So long, Thomas