AmigActive 4

home *** CD-ROM | disk | FTP | other *** search

/ AmigActive 4 / AACD04.ISO / AACD / Programming / MMULib / Autodocs / mmu.doc < prev

Wrap

Text File | 1999-08-28 | 112.2 KB | 3,441 lines

TABLE OF CONTENTS mmu.library/--Background-- mmu.library/--Patches-- mmu.library/CreateMMUContext mmu.library/DeleteMMUContext mmu.library/EnterMMUContext mmu.library/LeaveMMUContext mmu.library/CurrentContext mmu.library/AddContextHook mmu.library/RemContextHook mmu.library/AddMessageHook mmu.library/RemMessageHook mmu.library/ActivateException mmu.library/DeactivateException mmu.library/GetPageSize mmu.library/RemapSize mmu.library/SetPropertiesA mmu.library/SetPagePropertiesA mmu.library/RebuildTree mmu.library/GetPropertiesA mmu.library/GetPagePropertiesA mmu.library/AllocAligned mmu.library/LockMMUContext mmu.library/UnlockMMUContext mmu.library/AttemptLockMMUContext mmu.library/LockContextList mmu.library/UnlockContextList mmu.library/AttemptLockContextList mmu.library/AllocLineVec mmu.library/PhysicalPageLocation mmu.library/PhysicalLocation mmu.library/DMAInitiate mmu.library/DMATerminate mmu.library/GetMapping mmu.library/ReleaseMapping mmu.library/NewMapping mmu.library/CopyMapping mmu.library/DupMapping mmu.library/CopyContextRegion mmu.library/SetPropertiesMapping mmu.library/SetMappingPropertiesA mmu.library/GetMappingPropertiesA mmu.library/SetPropertyList mmu.library/GetMMUType mmu.library/SuperContext mmu.library/DefaultContext mmu.library/WithoutMMU mmu.library/SetBusError mmu.library/GetMMUContextData mmu.library/SetMMUContextDataA mmu.library/BuildIndirect mmu.library/SetIndirect mmu.library/GetIndirect mmu.library/--Background-- mmu.library/--Background-- PURPOSE 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 basic object administrated by this library is the "context". A "context" is the software abstraction of a MMU translation tree, it keeps the information of the status of memory. The mmu.library provides a "global" context that represents the MMU translation tree for all tasks. It is build by the init code of the library either by snooping the already existing MMU translation tree or by building an own tree by looking at the available memory and expansion devices. Programs can build own contexts by using the MMU library functions and may enter or leave the contexts generated in this way. Several tasks may share one context, as they represent, for example, multiple "threads" of one single program. Thus, the notation used here is some- how turned around: A "context" in the amiga world is called "process" in unix, and a "task" or "process" in the amiga world is called a "thread" usually. Tasks that do not enter an own context explicitly share the common global context. Even though it is possible to change the global context, this technique should be used only by debugging tools as the enforcer. It could, for example, mark unused areas of the memory as well as the first 4K as "invalid". The MMU library provides two "hooks" for each context, the "bus error hook" and the "segmentation fault" hook. The first hook is called if an access to an invalid memory location is detected, or a write to a read-only memory area. The second is called if an access to a memory page marked as "swapped out" is detected. It's part of the service of the MMU library to keep these two access violations apart. The default hooks call simply the exception handler of the running task, which generates by default the well known "guru". It's up to programs on top of the MMU library to setup useful hooks. An enforcer like tool might set "bus error hook" to print some useful information about the access violation, the memory.library will set the "segmentation fault" hook to swap in the memory in question. The hooks are really "low-level" routines and are executed in super- visor mode, and therefore very limited in power. The library provides itself a ready-for-use hook function which sends a message to a task to be specified and suspends the task that caused the bus error until the message is replied. MMU trees are managed on two levels, a "software abstraction level" which is comfortable and easy to use. Memory "properties" of large regions of memory can be redefined quite easely with one single call, but rebuilding the MMU table tree from this abstraction layer is a lengthly operation and requires quite a lot of CPU power not available in critical applications. Therefore, a more "hardware based" approach is available which modifies the existing MMU table "on the fly" and is therefore rather fast. However, memory pages to be handled like this must be marked with the MAPP_SINGLE property to tell the library to build the MMU table in a special way to allow fast modification and to bypass some possible optimizations (e.g. "early page terminators" and "invalid descriptors not at page level"). Modifications on this level are never seen by the abstraction level above and should be used only once the MMU tree is complete. If that is, too, not fast enough, the MMU library allows building pages using "indirect descriptors". That is, the page property flags are given by a true hardware descriptor you provide. This makes code CPU specific, obviously, but has the advantage that page properties can be modified by a single long word "poke" in your program, and the proper ATC flush. This is almost "hardware banging", with some support. This method has one important drawback, namely that the library is no longer able to disable caching for DMA transfer to and from this page. Hence, NEVER EVER access an indirect page by DMA. mmu.library/--Patches-- mmu.library/--Patches-- To perform its job, the mmu.library has to install a number of system patches. I tried avoid this as best as possible, but some installations have to be done. The following patches are installed: exec/CacheControl: Replaced partially by a function that guarantees that the data cache remains off when the mmu.library builds descriptors. exec/ColdReboot: Replaced partially by a function that removes the mmu.library installed MMU trees. This is done to restart the processor with a clean MMU setup. exec/Alert: Replaced partially. The Alert() replacement routine will check whether the alert caused is fatal or not, and will Disable() and unload the mmu.library installed MMU tree if this is the case. Since a deadend alert will go over into a reset without calling ColdReboot(), this must be done here separately to ensure that the machine restarts properly. exec/AddMem: Adding memory with a MMU setup active would or would not mean that the MMU table must be adjusted to reflect the changes. This function should not be called once the system is setup and running. It is here patched to an Alert(). The original routine is not called because some 68040/68060 libraries modify the MMU table on their own in case this happens. I don't think this routine is really required unless on startup, but in case it is I will replace it completely on demand. exec/AddConfigDev: Patched to an Alert() for just the same reason than above. exec/CachePreDMA: Replaced completely by a MMU library routine that disables copyback mode for non-aligned pages and translates the logical address passed in to the physical address, by means of the mmu.library public context. exec/CachePostDMA: Ditto. Replaced completely by the MMU.library. mmu.library/CreateMMUContext mmu.library/CreateContext mmu.library/CreateMMUContext NAME CreateMMUContext - Build a new MMU context. SYNOPSIS context = CreateMMUContextA ( tags ); d0 a0 context = CreateMMUContext ( tag1, ... ); struct MMUContext * CreateMMUContextA ( struct TagItem *); struct MMUContext * CreateMMUContext ( Tag tag1, ... ); FUNCTION This function builds a new MMU context. The context created will be a copy of the global context, with all memory regions marked in the same way and the same hooks installed. INPUTS tags - Tag items for the context to be created. Currently defined tags are: MCXTAG_COPY - build a copy of the context * passed in, if the pointer is NULL, build a copy of the global default context. If this tag item is not given, all context addresses will be marked as MAPP_BLANK. Most likely not what you want. If you specify a different table size than that of the context you want to clone you should specify the MCXTAG_ERRORCODE as well and study the return code carefully. The mmu library might have performed some rounding to fit the old table specifications into the new table layout. In worst case, this will make your new table unusable. It is therefore in general not a good idea to specify a page size larger than that of the cloned context. Even though the library itself allocates all its internal structures aligned to "worst case" page sizes, this might not be true for external user programs. MCXTAG_EXECBASE - allow accesses of AbsExecBase and all accesses except for the first KByte, even if the first page in the MMU tree - the "zeropage" - is marked as invalid. This is an important feature if the mmu.library is used to implement an Enforcer type program. Accesses will be emulated in software and are hence *slow*. They should be avoided. AbsExecBase accesses are handled with highest priority first and might be faster, even though they're still slower than "the real thing". It is not guaranteed that the library will really read AbsExecBase from location four, dependent on some internals, it might give you a cached copy instead. This means usually no problem since AbsExecBase must not change while the machine is up and running. This option defaults to TRUE. For more quirks about the zeropage, read the MCXTAG_ZEROBASE tag documentation below. MCXTAG_BLANKFILL - defines a ULONG word fill value for blank memory regions. This ULONG is read by the CPU in case a program tries an access to "empty" memory regions. It defaults to 0L, but other values might be use- ful for debugging. MCXTAG_MEMORYATTRS- An exec memory attributes specifier to be used for allocating memory for the (hardware) MMU tables. Defaults to MEMF_PUBLIC, check exec/memory.h for other possibilities. MCXTAG_PRIVATESUPER A boolean value, either TRUE or FALSE. If TRUE, build a private MMU supervisor table for this context, independent of the global supervisor table. BE WARNED! This means specifically that possible modifications of the global supervisor context will not be carried on your private supervisor table. Even if you pass in FALSE here, the library might still ignore your choice and build a private supervisor table anyways. This happens if the table layout you've chosen is different to the default table layout, making the user tree in- compatible to the default supervisor tree. MCXTAG_ZEROBASE This option takes only effect if MCXTAG_EXECBASE is TRUE and the first page of the MMU table build by you is invalid. This means that the MMU library will emulate accesses to all addresses in the first page up to the first KByte which remains unavailable to implement an "Enforcer" function. This tag provides a base address to which page these accesses have to be redirected. This tag defaults to NULL meaning that the library will redirect accesses to the true zeropage, making it available temporarely, but any other memory location - provided it is page aligned - can be specified here as well. This is important if the zero page gets remapped to a different location, and an Enforcer type program is run later on. The zero page remapper should specify this tag to redirect accesses transparently, even if an Enforcer type application invalidates the zero page. Failing to do so would make the MMU library emulating the access to the incorrect, non-remapped memory location. Since other programs might want to build a private MMU table with a different table size, it is *NOT* enough to align the remap destination of the zeropage to GetPageSize() boundaries, RemapSize() alignment is required! THIS IS AN ADVANCED FEATURE. The next tag items define the MMU table layout. A logical address, used as input for the MMU, consists of exactly 32 bits. These bits are now split from the left to the right into groups to define a "path" in the MMU tree. Each "level" of the MMU tree should be considered as an array of pointers, pointing to the next lower level of the tree. The nodes of the tree are contain the descriptors that define how the address belonging to the path from the root to this descriptor should be handled. For example, consider a three- level tree with 7 bits for level A and B, 6 bits for level C and 12 bits for the page. The address 0x01feabcd would be used like this to find an descriptor: hex 0x01feabcd is binary ----7--- ----7---- ---6--- ------12------- bits 0000 000|1 1111 11|10 1010| 1011 1100 1101 \_______/\________/\______/\_____________/ | | | | | | | | V | | | Index into level A of the MMU tree is 0, hence the first pointer is read. The MMU obtains now another array of pointers, called the level B. | | | | | | V | | Index into level B of the MMU tree is 127. The MMU uses the last pointer from the table obtained in the previous step. | | | | V | Index into level C of the MMU tree is 42. The MMU uses, hence, the 42nd pointer of the array pointed to by the 127th pointer of the level B array. This is now the "page descriptor", defining the base address for the next step. | | V This is now finally the page offset, 0xbcd in this example. It is added to the base address from the page descriptor in level C. If the address is not "remapped", the base address would be identically to the first 32-12 = 20 bits of the physically address. MCXTAG_DEPTH - Depth of the MMU tree to build. Defaults to the depth of the global public context. Legal values are 1..4 for the 68020/68851 and the 68030, but the 68040/68060 supports only trees of depth 3. MCXTAG_LEVELABITS - Number of bits of the logical address that make up the level A of the MMU tree. 2^bits is the number of entries on this level of the tree. The 68020/68851 and the 68030 support here values from 1..15, the only legal value for the 68040 and 68060 is 7. The MMU library will pick a reasonable and system dependent default for you if you don't specify this tag item. MCXTAG_LEVELBBITS - Number of bits for the level B of the MMU tree, unused if the depth is smaller than two. Legal values are 1..15 for the 851 and 030, and 7 as only possible value for the 040 and 060. MCXTAG_LEVELCBITS - Number of bits of the level C of the MMU tree, unused if the depth is smaller than three. Arguments may range from 1..15 for the 851 and 030, and must be either 5 or 6 for the 040 and 060. MCXTAG_LEVELDBITS - Number of bits in the level D of the MMU tree, only used if the depth is four and therefore unused on the 040 and 060. Must range from 1..15. MCXTAG_PAGEBITS - Number of bits to be used from the logical address as the page offset. 2^bits is the page size. Legal values are 8..15, giving 256 bytes up to 32K pages for the 68020/68851 and 68030, or 12..13 defining 4K resp. 8K pages for the 68040 and 68060. The default is the page size of the global context. All the "..."BITS specifications MUST sum up to 32 since a logical address consists of exactly 32 bits. You may leave out some or all of these tags, the MMU library will keep care of the rest and will chose reasonable defaults for you. MCXTAG_ERRORCODE - pointer to a ULONG the MMU library will fill in with an error code in case building the MMU tree failed. It will be set to 0L if the function succeeds. The following error codes have been defined: CCERR_NO_FREE_STORE - the library went out of memory. CCERR_INVALID_PARAMETERS - the parameters specified by the tags are invalid. CCERR_UNSUPPORTED - the parameters are valid, but not supported by the hardware. CCERR_TRIMMED - the library performed some minor adjustments on the MMU table passed in for cloning. The cache modes might not be optimal due to some roudings that have to be performed, but the MMU table should work in general. THIS IS NOT AN ERROR, you will get your new context. CCERR_UNALIGNED - the library had to perform heavy rouding in the MMU table passed in, it might be unusable. For example, remapped pages were mis- aligned and due to the rounding accesses might go to wrong locations. If you get this return code, you should possibly deallocate the new context and inform the user that the request could not be satis- fied. Still, THIS IS NOT AN ERROR. You get a new context, but possibly an usuable one. RETURNS NULL if the new context couldn't be created or a handle to the new context, as parameter to all MMU library functions. NOTES This call makes NOT the current task entering the new context, you've to call EnterMMUContext() explicitly for that purpose. The context structure is not documented intentionally. It depends on the implementation. BUGS SEE ALSO DeleteMMUContext() BUGS mmu.library/DeleteMMUContext mmu.library/DeleteMMUContext NAME DeleteMMUContext - delete an MMU context build with CreateMMUContext. SYNOPSIS DeleteMMUContext ( context ); a0 void DeleteMMUContext ( struct MMUContext * ); FUNCTION This function deletes a context build with CreateMMUContext(). INPUTS A handle to the context to be deleted. RETURNS nothing. NOTES This call doesn't remove any task from the context, especially the current task is NOT removed from the context. You've to call LeaveMMUContext() before. Deleting a context with some tasks still in this context will cause this function to guru. If your context was created with a private supervisor context included, you must call this function only *once*, with the user context created. It will automatically deallocate the attached supervisor context as well. BUGS SEE ALSO CreateMMUContext() mmu.library/EnterMMUContext mmu.library/EnterMMUContext NAME EnterMMUContext - let a task enter a specific context. SYNOPSIS context = EnterMMUContext( context , task ); d0 a0 a1 struct MMUContext * EnterMMUContext( struct MMUContext * , struct Task * ); FUNCTION Add a given task to a context. This makes the MMU settings defined by the context available for the task in question. INPUTS context - the context to enter or NULL for the global context. task - a pointer to the task structure that should enter the context. RETURNS a handle to the context the task participated before or NULL if this function failed. The task will stay in the last context used in this case. NOTES This call uses the tc_Switch() and tc_Launch() functions of the task structure. What basically happens here is that these functions are set to internal procedures that swap the context specific MMU table or the global MMU in and flush the ATC of the MMU. This call may fail, check the return code for NULL - either due to lack of memory or because the task is part of a protected context the current task hasn't entered. If you want to use the tc_Switch() and tc_Launch() functions your- self, you should install a task specific context hook, see AddContextHook(). This function can be used to change the context of a task by adding it to a new context. The task specific context switch and launch hooks will be "carried over" to the new context, but all other MMU specific exceptions are now the matter of the new context. BUGS SEE ALSO LeaveMMUContext(),ProtectMMUContext(), exec/tasks.h mmu.library/LeaveMMUContext mmu.library/LeaveMMUContext NAME LeaveMMUContext - remove a given task from a context. SYNOPSIS context = LeaveMMUContext( task ); d0 a1 struct MMUContext * LeaveMMUContext( struct Task *); FUNCTION The specified task leaves its context and enters the global context. INPUTS task - the task that should leave a private context and enter the global default context. RETURNS the context the task was added to or NULL on failure. Might be the global default context if the task did not enter any context. NOTES It is safe to call this function even if the task wasn't added to any context. The function returns the global context in this case. This function must be called to any task participating a given context to be able to delete that context. This function is equivalent to EnterMMUContext(NULL,task). This function makes use of the tc_Switch() and tc_Launch() functions of the task structure to be able to set the MMU root pointer. Make sure that you check for failure. This call may return NULL if the task entered a protected context the current task does not participate or if switch and launch exceptions are in use. BUGS SEE ALSO EnterMMUContext(), DeleteMMUContext(), ProtectMMUContext(), RemContextHook(), exec/tasks.h mmu.library/CurrentContext mmu.library/CurrentContext NAME CurrentContext - find out the current context of a task. SYNOPSIS context = CurrentMMUContext( task ); d0 a1 struct MMUContext * CurrentMMUContext( struct Task * ); FUNCTION This function is used to get a handle to the context the given task is added to, or to return the context of the calling task. INPUTS task - the address of the task structure you like to investigate or NULL to get a handle to the currently active context. RETURNS a handle to the context the given task is added to, the global context if the task is not attached to any context or the currently active context if the argument is NULL. NOTES This call fails only if the given task is part of a protected context which is not shared by the current task. The NULL argument is always safe. BUGS Protected contexts are not yet implemented. SEE ALSO ProtectMMUContext(), FindTask() mmu.library/AddContextHook mmu.library/AddContextHook NAME AddContextHook - set an exception handler to a Context SYNOPSIS hook = AddContextHookA ( tags ); a0 hook = AddContextHook ( tag1, ... ); struct ExceptionHook * AddContextHookA ( struct TagItem * ); struct ExceptionHook * AddContextHook ( Tag tag1, ... ); FUNCTION This call installs an exception hook for a given context for various exception types the MMU library can provide. INPUTS tags - A taglist defining the type of the exception hook to be added. Currently defined are: MADTAG_CONTEXT - The context to which this exception hook should be added. This MUST be given for "swapped" handlers. If it is left blank or set to NULL for segmentation fault handlers, you define a global segmentation fault handler. MADTAG_TASK - If the hook should be called only if a specific task is running, specify a pointer to the task structure here. Warning! Adding too many task specific hooks slows things down unnecessary. Remember that a MMU Context may hold more than one task. This MUST be given for the switch and launch hooks. MADTAG_TYPE - Type of the exception hook to build. The following types are available: MMUEH_SEGFAULT - Called on segmentation fault, i.e. write to a write protected page or access of an invalid page. Most useful for "Enforcer" like tools. MMUEH_SWAPPED - Called on access for a "swapped out" page. Most useful to implement virtual memory. MMUEH_SWITCH - Called when the task looses the CPU. MMUEH_LAUNCH - Called when the task gains the CPU. Remember that the tc_Switch() and tc_Launch() function pointers are no longer available if the task has been added to a MMUContext. MMUEH_PAGEACCESS - Called whenever a MAPP_SINGLE page gets build by the context. This could be used to modify the MMU tree "on the fly" if necessary, the required parameters are passed thru. MADTAG_CODE - A function pointer to the code to be called. This should be an assembly language function. It is called like this: Register a0 - Pointer to the ExceptionData structure or the PageAccessData. Register a1 - loaded with the MADTAG_DATA provided data. Register a4 - Ditto. Register a5 - Pointer to the code itself. Register a6 - MMUBase. NOT A SCRATCH. Registers d0-d1/a0-a1/a4-a5 are scratches and are available for the Exception handler. You *MUST* set the "Z" condition code and clear d0 on exit in case you handled the exception. Details on how to write an exception handler are in the "Exception.doc" file. MADTAG_DATA - Data to be loaded for the hook function. MADTAG_NAME - A name for the hook. Currently unused. MADTAG_PRI - A priority, ranging from -128...+127. Hooks of higher priorities are called first. RESULTS A handle to the exception hook. Do not interpret this handle. Or NULL on failure. NOTES this call will be used by the high-level function AddMessageHook(). The global segmentation fault hook may be set by a debugging tool like the enforcer. The exception will not be activated, you need to call ActivateException() explicitly to make the library call it. Much more needs to be said about this function, see Exception.doc for details about the exception handlers. BUGS SEE ALSO RemContextHook(), AddMessageHook(), ActivateException(), exec/interrupts.h, Exception.doc mmu.library/RemContextHook mmu.library/RemContextHook NAME RemContextHook - remove an exception handler from a Context SYNOPSIS RemContextHook( hook ) a1 void RemContextHook( struct ExceptionHook * ); FUNCTION This function removes a previously installed context hook from the hook list. INPUTS The handle of the hook, as obtained by AddContextHook(). RESULTS none. NOTES You must call DeactivateException() on your hook before you remove it. Be aware that the library will call the exec exception handler, i.e. will generate a guru in case no exception handler is available. SEE ALSO AddContextHook(), DeactivateException(), exec/interrupts.h mmu.library/AddMessageHook mmu.library/AddMessageHook NAME AddMessageHook - install a high-level hook function. SYNOPSIS hook = AddMessageHookA ( tags ); a0 hook = AddMessageHook ( tag1, ... ); struct ExceptionHook * AddMessageHookA ( struct TagItem * ); struct ExceptionHook * AddMessageHook ( Tag tag1, ... ); FUNCTION Installs a high-level hook of the tag-given properties. As soon as an exception of the requested type occurs, an exception message (see below) will be sent to the port. The task that caused the exception will be halted until the message gets replied. BE WARNED: Message hooks perform only operation if task switching is enabled and interrupts are allowed and the code failed in User mode. They will just "drop thru" to the next handler if this is not the case. INPUTS tags - A taglist defining the type of the exception hook to be added. Currently defined are: MADTAG_CONTEXT - The context to which this exception hook should be added. This MUST be given. MADTAG_TASK - If the hook should be called only if a specific task is running, specify a pointer to the task structure here. Warning! Adding too many task specific hooks slows things down unnecessary. Remember that a MMU Context may hold more than one task. This MUST be given for the switch and launch hooks. MADTAG_TYPE - Type of the exception hook to build. The following types are available: MMUEH_SEGFAULT - Called on segmentation fault, i.e. write to a write protected page or access of an invalid page. Most useful for "Enforcer" like tools. MMUEH_SWAPPED - Called on access for a "swapped out" page. Most useful to implement virtual memory. MADTAG_CATCHERPORT - The port to sent the data to. MADTAG_NAME - A name for the hook. Currently unused. MADTAG_PRI - A priority, ranging from -128...+127. Hooks of higher priorities are called first. On an exception, the following message will be sent to the port: struct ExceptionMessage { struct Message exm_msg; struct ExceptionData exm_Data; }; For details about the ExceptionData structure, see Exception.doc. Once the message gets replied, the faulted task is restarted. RESULTS a handle for the exception that must be passed back to RemMessageHook() for removal or NULL on failure. Do not interpret this handle. NOTES The handler must have been added to a context with EnterMMUContext() before this function can be used. Unlike the AddContextHook() function, this DOES NOT work for "plain" tasks without a context. The hook must be activated with ActivateException() before it gets called. This function is used by the memory.library to install its exception handler. The port will be in this case the port of the swapper daemon that loads swapped out pages from disk. BUGS SEE ALSO AddContextHook(), RemContextHook(), RemMessageHook(), ActivateException(), Exception.doc mmu.library/RemMessageHook mmu.library/RemMessageHook NAME RemMessageHook - remove a high-level hook from a context. SYNOPSIS RemMessageHook( handle ); a1 void RemMessageHook( struct ExceptionHook * ); FUNCTION This function removed a previously installed Message hook from the hook list of the context. INPUTS handle - a handle to the message hook as returned by the AddMessageHook function. RESULTS none. NOTES To remove a message hook safely, deactivate it first with DeactivateException(), then tell the daemon to reply all exceptions of this hook, then remove it. Not following these rules may cause deadlocks. BUGS SEE ALSO AddMessageHook(), AddContextHook(), RemContextHook(), DeactivateException(), Exception.doc mmu.library/ActivateException mmu.library/ActivateException NAME ActivateException - enable an exception hook. SYNOPSIS ActivateException( hook ); a1 void ActivateException( struct ExceptionHook * ); FUNCTION Activates a formerly installed exception hook, either a low level context hook or a high-level message hook. RETURNS NOTES Hooks of either kind must be activated before the mmu.library will call them. Hooks are deactivated after creation and must be deactivated before they get removed. This call can be safely used within interrupts and from super- visor mode. BUGS SEE ALSO DeactivateException(), AddContextHook(), AddMessageHook(), Exception.doc mmu.library/DeactivateException mmu.library/DeactivateException NAME DeactivateException - enable an exception hook. SYNOPSIS DeactivateException( hook ); a1 void DeactivateException( struct ExceptionHook * ); FUNCTION Deactivates a formerly installed exception hook, either a low level context hook or a high-level message hook, i.e. disables it from being called. RETURNS NOTES Hooks of either kind must be activated before the mmu.library will call them. Hooks are deactivated after creation and must be deactivated before they get removed. This call can be safely used within interrupts and from super- visor mode. BUGS SEE ALSO ActivateException(), RemContextHook(), RemMessageHook(), Exception.doc mmu.library/GetPageSize mmu.library/GetPageSize NAME GetPageSize - return the page size of a context. SYNOPSIS pagesz = GetPageSize( context ); d0 a0 ULONG GetPageSize( struct MMUContext * ); FUNCTION This function returns the page size selected by the MMU library for the given context. Possible page sizes are limited by the hardware and cannot be adjusted from the outside. The page size is set up by the MMU library for the global public context, and it can be selected from the available page sizes for private MMUContexts, see CreateMMUContext(). INPUTS context - a handle to the context to be investigated or NULL for the active context. RESULTS the page size in bytes or zero for failure. NOTES BUGS Context protection is currently unsupported. SEE ALSO CreateMMUContext() mmu.library/RemapSize mmu.library/RemapSize NAME RemapSize - return the block size for memory remapping. SYNOPSIS remapsize = RemapSize( context ); d0 a0 ULONG RemapSize( struct MMUContext * ); FUNCTION This function returns the smallest possible block size, and therefore the alignment restrictions, for remapping of memory that should be added to the exec memory pool. Since the MMU tables have to be placed in non-fragmented memory, certain alignment restrictions for the memory blocks the MMU tables are placed in arise. This harder aligment condition is only required for memory that is put into the exec free list, but as long as remapped memory is never returned from AllocMem, the page size is good enough. INPUTS context - a handle to the context to be investigated or NULL for the active context. RESULTS the smallest admissable block size for memory returned by AllocMem(). NOTES The call will fail if the given context is protected, the result will be zero in this case. Even though the mmu.library does support memory remapping, this does not mean all other programs do. For example, remember that the inputs to the "MAPP_REMAPPED" pages is a physical page size, hence your program has to translate the logical address obtained by AllocMem() to a physical address at first. This can be done with the PhysicalLocation() function. Additionally, DMA devices might or might not support memory remapping, just for the same reason: They require physical, not logical addresses. The MMU library provides a translation mechanism in form of the ChachePreDMA() and CachePostDMA() functions of ExecBase, but not all DMA device drivers call these functions properly. Certain patches might be made available for devices not following this rule. BUGS Adding remapped memory to the freelist is highly untested and not recommended because of the quirks of this mechanism. SEE ALSO PhysicalLocation(), GetPageSize(), exec/CachePreDMA(), DMAInitiate() mmu.library/SetPropertiesA mmu.library/SetPropertiesA NAME SetPropertiesA - set memory attributes for a given logical range. SYNOPSIS result = SetPropertiesA( context, flags, mask, lower, size, tags); d0 a0 d1 d2 a1 d0 a2 BOOL SetPropertiesA( struct MMUContext *, ULONG, ULONG, ULONG, ULONG, struct TagItem *); result = SetProperties( context, flags, mask, lower, size, tag1, ...); BOOL SetProperties( struct MMUContext *, ULONG, ULONG, ULONG, ULONG, Tag tag1, ...); FUNCTION This call sets attributes of a certain memory range of the software abstraction layer of the MMU tree, aligned to page boundaries. INPUTS context - a handle to the context to modify or NULL for the active context. flags - a binary flags field for the attributes to define. The following bits have been defined: MAPP_WRITEPROTECTED - The page will be write protected. Writes to this area will cause a segmentation fault. MAPP_ROM - Read only memory, writes tolerated. This is almost identically to MAPP_READONLY except that writes into this area will not cause a call of the segmentation fault handler. The library will filter them out. This property can be used to simulate a ROM in RAM and might be useful for kickstart remappers. MAPP_USED - The "used" bit of the pages will be set. The CPU will set this bit automatically as soon as the pages are accessed. This flag will turn on the "USED" bit in the hard- ware MMU bit. NOT setting this flag means that the USED bit in the hardware tree is preserved, regard- less of the mask value. MAPP_MODIFIED - The "modified" bit of the pages will be set. The CPU will set this bit automatically as soon as a write is performed to the page in question. DO NOT SET THIS BIT TOGETHER WITH MAPP_WRITEPROTECTED OR WITHOUT MAPP_USED or the CPU might hang. This flag will turn on the "MODIFIED" bit in the hard- ware MMU bit. NOT setting this flag means that the MODIFIED bit in the hardware tree is preserved, regard- less of the mask value. MAPP_PRIVATE - The page will be marked invalid for all but the given contexts. MAPP_INVALID - The page will be marked as invalid. Accessing it will invoke the bus error hook. User data can be provided for this property mode, provided you don't select MAPP_SINGLEPAGE or MAPP_REPAIRABLE as well. MAPP_SWAPPED - The page will be marked as swapped out. A block ID *MUST* be provided for this property mode. MAPP_CACHEINHIBIT - The page will be marked as non- cacheable. MAPP_IMPRECISEEXECPTION - The page will be marked as "imprecise exception". MAPP_CACHEINHIBIT is mandatory in this case or this flag does nothing. Only available for the 68060, but does not harm for other MMUs. MAPP_NONSERIALIZED - The page will be marked as serialized. MAPP_CACHEINHIBIT is mandatory if this property is selected. Only available for the 68040, but does not harm for other MMUs. MAPP_COPYBACK - The page will be marked as "copyback" instead of "writethrough". Generally re- commended since this is faster for the '40 and '60. Only available for 68040 and 68060, but does not harm if selected for other MMUs. MAPP_CACHINHIBIT MUST NOT be selected. MAPP_REMAPPED - Map the page to a different memory location. Parameters are given in the tag items. Even though this seems simple, remapping memory is full of quirks. Obviously, DMA devices and the MMU itself see the true physical addresses and not the logical addresses as filtered by the MMU. Therefore, adding remapped memory to the exec.library freelist will cause nothing than trouble and hard to trace disk faults and crashes as soon as this memory is used by a DMA device or the mmu.library itself. (Note that even though the library is supposed to support this, this is currently untested) Even though there *are* documented methods how to prepare a DMA transfer for remapped memory, USING these exec function calls is unfortunately the exceptions. Therefore, this method is currently un- supported, by most (!really!) DMA device drivers. Amongst the broken devices are the gvpscsi.device and the cybscsi.device, to give just two examples. The omniscsi.device (the "Guru ROM") can be fixed with the MuOmniScsiPatch. If you really *MUST* remap public memory, then align it *AT LEAST* to the border given by RemapSize(). Just page alignment WILL NOT BE ENOUGH due to the way how the library works internally. YOU HAVE BEEN WARNED! MAPP_SUPERVISORONLY - The page will be not available for user programs. NOTE: This mode is currently implemented using invalid page descriptors for the user pages and is ignored when building supervisor tables. This method saves some space for the 68040 and 68060 and was the only way how it could be done for the 68030 and 68851 without using MMU tables twice as large. MAPP_USERPAGE0 - Set user page attribute 0. This selects the user page attribute 0 for the 68040 and 68060. "USER" DOES NOT MEAN YOU! The status of this bit appears on special pins of the CPU and might be required by some hardware, so don't play with this. You should not change this bit, by no means. MAPP_USERPAGE1 - Set user page attribute 1. This selects the user page attribute 0 for the 68040 and 68060. See above for warnings. MAPP_GLOBAL - The pages are part of the global (public) memory. You should not set this bit manually, it is under control of the library to optimize table flushes. MAPP_BLANK - Blank memory. The pages are mapped to one special area in RAM so erraneous reads and writes to these pages won't harm. MAPP_BLANK should ONLY be used to mark special memory areas as "non-available" and un-handled by the hardware, nothing else. MAPP_SHARED - Properties are identically to the public context. This tells the library to use the same properties as for the global context. However, MAPP_SHARED pages are not automatically updated when the global context changes, it's just a convenient way of saying "I want to uninstall my settings". MAPP_TRANSLATED - Under control of the TTx registers. NEVER SET THIS BIT YOURSELF. Pages with the "MAPP_TRANSLATED" bit set are under control of the "transparent translation registers" of the MMU and are "out of scope" for the mmu.library. Defining any properties for this domain will do nothing (or little, dependent on the TTx register configuration). A virtual memory program MUST NOT use virtual addresses which are transparently translated, this won't work. The mmu.library tries to be smart about the TTx registers and disables "unuseful" TTx settings itself. MAPP_INDIRECT - Map to a user provided page descriptor. The provided pages(s) are mapped by a user provided page descriptor. This page descriptor MUST BE aligned to a long word address, and it MUST BE a valid page descriptor for the MMU used. NEVER EVER attempt DMA, such as harddisk reads or writes to a memory domain marked as MAPP_INDIRECT. Due to some cache peculatities, the data might be incorrect and the result would be corrupt data. The library will be able to mark pages as non-cacheable if this is required for the DMA transfer, but this magic does not work for indirect pages. JUST DON'T DO THAT, MAPP_INIDIRECT is definitely an advanced feature. MAPP_BUNDLED - Map all pages in range to a single page in RAM. The main purpose of this function is to provide a MAPP_BLANK property with a user-selectable target page. MAPP_SINGLEPAGE - Make this page available for SetPagePropertiesA(). WARNING! Setting this bit shortcuts some optimizations the library might perform on the MMU table. The system may easely run out of memory if you select this property for "too many" pages. Use it with care, you have been warned! MAPP_REPAIRABLE - Inform the exception handler to provide write data and to allow pipeline fill. If this bit is set, the exception handler gets informed that you want to know the write data in case writes fail, or you want to provide the read data in case reads fail. The read/write data is available in the ExceptionData structure, read the exception handler documentation. This flag should be combined with MAPP_INVALID, MAPP_WRITEPROTECTED, MAPP_SWAPPED or MAPP_SUPERVISORONLY However, this technique requires a lot of "trickery" and should be expected to be slow and to create sub-optimal and over-sized MMU tables. Use it with care, on as few pages as possible and only if your exception handler is "not on a hurry". MAPP_USERATTRIBUTE0 - This is for your private use. This bit does not have any specific function, it is for your private use. MAPP_USERATTRIBUTE1 - This is for your private use. MAPP_USERATTRIBUTE2 MAPP_USERATTRIBUTE3 mask - A bit mask of the attributes to be changed. Note that the hardware USED and MODIFIED bits will never be cleared, even though the properties say so and the corresponding bits in the mask are set. However, you can force them "ON" if you like, this saves unnecessary write- backs of the MMU. lower - The lower boundary of the logical address to be modified. This must be aligned to the page size or this call will guru. size - Size of the region to be modified. Must be a multiple of the page size. tags - A tag array with additional data. Currently defined: MAPTAG_DESTINATION - the physical destination of the logical address. Must be provided for the MAPP_MAPPED or MAPP_BUNDLED bits. MAPTAG_BLOCKID - a unique ID the MMU.library doesn't care about, for external usage of the memory.library. Must be provided for the MAPP_SWAPPED flag and may be used to indicate where on disk the swapped page is kept. MAPTAG_USERDATA - a unique cookie you might provide for MAPP_INVALID pages and which is passed thru to the segmentation fault exception handler. MAPTAG_DESCRIPTOR - a pointer to a long word aligned table descriptor for MAPP_INDIRECT. RESULTS A boolean success/failure indicator. Might fail if the context is protected or no memory is available for the modification. NOTES This call adjusts only the abstraction layer of the MMU table and marks the pages as "dirty". An explicit call to RebuildTree() is required to make the changes active. You should bundle changes to the MMU table and call RebuildTree() once when you're done because rebuilding the MMU tree is a costy operation. If you need to modify the MMU table "on the fly" then consider using "SetPagePropertiesA()", even though its use is restricted to single pages. Even faster are MAPP_INDIRECT pages, but - to say that again - DO NOT PERFORM DMA ON THESE PAGES. The page size can be read with GetPageSize(). SUPERVISORONLY, SWAPPED and INVALID memory are implemented using the same MMU attributes (invalid, namely), but the library exception handler will filter them out and call the appropriate hook. Write protection goes only for the context specified. It usually makes sense to mark the memory region as PRIVATE as well, unless you modify the public hook. (Note that MAPP_PRIVATE is currently not implemented because it will slow down things considerably.) You may freely mark the first memory page as INVALID provided the context MCXTAG_EXECBASE flag is set (it usually is). Long word read accesses to AbsExecBase will be filtered out by the exception handler of the library and will be satisfied trans- parently to the program, as well as all other accesses except those into the first 1024 bytes. BUGS If the mask contains any property that requires user data, i.e. MAPP_REMAPPED or MAPP_SWAPPED, you *have* to redefine the user data by tag items and MAY NOT leave them out, as the library WILL NOT be able to restore the previously defined user data. SEE ALSO GetPropertiesA(), SetContextHook(), GetPageSize(), RemapSize(), RebuildTree(), SetPagePropertiesA(), SetMappingPropertiesA() mmu.library/SetPagePropertiesA mmu.library/SetPagePropertiesA NAME SetPagePropertiesA - set hardware memory attributes for a single page. SYNOPSIS result = SetPagePropertiesA( context, flags, mask, lower, tags); d0 a0 d1 d2 a1 a2 BOOL SetPagePropertiesA( struct MMUContext *, ULONG, ULONG, ULONG, struct TagItem *); result = SetPageProperties( context, flags, mask, lower, tag1, ...); BOOL SetPageProperties( struct MMUContext *, ULONG, ULONG, ULONG, Tag tag1, ...); FUNCTION This call sets the hardware attributes of a memory page. INPUTS context - a handle to the context to modify or NULL for the active context. flags - a binary flags field for the attributes to define. For the available attributes, see the SetPropertiesA() function. Differences: MAPP_MODIFIED and MAPP_USED are really set or cleared in the true hardware table, the mask is considered correctly. Note that this function is the only method to clear these two hardware flags, SetPropertiesA() or RebuildTree() don't do this. mask - a bit mask of all bits to be changed. tags - A tag array with additional data. Check SetPropertiesA() for details. RESULTS A boolean success/failure indicator. Might fail if the context is protected or no memory is available for the modification or the page is not marked with MAPP_SINGLEPAGE. NOTES BE WARNED! This function is very restricted in its use. It may well return FALSE even if all parameters are valid due to hardware restrictions. This function does never ever rebuild an MMU tree, it just modifies "what is there". If the library choose to optimize the MMU library tree and to map a couple of pages by one descriptor, for what reasons ever, this call will fail. The details when this happens depends not only on the MMU, but on the general system layout. The ONLY documented way to get a mapping for a page that can be adjusted using this call is to set the page to MAPP_SINGLEPAGE using SetPropertiesA() before. This call adjusts the hardware level of the MMU table if a descriptor is available for a single page. It does not modify more than one page at once. It might happen that the library does not satisfy a request setting a page as "cacheable" if a DMA operation is currently in progress and the page must remain "nonacheable". However, the function will not fail in this case, but just delay the operation until the DMA is complete. The properties will always fall back to the next available option. This routine is safe to be called from within interrupts, it does not break any Forbid() or Disable() and is ideal for quick-and-dirty repair operations within exceptions handlers, provided the MAPP_SINGLEPAGE flag has been set. BUGS Note that MAPP_SINGLEPAGE is the flag you want here, not MAPP_REPAIRABLE. That's something different! If the mask contains any property that requires user data, i.e. MAPP_REMAPPED or MAPP_SWAPPED, you *have* to redefine the user data by tag items and MAY NOT leave them out, as the library WILL NOT be able to restore the previously defined user data. SEE ALSO GetPagePropertiesA(), SetContextHook(), GetPageSize(), RebuildTree(), SetPropertiesA(), SetMappingPropertiesA() mmu.library/RebuildTree mmu.library/RebuildTree NAME RebuildTree - build a MMU hardware tree from the software abstraction layer. SYNOPSIS result = RebuildTree( context ); d0 a0 BOOL RebuildTree ( struct MMUContext * ); FUNCTION This function adjusts the MMU hardware tree to reflect the settings of the software abstraction layer defined with SetPropertiesA(). INPUTS context - a handle to the context to investigate or NULL for the active context. RESULTS a boolean success/failure indicator. TRUE if the operation was performed successfully. NOTES This is the big - and admittedly - slow one. Rebuilding the MMU tree is a relatively slow operation. The library tries to be smart about it and rebuilds only the pages whose mappings have been adjusted, but it's still a heavy beast. Properties temporarely defined with SetPagePropertiesA() will be lost after the rebuild, except for the MAPP_USED and MAPP_MODIFIED bits. BE WARNED! A consistent use of the two flags is only possible if the pages are marked as MAPP_SINGLE. The page building algorithm does not guarantee consistent use of these two bits except for MAPP_SINGLE pages. Even though it *might* look well most the time, it is not documented that these two bits are kept correctly for non- SINGLE pages. If you need MODIFIED or USED page information, the only way to get them is to mark these pages as MAPP_SINGLE. There's no consistent use for these flags if early termination descriptors (hence, w/o MAPP_SINGLE) are used by the library. Even though some pages in the abstraction layer might be marked as un-USED or un-MODIFIED, this routine NEVER clears the hardware bits. It requires a call to SetPagePropertiesA(), and hence the MAPP_SINGLE attribute (once again!) to do this. BUGS Much more should be said about this function. SEE ALSO SetPropertiesA(), SetPagePropertiesA(), GetPropertiesA(), GetPagePropertiesA() mmu.library/GetPropertiesA mmu.library/GetPropertiesA NAME GetPropertiesA - read memory attributes for a given logical page from the MMU table abstraction layer. SYNOPSIS flags = GetPropertiesA( context, lower, tags); d0 a0 a1 a2 ULONG GetPropertiesA( struct MMUContext *, void *, struct TagItem *); flags = GetProperties( context, lower, tag1, ...); ULONG GetProperties( struct MMUContext *, void *, Tag tag1, ...); FUNCTION This call reads the page properties of a certain address in memory from the software abstraction layer. It is the counterpart of SetPropertiesA(). INPUTS context - a handle to the context to investigate or NULL for the active context. lower - the logical address of the page to investigate. The size of the page depends on the hardware and is selected by the MMU library. The number of bytes in a page is returned by GetPageSize(). tags - additional tags. Currently defined are: MAPTAG_DESTINATION - a pointer to a void * where the physical destination of the logical address is filled in. Only available if the page is physically mapped to somewhere. Not filled in otherwise. MAPTAG_BLOCKID - read the a unique ID for the MAPP_SWAPPED property. Untouched if the page isn't swapped. The tag data points to a long word which will be filled in for swapped out pages. MAPTAG_USERDATA - read the unique cookie for INVALID pages, fill in the long word pointed to by the tag data field. MAPTAG_DESCRIPTOR - fill in the location of the indirect descriptor which is used to perform the mapping. Only used if MAPP_INDIRECT is used. RESULTS Returns a binary flags field for the attributes to define. See SetPropertiesA() for details. Remember that MAPP_USED or MAPP_MODIFIED reflect the bits on the abstraction layer, not the true hardware bits. You MUST call GetPagePropertiesA() to read them, and hence *MUST* use MAPP_SINGLE pages. NOTES The page size can be read with GetPageSize(). Check the return code of this call! The flags returned are valid for the given context, a different context may return a different flag setting and even a different physical locations. WARNING: The flags returned DO NOT reflect the hardware flags in the MMU table for the context. They DO reflect the settings installed with SetPropertiesA() on the abstraction layer of the MMU tables. The hardware table might differ for the following reasons: - SetPropertiesA() was called, but the changes haven't been made active with RebuildTree() yet. - A program modified the hardware layer directly using SetPagePropertiesA(). - DMA is currently active and the page in question has therefore been marked as non-cacheable temporarely. Additionally, the library might have adjusted the abstraction layer itself by allocating non-cacheabe memory for its MMU tables. This routine is *NOT* safe to be called from within interrupts. BUGS SEE ALSO SetPropertiesA(), SetContextHook(), GetMappingPropertiesA(), GetPageSize(), GetPagePropertiesA(), RebuildTree() mmu.library/GetPagePropertiesA mmu.library/GetPagePropertiesA NAME GetPropertiesA - read memory attributes from the hardware level for a given logical page. SYNOPSIS flags = GetPagePropertiesA( context, lower, tags); d0 a0 a1 a2 ULONG GetPagePropertiesA( struct MMUContext *, void *, struct TagItem *); result = GetPageProperties( context, lower, tag1, ...); BOOL GetPageProperties( struct MMUContext *, void *, Tag tag1, ...); FUNCTION This call reads the page properties of a certain address in memory directly from the hardware. It is the counterpart of SetPagePropertiesA(). INPUTS context - a handle to the context to investigate or NULL for the active context. The library might use the MMU hardware directly if NULL is passed in, this call might be faster therefore. lower - the logical address of the page to investigate. The size of the page depends on the hardware and is selected by the MMU library. The number of bytes in a page is returned by GetPageSize(). tags - additional tags. See GetPropertiesA() for details. RESULTS Returns a binary flags field for the attributes to define. See SetPropertiesA() for details. NOTES The page size can be read with GetPageSize(). The flags returned are valid for the given context, a different context may return a different flag setting and even a different physical location. WARNING: The flags returned reflect the NOT the hardware flags in the MMU table for the context except for the MODIFIED and USED properties, even though the hardware level is *almost* consistent with these flags. The hardware table might differ slightly in the following situations: - DMA is currently active and the page in question has therefore been marked as non-cacheable temporarely. Therefore, the cache settings returned are what will be re-installed here when DMA is finished. The library will "fake" the flags you have installed for the page investigated. - The library will use invalid descriptors to implement supervisor only or swapped pages. However, even though the flags might differ from the hardware flags, you're always safe to re-install the properties with SetPageProperties, there's no need to keep track of pecularities like cache disabling for DMA pages. The library does this for you. MAPP_MODIFIED and MAPP_USED are always read from the hardware directly. KEEP IN MIND that these two bits are only set and handled consistently for MAPP_SINGLE pages. You MUST NOT interpret them in all other cases, their values might get lost on a RebuildTree() call. This routine is safe to be called from within interrupts, most useful within exception handlers. BUGS SEE ALSO GetPropertiesA(), SetContextHook(), GetPageSize(), SetPagePropertiesA(), RebuildTree() mmu.library/AllocAligned mmu.library/AllocAligned NAME AllocAligned - allocate memory aligned to a memory border. SYNOPSIS mem = AllocAligned( bytesize, reqments, align ); d0 d0 d1 a0 void * AllocAligned( ULONG, ULONG, ULONG); FUNCTION Allocate memory aligned to certain boundaries. INPUTS bytesize - the size of the memory to allocate. reqments - exec style memory attributes align - the alignment restrictions of the page. MUST be a power of two. RETURNS a pointer to the allocated memory, aligned to the given border or NULL if no free physical memory could be found. NOTES Examples of how to use the "align" parameter: mem = AllocAligned(123,MEMF_PUBLIC|MEMF_CLEAR,1024); will allocate 123 bytes starting at a 1024 byte border, i.e. the address returned will be divisible by 1024. The call will clear the 123 bytes, NOT MORE. This is a service routine for the memory.library and shouldn't be used for all-day purposes. A DOS process will have its pr_Result2 field set to ERROR_NO_FREE_STORE if the memory allocation fails. The mmu.library calls this function by using its LVO library entry, so it can be patched to a smarter implementation if desired. BUGS SEE ALSO GetPageSize(), exec/memory.h mmu.library/LockMMUContext mmu.library/LockMMUContext NAME LockMMUContext - lock a MMU context SYNOPSIS LockMMUContext( context ); a0 void LockMMUContext( struct MMUContext * ); FUNCTION Lock the software abstraction layer of the MMU table against modifications from other tasks. INPUTS A handle to a MMUContext or NULL for the active context. RETURNS NOTES This mechanism DOES NOT avoid changes of the MMU table on a lower level by SetPageProperties(), only SetProperties() from other tasks will be locked. Hence, it locks the abstraction layer, but not the hardware level. DO NOT lock more than one context at once, unless you locked also the context list with LockContextList(). Not following this rule might cause deadlocks. BUGS SEE ALSO UnlockMMUContext(), SetPageProperties(), SetProperties(), LockContextList(). mmu.library/UnlockMMUContext mmu.library/UnlockMMUContext NAME UnlockMMUContext - release a MMU context SYNOPSIS UnlockMMUContext( context ); a0 void UnlockMMUContext( struct MMUContext * ); FUNCTION Release the software abstraction layer of the MMU table, allow modifications from other tasks. INPUTS A handle to a MMUContext or NULL for the active context. RETURNS NOTES This mechanism DOES NOT avoid changes of the MMU table on a lower level by SetPageProperties(), only SetProperties() from other tasks will be locked. Hence, it locks the abstraction layer, but not the hardware level. BUGS SEE ALSO LockMMUContext(), SetPageProperties(), SetProperties(), AttemptLockMMUContext() mmu.library/AttemptLockMMUContext mmu.library/AttemptLockMMUContext NAME AttemptLockMMUContext - attempt to lock a MMU context SYNOPSIS ok = AttemptLockMMUContext( context ); a0 LONG AttemptLockMMUContext( struct MMUContext * ); FUNCTION Grants non-blocking access to a MMU context. Attempts to lock the software abstraction layer of the MMU table against modifications from other tasks. INPUTS A handle to a MMUContext or NULL for the active context. RETURNS TRUE in case of success - the context is then locked for you and this lock must be released with UnlockMMUContext(). FALSE in case any other task holds a lock. NOTES This mechanism DOES NOT avoid changes of the MMU table on a lower level by SetPageProperties(), only SetProperties() from other tasks will be locked. Hence, it locks the abstraction layer, but not the hardware level. DO NOT lock more than one context at once, unless you locked also the context list with LockContextList(). Not following this rule might cause deadlocks. BUGS In pre-V39 machines, this call does not lock the context again in case you already hold a lock. This is a bug of the pre-V39 AttemptSemaphore(), read the exec autodocs for a workaround. SEE ALSO UnlockMMUContext(), SetPageProperties(), SetProperties(), LockContextList(), AttemptSemaphore() mmu.library/LockContextList mmu.library/LockContextList NAME LockContextList - arbitrate a master lock. SYNOPSIS LockContextList( ); void LockContextList( void ); FUNCTION Arbitrates a master lock that allows locking more than one context at once to avoid deadlocks. INPUTS RETURNS NOTES This lock grants access for locking more than one context at once, to avoid deadlocks. I.e. in case you need to lock more than one context at a time, get this lock FIRST, then lock the contexts in any order you prefer. This call DOES NOT avoid modification of the context list or individual contexts at all, i.e. other tasks are still able to create and to dispose contexts. To avoid this, you must lock the contexts afterwards. When you're done with the contexts, unlock the contexts first, THEN release this lock with UnlockContextList(). NOTE THE ORDER! BUGS SEE ALSO UnlockMMUContextList(), LockMMUContext(), AttemptLockContextList() mmu.library/UnlockContextList mmu.library/UnlockContextList NAME UnlockContextList - release the master context lock SYNOPSIS UnlockContextList( ); void UnlockContextList( void ); FUNCTION Releases the master lock that allows locking more than one context at once to avoid deadlocks. INPUTS RETURNS NOTES This lock grants access for locking more than one context at once, to avoid deadlocks. I.e. in case you need to lock more than one context at a time, get this lock FIRST, then lock the contexts in any order you prefer. This call DOES NOT avoid modification of the context list or individual contexts at all, i.e. other tasks are still able to create and to dispose contexts. To avoid this, you must lock the contexts afterwards. When you're done with the contexts, unlock the contexts first, THEN release this lock with UnlockContextList(). NOTE THE ORDER! BUGS SEE ALSO LockContextList(), LockContext(), AttemptLockContextList() mmu.library/AttemptLockContextList mmu.library/AttemptLockContextList NAME AttemptLockContextList - attempt to arbitrate the master lock. SYNOPSIS ok = AttemptLockContextList( ); LONG AttemptLockContextList( void ); FUNCTION Attempts granting the context master lock in a non-blocking fashion. INPUTS RETURNS TRUE in case the master lock could be arbitrated. You have then to release it with UnlockContextList(). FALSE in case it is already locked and access could not be granted. NOTES This lock grants access for locking more than one context at once, to avoid deadlocks. I.e. in case you need to lock more than one context at a time, get this lock FIRST, then lock the contexts in any order you prefer. This call DOES NOT avoid modification of the context list or individual contexts at all, i.e. other tasks are still able to create and to dispose contexts. To avoid this, you must lock the contexts afterwards. When you're done with the contexts, unlock the contexts first, THEN release this lock with UnlockContextList(). NOTE THE ORDER! BUGS In pre-V39 machines, this call does not lock the context again in case you already hold a lock. This is a bug of the pre-V39 AttemptSemaphore(), read the exec autodocs for a workaround. SEE ALSO UnlockContextList(), LockContext(), LockContextList(), AttemptLockSemaphore() mmu.library/AllocLineVec mmu.library/AllocLineVec NAME AllocLineMem - allocate cache line aligned, keep size SYNOPSIS AllocLineVec ( bytesize , attributes ); d0 d1 void * AllocLineVec ( ULONG, ULONG ); FUNCTION Allocates memory like AllocVec(), but the memory is guaranteed to be aligned to cache lines of the processors in the system, even though the pointer returned IS NOT. Minimal guaranteed alignment is currently 32 bytes, i.e. a PPC cache line. Future hardware may require stricter alignments. AllocLineMem'd memory is released with FreeVec() from the exec.library. INPUTS bytesize - the size of the memory block in bytes. attributes - memory attributes, see exec.library/AllocMem. RETURNS a pointer to the memory allocated or NULL on failure. A DOS process will have its pr_Result2 field set to ERROR_NO_FREE_STORE if the memory allocation fails. NOTES BIG WARNING: The pointer returned IS NEVER cache line aligned itself, but the complete memory block toghether with the vector size is kept in a cache line, regardless of the size passed in. Due to alignment restrictions, the routine might allocate a larger memory block than requested. It is however guaranteed that AT LEAST the size requested is returned, and that a FreeVec() will, indeed, free all memory. If MEMF_CLEAR is requested, the memory is cleared on the MC68K side, but the "zeros written" might be still in the cache. Hence, it is a good idea to flush the cache if the memory is passed over to the PPC. However, the vector size itself is always "pushed" to memory, it is therefore guaranteed to be properly written back to the memory. The memory allocated this way is released by FreeVec() of the exec.library. BUGS SEE ALSO exec.library/AllocVec(), exec.library/FreeVec(), AllocLineMem() mmu.library/PhysicalPageLocation mmu.library/PhysicalPageLocation NAME PhysicalPageLocation - translate logical address to physical SYNOPSIS addr = PhysicalPageLocation( context , addr ); d0 a0 a1 void * PhysicalPageLocation( struct MMUContext * , void * ); FUNCTION This function finds the physical address for the logical address passed in by scanning the MMU hardware table. If the physical address is not available, NULL is returned. INPUTS context - the context to enter or NULL for the current context. addr - the logical address to be translated. RETURNS the physical address of the logical address passed in, or NULL in case the logical address is not swapped in or otherwise out of control of the library. NOTES This is the low-level function, consider using the high-level function PhysicalLocation() when possible. This call can be safely used within interrupts. BUGS The function will also return NULL in case the logical address is translated to the address 0L. However, 0L should never be used as physical address anyhow. SEE ALSO GetPageProperties(), PhysicalLocation() mmu.library/PhysicalLocation mmu.library/PhysicalLocation NAME PhysicalLocation - translate logical address to physical SYNOPSIS props = PhysicalLocation( context, addrptr, lenptr ); d0 d1 a0 a1 ULONG PhysicalLocation( struct MMUContext * , void ** , ULONG * ); FUNCTION This function finds the physical address for the logical address passed in by scanning the software abstraction layer. If the physical address is not available, NULL is returned. INPUTS context - the context to enter or NULL for the current context. addrptr - points to the logical address to be translated. The physical address is filled in here. lenptr - Points to the length of the address range to be trans- lated. The function returns the length of the largest possible continous memory range contained in the memory range passed in. Hence, this function may shorten the memory block for fragmentized memory models. RETURNS the properties of the memory range. NOTES This is the high-level function, it is not callable from within interrupts. In case you've to operate on a range of physical memory, start the translation with this call, then compare the size returned with the size of the memory block passed in. Because this function may shorten the memory size in case the physical memory is fragmentated, you should be prepared that the size returned is smaller than what was passed in. In this case, operate on the memory region returned, then add the returned size to the original logical address and call this function again to get the physical location of the next chunk. BUGS The function will also return NULL in case the logical address is translated to the address 0L. However, 0L should never be used as physical address anyhow. SEE ALSO GetProperties(), PhysicalPageLocation() mmu.library/DMAInitiate mmu.library/DMAInitiate NAME DMAInitiate - start a DMA transport given a logical address. SYNOPSIS DMAInitiate( context, addrptr, lenptr, write ); d1 a0 a1 d0 void DMAInitiate( struct MMUContext * , void ** , ULONG * , BOOL ); FUNCTION This function finds the physical address for the logical address passed in by scanning a backup of the MMU translation tree. It ignores modifications made by the high-level and low-level functions unless RebuildTree() is called. INPUTS context - the context to enter or NULL for the current context. NOTE: This parameter is currently a dummy and should be set to NULL. The mmu.library will always use the public context for translation. addrptr - points to the logical address to be translated. The physical address is filled in here. lenptr - Points to the length of the address range to be trans- lated. The function returns the length of the largest possible continous memory range contained in the memory range passed in. Hence, this function may shorten the memory block for fragmentized memory models. write - set this to TRUE for transports from a DMA device INTO the memory, i.e. device reads. Set this to FALSE for writes from memory to the device. RETURNS NOTES The function checks whether the memory range passed in is available for DMA. It will guru in case it is not, i.e. the page is either swapped out, invalid, indirect, or write protected for DMA device reads. Reads into ROM addresses are silently tolerated, and, hence, are translations to and from blank dummy pages. This function is callable from within interrupts, but does only use a backup of the high-level table for its translation. Changes to the software abstraction level are not visible for this function unless RebuildTree() is called. Changes to the hardware level are not at all visible to this (and all other high-level) functions. In case you've to operate on a range of physical memory, start the translation with this call, then compare the size returned with the size of the memory block passed in. Because this function may shorten the memory size in case the physical memory is fragmentated, you should be prepared that the size returned is smaller than what was passed in. With the physical address returned, start the DMA and call DMATerminate() when done. In case the returned size is smaller than the block passed in, add the returned size to the original logical address and call this function again to get the physical location of the next chunk. EACH CALL TO DMAInitiate() must be matched by ONE AND PRECISELY ONE call to DMATerminate(). Even though this function does not require locking the context, I highly recommend doing so. It won't crash if you don't, but someone else could modify the MMU translation table in between. The library can deal with that, but the result of the DMA operation might be different than what you expect. BUGS This function should really use the context passed in, but since most (if not all) DMA device drivers do not keep the context of the task that actually initiated the transfer and hence would use the wrong context anyhow, DMA is currently limited to the public context. SEE ALSO DMATerminate(), PhysicalPageLocation(), exec/CachePreDMA() mmu.library/DMATerminate mmu.library/DMATerminate NAME DMATerminate - end a DMA transfer initiated by DMAInitiate. SYNOPSIS DMATerminate( context ); d1 void DMATerminate( struct MMUContext * ); FUNCTION This function ends a DMA transfer initiated by DMAInitate. It releases the resources by the first call. INPUTS context - the context to enter or NULL for the current context. NOTE: This parameter is currently a dummy and should be set to NULL. The mmu.library will always use the public context for translation. RETURNS NOTES This function is callable from within interrupts, but does only use a backup of the high-level table for its translation. Changes to the software abstraction level are not visible for this function unless RebuildTree() is called. Changes to the hardware level are not at all visible to this (and all other high-level) functions. EACH CALL TO DMAInitiate() must be matched by ONE AND PRECISELY ONE call to DMATerminate(). For details, check the DMAInitiate() function. BUGS This function should really use the context passed in, but since most (if not all) DMA device drivers do not keep the context of the task that actually initiated the transfer and hence would use the wrong context anyhow, DMA is currently limited to the public context. SEE ALSO DMAInitiate(), PhysicalPageLocation(), exec/CachePostDMA() mmu.library/GetMapping mmu.library/GetMapping NAME GetMapping - get access to the memory map of a MMUContext SYNOPSIS list = GetMapping( context ); d0 a0 struct MinList * GetMapping( struct MMUContext * ); FUNCTION This function makes a copy of the MapNodes for the given context. The nodes in this list describe the memory map as seen from tasks attached to this context, sorted by logical addresses. The list must be released afterwards with ReleaseMapping(). INPUTS context - the context to enter or NULL for the current context. RETURNS a pointer to a struct MinList which contains the MapNodes for this context, sorted by physical address, or NULL in case of failure. NOTES The nodes are just a copy of the real nodes within the context. This function is most useful to make a backup of the context memory map before altering it. In case any of the modifications fail, you are able to undo all modifications completely with a call to SetPropertyList() - which can't fail. To give an example: /* make a backup of the context how it looks now */ LockMMUContext(ctx); if (list=GetMapping(ctx)) { fine=TRUE; /* Try to alter it, step by step. */ if (!SetProperties(...)) fine=FALSE; if (!SetProperties(...)) fine=FALSE; /* etc, etc.... */ /* Oops, we failed! Re-install the old setup. */ if (!fine) SetPropertyList(ctx,list); } ReleaseMapping(ctx,list); UnlockMMUContext(ctx); /* and so on... */ Note that you've still to call ReleaseContextList(), even in case of failure when you've already re-installed backup property list. BUGS SEE ALSO ReleaseMapping(), SetPropertyList(), mmu/context.h mmu.library/ReleaseMapping mmu.library/ReleaseMapping NAME ReleaseMapping - get access to the memory map SYNOPSIS ReleaseMapping( context , list ); a0 a1 void ReleaseMapping( struct MMUContext * , struct MinList * ); FUNCTION This function releases the list of MapNodes arbitrated by GetMapping. INPUTS context - the context the nodes where taken from. list - the backup property list to release. RETURNS NOTES This function *MUST* be called, even in case the property list was re-installed with SetPropertyList(). BUGS SEE ALSO NewMapping(), GetMapping(), SetPropertyList() mmu.library/NewMapping mmu.library/NewMapping NAME NewMapping - build a new memory map SYNOPSIS list = NewMapping ( ); d0 struct MinList * NewMapping ( void ); FUNCTION Build and initialize a new memory map list. All addresses in this list will be marked as MAPP_BLANK. INPUTS nothing. RESULTS a MinList structure, initialized with MapNodes representing a completely blank memory layout or NULL on failure. You either need to copy the layout from a context with CopyContextRegion(), or define your own layout with calls to SetMappingPropertiesA(). NOTES Don't forget to release the list (and its contents) with ReleaseMapping() when you're done. BUGS SEE ALSO CopyContextRegion(), SetMappingPropertiesA(), ReleaseMapping(), GetMapping() mmu.library/CopyMapping mmu.library/CopyMapping NAME CopyMapping - transfer memory properties between lists SYNOPSIS fine = CopyMapping ( from , to , base , length , mask ); d0 a0 a1 d0 d1 d2 BOOL CopyMapping ( struct MinList * , struct MinList * , ULONG , ULONG , ULONG ); FUNCTION Copy the memory properties from one memory map to another, thru a mask. INPUTS from - the memory map which is (partially) to be transfered. to - the destination of the copy operation. base - base address. Memory properties will be copied starting at this address. length - length of the memory region in bytes whose properties shall be transfered. mask - a mask of property bits which are to be transfered. A zero bit in this mask indicates that the corresponding property in the destination will not be touched. For all the properties, check the SetPropertiesA() function. RESULTS a boolean success/failure indicator. It is TRUE in case the operation was performed, FALSE otherwise. The destination will not have been touched at all in this case. NOTES this call does not copy memory. It just copies memory attributes from one memory map to another. Check CopyContextRegion() to copy the properties from a context instead from a list. Since this call is not context based, the library will not be able to perform checks for correct page alignment, you have to do that yourself. Especially, note that SetPropertyList() - which attaches a memory map to a context - does not perform any check on this list either. Hence, *NOT* checking for page alignment here might result in an invalid context if you try to attach an incorrectly aligned list to a context later on. BUGS SEE ALSO SetPropertyList(), ReleaseMapping(), DupMapping(), SetPropertiesA(), CopyContextRegion() mmu.library/DupMapping mmu.library/DupMapping NAME DupMapping - make a one-to-one copy of a memory map SYNOPSIS dup = DupMapping ( list ); d0 a0 struct MinList * DupMapping( struct MinList * ); FUNCTION this call builds an identical copy of the memory map passed in. INPUTS list - the memory map to be copied. RESULTS another memory list, identical to the list passed in, or NULL on failure. NOTES Don't forget to release the memory list with ReleaseMapping() if you're done with it. You need to release both, the original as well as the duplicate. In case you want to make a copy of the memory map of a context, use GetMapping() instead. BUGS SEE ALSO GetMapping(), ReleaseMapping() mmu.library/CopyContextRegion mmu.library/CopyContextRegion NAME CopyContextRegion - transfer properties from a context to a list SYNOPSIS fine = CopyContextRegion ( ctx, list, base, length, mask ); d0 a0 a1 d0 d1 d2 BOOL CopyContextRegion ( struct MMUContext *, struct MinList *, ULONG, ULONG, ULONG ); FUNCTION Copy the properties of a memory region defined by a context to another memory map, thru a mask. INPUTS ctx - source context whose memory map shall be transfered. list - the destination memory map which is to be altered. base - base address of the memory region whose properties are to be copied. length - length of the memory region in bytes whose properties will be transfered. mask - a mask of property bits, see the SetPropertiesA() function for a detailed explanation. A zero bit in this mask means that the corresponding property in the destination will be left alone and will remain unchanged. RESULTS a boolean success/failure indicator, TRUE for success. On failure, the destination memory map will not have been touched at all. NOTES This call does not copy memory at all, it just defines the memory properties of a given memory map from that of a given context. Check CopyMapping() to transport memory properties from one list to another. Since this call is not context based, the library will not be able to perform checks for correct page alignment, you have to do that yourself. Especially, note that SetPropertyList() - which attaches a memory map to a context - does not perform any check on this list either. Hence, *NOT* checking for page alignment here might result in an invalid context if you try to attach an incorrectly aligned list to a context later on. BUGS SEE ALSO SetPropertyList(), ReleaseMapping(), SetPropertiesA(), SetPropertiesMapping() mmu.library/SetPropertiesMapping mmu.library/SetPropertiesMapping NAME SetPropertiesMapping - transfer properties from a map list to a context SYNOPSIS fine = SetPropertiesMapping ( ctx, list, base, length, mask ); d0 a0 a1 d0 d1 d2 BOOL SetPropertiesMapping ( struct MMUContext *, struct MinList *, ULONG, ULONG, ULONG ); FUNCTION Copy the properties of a memory map to a context, thru a mask. This is equivalent to SetPropertiesA(), except that the source data is contained in a memory map instead given as function arguments. This function is reverse to CopyContextRegion(). INPUTS ctx - destination context whose memory map shall be set. list - the source memory map, containing the data to be transfered. base - base address of the memory region whose properties are to be copied. length - length of the memory region in bytes whose properties will be transfered. mask - a mask of property bits, see the SetPropertiesA() function for a detailed explanation. A zero bit in this mask means that the corresponding property in the destination will be left alone and will remain unchanged. RESULTS a boolean success/failure indicator, TRUE for success. On failure, the destination context will not have been touched at all. NOTES This call does not copy memory at all, it just defines the memory properties of the context passed in. Check CopyMapping() to transport memory properties from one list to another, or CopyContextRegion() to transfer properties from a context to a list (the other direction). The library will not be able to perform checks for correct page alignment, you have to do that yourself. BUGS SEE ALSO SetPropertyList(), ReleaseMapping(), SetPropertiesA(), CopyContextRegion() mmu.library/SetMappingPropertiesA mmu.library/SetMappingPropertiesA NAME SetMappingPropertiesA - set memory attributes in a memory map. SYNOPSIS result = SetMappingPropertiesA( list, flags, mask, lower, size, tags); d0 a0 d1 d2 a1 d0 a2 int SetMappingPropertiesA( struct MinList *, ULONG, ULONG, ULONG, ULONG, struct TagItem *); result = SetMappingProperties( list, flags, mask, lower, size, tag1, ...); int SetMappingProperties( struct MinList *, ULONG, ULONG, ULONG, ULONG, Tag tag1, ...); FUNCTION This call sets attributes of a certain memory range of a given memory map. INPUTS list - a minlist structure keeping the memory map to be altered. flags - a binary flags field for the attributes to define. Check SetProperties() for details about the defined bits. mask - A bit mask of the attributes to be changed. lower - The lower boundary of the logical address to be modified. size - Size of the region to be modified. tags - A tag array with additional data, identical to the tags defined for SetPropertiesA(). RESULTS Unlike SetPropertiesA() or SetPagePropertiesA(), this does not return a boolean value! The result code is 0 on failure, and different from zero on success, though. To be more precise, this routine will return "1" in case of success, and "2" in case the memory map was really altered and is now "dirty", hence upper software layers might require a "rebuild". NOTES This call really doesn't do anything to the MMU, it is just an administration call to modify a memory map - a handy data structure you might want to use for your own memory administration. Its context-based equivalent SetPropertiesA() will, hence, adjust the memory map which is kept by a context, and SetPagePropertiesA() will perform the same operation truely on the hardware. Since this call is not context based, the library will not be able to perform checks for correct page alignment, you have to do that yourself. Especially, note that SetPropertyList() - which attaches a memory map to a context - does not perform any check on this list either. Hence, *NOT* checking for page alignment here might result in an invalid context if you try to attach an incorrectly aligned list to a context later on. BUGS SEE ALSO SetPropertyList(), ReleaseMapping(), SetPropertiesA(), SetPagePropertiesA(), GetMappingPropertiesA() mmu.library/GetMappingPropertiesA mmu.library/GetMappingPropertiesA NAME GetMappingPropertiesA - read memory attributes from a memory map. SYNOPSIS flags = GetMappingPropertiesA( list, lower, tags); d0 a0 a1 a2 ULONG GetMappingPropertiesA( struct MinList *, ULONG, struct TagItem *); result = GetMappingProperties( list, lower, tag1, ...); ULONG GetMappingProperties( struct MinList *, ULONG, Tag tag1, ...); FUNCTION This call reads the page properties of a certain address in memory from a memory map. It is the counterpart of SetMappingPropertiesA() and the memory map analogue of GetPropertiesA(). INPUTS list - a MinList holding the memory map, obtained from either GetMapping(), DupMapping() or NewMapping(). lower - the logical address of the address to investigate. tags - additional tags, identical to those defined for GetPropertiesA(). Check the documentation of this function for details. RESULTS Returns a binary flags field for the attributes to define. See SetPropertiesA() for details. NOTES This call is the analogue of the GetPropertiesA() call. It operates directly on memory maps, unlike the former which operates only on the memory map of a context. This function does not require page alignment because the mmu.library does not have a context to check the alignment restrictions, but you should note that a memory map that is to be attached to a context with DefineMapping() *HAS* to be correctly aligned. This routine is *NOT* safe to be called from within interrupts. BUGS SEE ALSO SetMappingPropertiesA(), SetPropertiesA(), GetPagePropertiesA(), GetPropertiesA() mmu.library/SetPropertyList mmu.library/SetPropertyList NAME SetPropertyList - re-install a backup memory map SYNOPSIS SetPropertyList ( context, list ); a0 a1 void SetPropertyList ( struct MMUContext * , struct MinList * ); FUNCTION This call re-installes a property list, i.e. a complete memory map of a context, obtained from GetMapping() before. INPUTS context - the context the list should be installed in. This should be the same context the list was taken from. list - the property list to install. This list *MUST* have been obtained with GetMapping() before. RESULTS Nothing. The big advantage of this call is that it cannot fail. NOTES The property list will become part of the context and is empty after this call. You can't re-use it for that reason. However, you still need to call ReleaseMapping() with the list pointer you've obtained before. For additional tips how this function should be used, see the GetMapping() function; especially, you can only un-do changes to the software abstraction level of a MMU-tree, and only as long as you haven't called RebuildTree() to translate these into hardware MMU tables. Trying to un-do these changes with SetPropertyList() will fail, and it will even fail if you call RebuildTree() afterwards. SetPropertyList() *does not* inform the software abstraction level about any changes, it is just a quick un-do operation. (For the experts: It even re-installs the "dirty" flags). BUGS SEE ALSO GetMapping(), ReleaseMapping(), RebuildTree() mmu.library/LockContext mmu.library/LockContext NAME LockContext - arbitrate a MMUContext for exclusive access SYNOPSIS LockContext( context ); a0 void LockContext( struct MMUContext * ); FUNCTION Locks a context from modification by any task except the calling task, i.e. implements a semaphore protection for the context passed in. INPUTS context - the context to enter or NULL for the current context. RETURNS NOTES This lock includes locking the memory map by GetMapping(). It is therefore safe to call GetMapping() while holding a context lock. The lock must be released later on with UnlockContext(). BUGS SEE ALSO UnlockContext() mmu.library/UnlockContext mmu.library/UnlockContext NAME UnlockContext - release a MMUContext lock SYNOPSIS UnlockContext( context ); a0 void UnlockContext( struct MMUContext * ); FUNCTION Releases a lock to a MMUContext arbitrated by LockContext(). INPUTS context - the context to enter or NULL for the current context. RETURNS NOTES BUGS SEE ALSO LockContext() mmu.library/GetMMUType mmu.library/GetMMUType NAME GetMMUType - return the type of the MMU available in the system. SYNOPSIS mmu = GetMMUType( ); char GetMMUType( void ); FUNCTION Returns an identifier for the MMU available in the system or NUL in case no MMU is installed. INPUTS RETURNS a character identifying the MMU type: MUTYPE_NONE no working MMU detected. MUTYPE_68851 a 68020 system with an external 68851 MMU. MUTYPE_68030 a 68030 MMU. MUTYPE_68040 the internal 68040 MMU. MUTYPE_68060 the 68060 MMU. NOTES The mmu library is smart enough to detect EC processors without a working MMU, but the library does not detect multiple CPUs in the system. (How?) BUGS SEE ALSO mmu/mmubase.h mmu.library/SuperContext mmu.library/SuperContext NAME SuperContext - find the supervisor context for a given context. SYNOPSIS super = SuperContext( context ); d0 a0 struct MMUContext * SuperContext( struct MMUContext * ); FUNCTION Returns the context that manages the supervisor mode for the user mode context passed in. INPUTS A user mode context or NULL for the current context. RETURNS A pointer to the context managing the supervisor type accesses with- in the current context. NOTES All contexts build by CreateMMUContext are by default user mode contexts. The current version of the library manages one global supervisor tree, and optionally private supervisor trees for private contexts if you ask for one on context creation. This is different to former releases! To find the public supervisor mode context, call DefaultContext() first and pass in its return value to this function. BUGS SEE ALSO DefaultContext(), CreateMMUContext() mmu.library/DefaultContext mmu.library/DefaultContext NAME DefaultContext - get the global default context SYNOPSIS public = DefaultContext( ); d0 struct MMUContext * DefaultContext( void ); FUNCTION Returns the global default user mode context which is used for tasks that are not attached to any other private context. INPUTS RETURNS A pointer to the context managing the user mode accesses for "context less" tasks. NOTES A task is by default part of this default context unless you call EnterMMUContext() and attach it to a different context. Note that you might have to enter even the default context explicitly to be able to use certain features of the exception hook mechanism. BUGS SEE ALSO SuperContext() mmu.library/WithoutMMU mmu.library/WithoutMMU NAME WithoutMMU - execute a short subroutine with the MMU disabled. SYNOPSIS result = WithoutMMU( userFunc ); d0 a5 ULONG WithoutMMU(void *); FUNCTION Executes a small assembly language routine pointed to in a5 in supervisor mode, with all interrupts disabled, and the MMU disabled. All registers are preserved by this call. The function must end with an RTS instruction. INPUTS userFunc - A pointer to a *short* assembly language routine, ending with RTS. The function has full access to all registers. RETURNS whatever was left in register d0 by the called function. NOTES This is a low-level function. Remember that disabling the MMU might or might not be what you want, especially if memory is remapped. BUGS Big trouble if the supervisor stack is in remapped memory. SEE ALSO exec/Supervisor() mmu.library/SetBusError mmu.library/SetBusError NAME SetBusError - define the bus error handler. SYNOPSIS SetBusError ( newfuncptr , oldfuncptrptr ); d0 a0 a1 void SetBusError ( void (*)() , void (**)() ); FUNCTION This defines the bus error handler which is called in case the MMU library exception handler was not able to handle the fault. This happens for true physical bus errors, errors initiated by the unsupported TAS, CAS and CAS2 instructions using "locked transfers" not supported by the amiga hardware, and MOVE16 in- structions causing an access fault. The default bus error handler is whatever the library finds in the autovectors of the CPU when starting up. It is usually the exec fault handler which presents the nice guru 80000002. INPUTS newfuncptr - A pointer to the new bus error handler. It is called without any parameters in supervisor state, with the exception stack frame on the stack. oldfuncptrptr - A pointer to a pointer filled in with the previously defined handler, or NULL. RETURNS NOTES The function pointer is guaranteed to be flushed to memory by the library, the function pointer pointer could be used, for example, to modify the destination of a JMP instruction. The bus error handler *MUST BE IMMEDIATELY* ready for run after this function has to be called. This is a low-level function. You do not want to call it. BUGS SEE ALSO mmu.library/GetMMUContextData mmu.library/GetMMUContextData NAME GetMMUContextData - read MMUContext specific data SYNOPSIS GetMMUContextData ( ctx , id ); d0 a0 d0 ULONG GetMMUContextData ( struct MMUContext * , ULONG ); FUNCTION This function reads various parameters of the MMU context, indexed by an ID from mmu/mmutags.h. All legal tag items of CreateMMContext() are available, plus the following: MGXTAG_PAGESIZE - Return the page size in bytes of the input context. Unlike MCXTAG_PAGEBITS, this is *NOT* an exponent. This is identical to GetPageSize(). MGXTAG_REMAPSIZE - Returns the alignment restriction for remapped memory to be added to the exec memory free list. This is identical to RemapSize(). MGXTAG_ROOT - Return the pointer to the root of the MMU tree. You have to cast the result to an ULONG *. Note that you DO NOT WANT to modify this tree directly. MGXTAG_CONFIG - Returns the pointer to a struct MMUConfig * specifying the complete MMU configuration for this context. You usually DO NOT NEED to touch this. INPUTS ctx - A pointer to a struct MMUContext *. id - An ID specifying which data you want to read. NOTE THAT THIS IS NOT A TAG LIST, but just the tag item id from mmutags.h. RETURNS the data requested. You need to cast it to the correct type. NOTES BUGS SEE ALSO CreateMMUContext(), mmu/config.h mmu.library/SetMMUContextDataA mmu.library/SetMMUContextDataA NAME SetMMUContextDataA - define MMU context specifications on the fly SYNOPSIS SetMMUContextDataA ( ctx , tags ); a0 a1 SetMMUContextData ( ctx , ... ); void SetMMUContextDataA ( struct MMUContext * , struct TagItem * ); void SetMMUContextData ( struct MMUContext * , Tag tag1 , ... ); FUNCTION This function allows to adjust *some* of the MMUContext specifications on the fly. The following tag items of the CreateMMUContextA() call are supported: MCXTAG_BLANKFILL - define the data to read from the dummy "blank" pages. Note that a *working* program should never read this data. MCXTAG_MEMORYATTRS - define the memory attributes the MMU tables will be allocated from. This will *NOT* reallocate the MMU tables already build, cf. exec/memory.h MCXTAG_EXECBASE - specify whether or not page 0 will be threated specially and accesses to the first Kbyte should be emulated. If set to FALSE, the first page will be threated as all other pages. MCXTAG_ZEROBASE - Specify a base address for where possibly emulated zero page accesses have to be redirected to. This address is usually ignored unless the zero- page is invalidated and MCXTAG_EXEBASE is TRUE. For the messy details, check the CreateMMUContext() autodocs. No other tag items are valid here. INPUTS ctx - A pointer to a struct MMUContext *. tags - A tag list containing the parameters to be adjusted. RETURNS NOTES BUGS SEE ALSO CreateMMUContext(), exec/memory.h mmu.library/BuildIndirect mmu.library/BuildIndirect NAME BuildIndirect - build a true hardware page descriptor. SYNOPSIS descr = BuildIndirect ( ctx , address , props ); d0 a0 d0 d1 ULONG BuildIndirect ( struct MMUContext * , ULONG , ULONG ); FUNCTION This function builds a true hardware page descriptor, to be used for the MAPP_INDIRECT property. INPUTS ctx - the MMUContext handle in which this descriptor is to be used as the destination of a MAPP_INDIRECT descriptor. address - in case this descriptor is "valid", this is the PHYSICAL destination address, to be told to the MMU, to which accesses will be redirected to. Unlike SetPropertiesA(), there is *NO* MAPP_REMAPPED bit. In case you do not want remapping, set this to the logical address. DO NOT LEAVE THIS BLANK or accesses will be redirected to address 0 - which is most likely not want you want. Note that this address must be, as all other addresses the MMU cares about, page aligned! In case this descriptor is of invalid type, the address can be used for your purposes, but note that this MUST STILL be a number which is page aligned for the given context. It *MAY NOT* be arbitrary. props - Properties for the descriptor to be defined. NOTE THAT THIS IS A TRUE HARDWARE DESCRIPTOR! The library WILL NOT BE ABLE to help you out by emulating missing features of one MMU or another. Instead, it will just ignore them. This means for you, specifically, that only a minor subset of the usual properties may be used safely here, and that parsing the hardware properties later on with GetIndirect() might result in different properties than you intended because of missing features of the MMU in use. To be precise, the following properties *might* be available - meaning that all others ARE NOT! MAPP_WRITEPROTECTED - The page will be write protected. Writes to this area will cause a segmentation fault. MAPP_USED - The "used" bit of the pages will be set. The CPU will set this bit automatically as soon as the pages are accessed. MAPP_MODIFIED - The "modified" bit of the pages will be set. The CPU will set this bit automatically as soon as a write is performed to the page in question. DO NOT SET THIS BIT TOGETHER WITH MAPP_WRITEPROTECTED OR WITHOUT MAPP_USED or the CPU might hang. MAPP_INVALID - The page will be marked as invalid. Accessing it will invoke the bus error hook. See below for how to mark this page as REMAIRABLE. Note that the MAPP_REPAIRABLE bit is *here* not available. MAPP_SWAPPED - The page will be marked as swapped out. This is for this kind of descriptors identical to MAPP_INVALID and will be read as such later on. MAPP_CACHEINHIBIT - The page will be marked as non- cacheable. MAPP_IMPRECISEEXECPTION - The page will be marked as "imprecise exception". MAPP_CACHEINHIBIT is mandatory in this case or this flag does nothing. Only avail- able for the 060, ignored and read as zero by all others. MAPP_NONSERIALIZED - The page will be marked as serialized. MAPP_CACHEINHIBIT is mandatory if this property is selected. Only available for the 040, ignored and read as zero by all others. MAPP_COPYBACK - The page will be marked as "copyback" instead of "writethrough". Generally re- commended since this is faster for the '40 and '60. MAPP_CACHEINHIBIT *MUST* be disabled for this to work. Only available for the 040 and 060, ignored and read as zero by others. MAPP_USERPAGE0 - Set user page attribute 0, only available for the 040 and 060, ignored and read as zero by all others. The status of this bit appears on special pins of the CPU and might be required by some hardware, so don't play with this. MAPP_USERPAGE1 - Set user page attribute 1, see above for details. MAPP_GLOBAL - DIFFERENT TO SetProperties() and others! Set the GLOBAL bit in the page descriptor, only avail- able for the 040 and 060, ignored and read as zero by all others. Setting this bit means that certain specialized instructions will not flush this descriptor from the cache (the ATC) of the MMU. The mmu.library writes only descriptors without this bit set and does not use these instructions. It will always flush descriptors independent of the G bit. There is little use of this bit. RESULTS a page descriptor for the current MMU in use, designed and to be used for as the destination of an MAPP_INDIRECT descriptor. NOT to be used as a true page descriptor, and NOT to be used as a table descriptor. In case the library finds no MMU or the alignment restrictions aren't satisfied, it will return BAD_DESCRIPTOR (0x03), it WILL NOT return NULL as this is a "valid invalid" descriptor. NOTES Note specifically that MAPP_SUPERVISORONLY *IS NOT* supported. The mmu.library enforces a distinct user/supervisor model and as such you might want to install an invalid descriptor into the user table and a valid descriptor into the supervisor table to emulate this feature. True "supervisor only" descriptors are available for the 040 and 060 anyways, but this "emulation" works for all MMUs. MAPP_REMAPPED is not supported either because you have to specify a physical destination address in all cases, even if no remapping has to be performed. Use the logical address as physical address in case remapping is not desired. MAPP_REPAIRABLE is not available because this flag is in fact an emulation provided by the library. However, you may make access faults to this page repairable by setting the MAPP_REPAIRABLE bit for the MAPP_INDIRECT descriptor that POINTS to the descriptor you're building by this call. This will be enough to inform the library about how to treat access faults. How to use this function: Allocate four bytes of memory, long-word aligned, and gets its TRUE PHYSICAL location with PhysicalLocation(), build a descriptor with this call and install it into this memory by calling SetIndirect(). *DO NOT* write it to the memory yourself! Due to CPU caching effects, this must be done by the library. Then build a MAPP_INDIRECT descriptor, and tell the library with the MAPTAG_DESCRIPTOR tag of SetPropertiesA() to make it point to your memory. In case you want access faults on this to be repairable, set the MAPP_REPAIRABLE bit for this call. In case you want it write protected but want to ignore write accesses, set MAPP_ROM, too. Then call RebuildTree() as usual. In case you want to exchange descriptors really fast - this is after all what indirect descriptors are designed for - build all descriptors you require in a first step and keep them. A single call to SetIndirect() will exchange them VERY RAPIDLY which is ideal for certain applications. BUGS Much more must be said about this function. It is definitely an advanced feature, so don't play with this in case you don't know what it does. SEE ALSO SetIndirect(), GetIndirect() mmu.library/SetIndirect mmu.library/SetIndirect NAME SetIndirect - Write a page descritor to memory SYNOPSIS SetIndirect ( destination , logical , descriptor ); a0 a1 d0 void SetIndirect ( ULONG *, ULONG, ULONG ); FUNCTION Write a page descriptor, used as the destination of one or several MAPP_INDIRECT descriptors, out to memory and make the MMU aware of the change. INPUTS destination - the memory location to which the descriptor should be written to. This is the same address specified by MAPTAD_DESCRIPTOR in the corresponding SetProperties() call. NOTE THAT THIS IS A PHYSICAL, NOT A LOGICAL ADDRESS. logical - The logical address covered by this descriptor, i.e. the address of the page which this descriptor is managing. In case you installed the same descriptor for several logical addresses, specify -1L. descriptor - The descriptor to install. RESULTS doesn't return a result. NOTES Do NOT try to install a descriptor yourself, even though this *seems* to be more effective. Somewhat more must be done than just writing the descriptor to memory. This call ensures that the descriptor is really written out to memory, and really fetched by the MMU. Specifying -1 as logical address is possible and supported but *slightly* less efficient than giving the correct logical address. This call DOES NOT ensure that all data in the page to be modified is really written out. Hence, if you change the cache mode, the protection status or the validity status of a page, you should call CacheClearU() or CacheClearE() before. Furthermore, note that the cache of the 020 and 030 keeps logical addresses. On these processors, you must flush the cache, too, if you install a descriptor which points to a different physical address. This call is *very* effective, there is little reason to try this yourself, not counting the portability problems. BUGS SEE ALSO GetIndirect(), BuildIndirect() mmu.library/GetIndirect mmu.library/GetIndirect NAME GetIndirect - Read a hardware page descritor from memory SYNOPSIS GetIndirect ( ctx , adt , address ); a0 a1 d0 void GetIndirect ( struct MMUContext *, struct AbstractDescriptor *, ULONG * ); FUNCTION Reads a true hardware page descriptor, used as the destination of one or several MAPP_INDIRECT descriptors, and places its data in the AbstractDescriptor structure. INPUTS ctx - the MMU context handle this page descriptor belongs. adt - An abstract table descriptor, to be filled out with the descriptor data. address - the address from where the descriptor is to be read. This is the same address which has been passed as argument to the MAPTAG_DESCRIPTOR tag of the SetPropertiesA() call when building the indirect descriptor. RESULTS no direct result code, but the AbstractDescriptor is filled out: struct AbstractDescriptor { ULONG atd_Pointer; ULONG atd_Properties; UWORD atd_LowerLimit; UWORD atd_UpperLimit; UBYTE atd_ThisType; UBYTE atd_NextType; UWORD atd_reserved; }; atd_Pointer is either the physical address the accesses to the page(s) this descriptor is installed for are redirected to, or the user data if this descriptor is of invalid type. This is the same value that was passed in as "address" argument to the corresponding BuildProperties() call. atd_Properties is the set of MMU properties read from the descriptor. This NEED NOT to be identical to the properties setup by BuildIndirect(), for two reasons: First, the MMU sets the USED and MODIFIED attributes as soon as any access or a write access happens to the page(s) handled by the descriptor. Second, not all MMUs support all properties. Unavailable properties are ignored by BuildIndirect(), and read as zero by this function. All other fields are currently not documented and should not be read. NOTES Do NOT try to read a descriptor yourself, even though this *seems* to be more effective. Somewhat more care must be kept for doing this. NOT following this rule might even lock up your machine! This call is *very* effective, there is little reason to try this yourself, not counting the portability problems. BUGS SEE ALSO SetIndirect(), BuildIndirect(), mmu/descriptor.h