ip26_ucmem(D3)

NAME
     ip26_enable_ucmem, ip26_return_ucmem - change memory mode on IP26 or IP28
     processor

SYNOPSIS
     #include <sys/systm.h>
     ulong ip26_enable_ucmem(void);
     void ip26_return_ucmem(ulong oldstate);

   Arguments
     oldstate  Previous memory mode. (Only ip26_return_ucmem has an input
               argument.)

DESCRIPTION
     The IP26 motherboard (Power Indigo2, Indigo2 10000, Power Challenge M)
     has 2 memory setup modes.  These modes only affect CPU accesses to main
     memory.  They have no impact on CPU accesses to device registers (PIOs),
     or on DMA between devices and main memory.  One of the modes (the
     default) is set up to allow CPU accesses to main memory to occur as fast
     as possible, but restricts the CPU from making uncached writes to main
     memory.  The other mode is set up to allow any CPU accesses to main
     memory (cached or uncached), but slows down CPU accesses to main memory.
     If a driver makes uncached writes to main memory without having
     previously called ip26_enable_ucmem, it will crash the system.

     The ip26_enable_ucmem function allows the processor to perform uncached
     writes to main memory.  During the interval between calling
     ip26_enable_ucmem and ip26_return_ucmem, all processor accesses to main
     memory (cached or uncached) perform slower.  Therefore, use of this
     function is recommended only if the device driver is unable for some
     reason to use cached accesses, and cache coherency operations.  (See the
     dki_dcache_*(D3) routines.)  The value returned from ip26_enable_ucmem
     must be saved and passed as the argument to a following call to
     ip26_return_ucmem.

     The ip26_return_ucmem returns the memory mode to its state from before
     the matching call to ip26_enable_ucmem.  These functions are designed to
     always be used as a matched pair, in which a driver enables uncached
     writes, performs the writes, and then returns the memory system to its
     previous mode.  The reason for using ip26_return_ucmem instead of a
     function which simply disallows uncached writes is that it is possible to
     have an interrupt service routine which needs to do uncached accesses.
     This can lead to a scenario where a driver top-half enables uncached
     writes, but before performing all the writes gets interrupted.  The
     interrupt service routine could then enable uncached writes, perform its
     writes, and then disable uncached writes.  Upon return from the ISR, the
     driver top-half would then attempt to perform uncached writes, and crash
     the system.
     The ip26_enable_ucmem and ip26_return_ucmem functions are only necessary
     for drivers which run on IP26 or IP28 processors, but stubs are provided
     for other architectures so that driver binaries will function across
     platforms.

   Return Values
     The ip26_enable_ucmem function returns the previous memory system mode.
     This must then be passed in as the argument to the matching call to
     ip26_return_ucmem.

   Synchronization Considerations
     The ip26_enable_ucmem and ip26_return_ucmem functions do not sleep, so
     they are callable from anywhere in a device driver.

   See Also
     dki_dcache_inval(D3X), dki_dcache_wb(D3X), dki_dcache_wbinval(D3X)