Linux-2.6.12-rc2v2.6.12-rc2

Initial git repository build. I'm not bothering with the full history,
even though we have it. We can create a separate "historical" git
archive of that later if we want to, and in the meantime it's about
3.2GB when imported into git - space that would just make the early
git days unnecessarily complicated, when we don't have a lot of good
infrastructure for it.

Let it rip!

1 files changed, 272 insertions, 0 deletions

diff --git a/Documentation/sparc/sbus_drivers.txt b/Documentation/sparc/sbus_drivers.txt
new file mode 100644
index 000000000000..876195dc2aef
--- /dev/null
+++ b/Documentation/sparc/sbus_drivers.txt
@@ -0,0 +1,272 @@
+
+                Writing SBUS Drivers
+
+            David S. Miller (davem@redhat.com)
+
+        The SBUS driver interfaces of the Linux kernel have been
+revamped completely for 2.4.x for several reasons.  Foremost were
+performance and complexity concerns.  This document details these
+new interfaces and how they are used to write an SBUS device driver.
+
+        SBUS drivers need to include <asm/sbus.h> to get access
+to functions and structures described here.
+
+                Probing and Detection
+
+        Each SBUS device inside the machine is described by a
+structure called "struct sbus_dev".  Likewise, each SBUS bus
+found in the system is described by a "struct sbus_bus".  For
+each SBUS bus, the devices underneath are hung in a tree-like
+fashion off of the bus structure.
+
+        The SBUS device structure contains enough information
+for you to implement your device probing algorithm and obtain
+the bits necessary to run your device.  The most commonly
+used members of this structure, and their typical usage,
+will be detailed below.
+
+        Here is how probing is performed by an SBUS driver
+under Linux:
+
+        static void init_one_mydevice(struct sbus_dev *sdev)
+        {
+                ...
+        }
+
+        static int mydevice_match(struct sbus_dev *sdev)
+        {
+                if (some_criteria(sdev))
+                        return 1;
+                return 0;
+        }
+
+        static void mydevice_probe(void)
+        {
+                struct sbus_bus *sbus;
+                struct sbus_dev *sdev;
+
+                for_each_sbus(sbus) {
+                        for_each_sbusdev(sdev, sbus) {
+                                if (mydevice_match(sdev))
+                                        init_one_mydevice(sdev);
+                        }
+                }
+        }
+
+        All this does is walk through all SBUS devices in the
+system, checks each to see if it is of the type which
+your driver is written for, and if so it calls the init
+routine to attach the device and prepare to drive it.
+
+        "init_one_mydevice" might do things like allocate software
+state structures, map in I/O registers, place the hardware
+into an initialized state, etc.
+
+                Mapping and Accessing I/O Registers
+
+        Each SBUS device structure contains an array of descriptors
+which describe each register set. We abuse struct resource for that.
+They each correspond to the "reg" properties provided by the OBP firmware.
+
+        Before you can access your device's registers you must map
+them.  And later if you wish to shutdown your driver (for module
+unload or similar) you must unmap them.  You must treat them as
+a resource, which you allocate (map) before using and free up
+(unmap) when you are done with it.
+
+        The mapping information is stored in an opaque value
+typed as an "unsigned long".  This is the type of the return value
+of the mapping interface, and the arguments to the unmapping
+interface.  Let's say you want to map the first set of registers.
+Perhaps part of your driver software state structure looks like:
+
+        struct mydevice {
+                unsigned long control_regs;
+           ...
+                struct sbus_dev *sdev;
+           ...
+        };
+
+        At initialization time you then use the sbus_ioremap
+interface to map in your registers, like so:
+
+        static void init_one_mydevice(struct sbus_dev *sdev)
+        {
+                struct mydevice *mp;
+                ...
+
+                mp->control_regs = sbus_ioremap(&sdev->resource[0], 0,
+                                        CONTROL_REGS_SIZE, "mydevice regs");
+                if (!mp->control_regs) {
+                        /* Failure, cleanup and return. */
+                }
+        }
+
+        Second argument to sbus_ioremap is an offset for
+cranky devices with broken OBP PROM. The sbus_ioremap uses only
+a start address and flags from the resource structure.
+Therefore it is possible to use the same resource to map
+several sets of registers or even to fabricate a resource
+structure if driver gets physical address from some private place.
+This practice is discouraged though. Use whatever OBP PROM
+provided to you.
+
+        And here is how you might unmap these registers later at
+driver shutdown or module unload time, using the sbus_iounmap
+interface:
+
+        static void mydevice_unmap_regs(struct mydevice *mp)
+        {
+                sbus_iounmap(mp->control_regs, CONTROL_REGS_SIZE);
+        }
+
+        Finally, to actually access your registers there are 6
+interface routines at your disposal.  Accesses are byte (8 bit),
+word (16 bit), or longword (32 bit) sized.  Here they are:
+
+        u8 sbus_readb(unsigned long reg)                /* read byte */
+        u16 sbus_readw(unsigned long reg)               /* read word */
+        u32 sbus_readl(unsigned long reg)               /* read longword */
+        void sbus_writeb(u8 value, unsigned long reg)   /* write byte */
+        void sbus_writew(u16 value, unsigned long reg)  /* write word */
+        void sbus_writel(u32 value, unsigned long reg)  /* write longword */
+
+        So, let's say your device has a control register of some sort
+at offset zero.  The following might implement resetting your device:
+
+        #define CONTROL         0x00UL
+
+        #define CONTROL_RESET   0x00000001      /* Reset hardware */
+
+        static void mydevice_reset(struct mydevice *mp)
+        {
+                sbus_writel(CONTROL_RESET, mp->regs + CONTROL);
+        }
+
+        Or perhaps there is a data port register at an offset of
+16 bytes which allows you to read bytes from a fifo in the device:
+
+        #define DATA            0x10UL
+
+        static u8 mydevice_get_byte(struct mydevice *mp)
+        {
+                return sbus_readb(mp->regs + DATA);
+        }
+
+        It's pretty straightforward, and clueful readers may have
+noticed that these interfaces mimick the PCI interfaces of the
+Linux kernel.  This was not by accident.
+
+        WARNING:
+
+                DO NOT try to treat these opaque register mapping
+                values as a memory mapped pointer to some structure
+                which you can dereference.
+
+                It may be memory mapped, it may not be.  In fact it
+                could be a physical address, or it could be the time
+                of day xor'd with 0xdeadbeef.  :-)
+
+                Whatever it is, it's an implementation detail.  The
+                interface was done this way to shield the driver
+                author from such complexities.
+
+                        Doing DVMA
+
+        SBUS devices can perform DMA transactions in a way similar
+to PCI but dissimilar to ISA, e.g. DMA masters supply address.
+In contrast to PCI, however, that address (a bus address) is
+translated by IOMMU before a memory access is performed and therefore
+it is virtual. Sun calls this procedure DVMA.
+
+        Linux supports two styles of using SBUS DVMA: "consistent memory"
+and "streaming DVMA". CPU view of consistent memory chunk is, well,
+consistent with a view of a device. Think of it as an uncached memory.
+Typically this way of doing DVMA is not very fast and drivers use it
+mostly for control blocks or queues. On some CPUs we cannot flush or
+invalidate individual pages or cache lines and doing explicit flushing
+over ever little byte in every control block would be wasteful.
+
+Streaming DVMA is a preferred way to transfer large amounts of data.
+This process works in the following way:
+1. a CPU stops accessing a certain part of memory,
+   flushes its caches covering that memory;
+2. a device does DVMA accesses, then posts an interrupt;
+3. CPU invalidates its caches and starts to access the memory.
+
+A single streaming DVMA operation can touch several discontiguous
+regions of a virtual bus address space. This is called a scatter-gather
+DVMA.
+
+[TBD: Why do not we neither Solaris attempt to map disjoint pages
+into a single virtual chunk with the help of IOMMU, so that non SG
+DVMA masters would do SG? It'd be very helpful for RAID.]
+
+        In order to perform a consistent DVMA a driver does something
+like the following:
+
+        char *mem;              /* Address in the CPU space */
+        u32 busa;               /* Address in the SBus space */
+
+        mem = (char *) sbus_alloc_consistent(sdev, MYMEMSIZE, &busa);
+
+        Then mem is used when CPU accesses this memory and u32
+is fed to the device so that it can do DVMA. This is typically
+done with an sbus_writel() into some device register.
+
+        Do not forget to free the DVMA resources once you are done:
+
+        sbus_free_consistent(sdev, MYMEMSIZE, mem, busa);
+
+        Streaming DVMA is more interesting. First you allocate some
+memory suitable for it or pin down some user pages. Then it all works
+like this:
+
+        char *mem = argumen1;
+        unsigned int size = argument2;
+        u32 busa;               /* Address in the SBus space */
+
+        *mem = 1;               /* CPU can access */
+        busa = sbus_map_single(sdev, mem, size);
+        if (busa == 0) .......
+
+        /* Tell the device to use busa here */
+        /* CPU cannot access the memory without sbus_dma_sync_single() */
+
+        sbus_unmap_single(sdev, busa, size);
+        if (*mem == 0) ....     /* CPU can access again */
+
+        It is possible to retain mappings and ask the device to
+access data again and again without calling sbus_unmap_single.
+However, CPU caches must be invalidated with sbus_dma_sync_single
+before such access.
+
+[TBD but what about writeback caches here... do we have any?]
+
+        There is an equivalent set of functions doing the same thing
+only with several memory segments at once for devices capable of
+scatter-gather transfers. Use the Source, Luke.
+
+                        Examples
+
+        drivers/net/sunhme.c
+        This is a complicated driver which illustrates many concepts
+discussed above and plus it handles both PCI and SBUS boards.
+
+        drivers/scsi/esp.c
+        Check it out for scatter-gather DVMA.
+
+        drivers/sbus/char/bpp.c
+        A non-DVMA device.
+
+        drivers/net/sunlance.c
+        Lance driver abuses consistent mappings for data transfer.
+It is a nifty trick which we do not particularly recommend...
+Just check it out and know that it's legal.
+
+                        Bad examples, do NOT use
+
+        drivers/video/cgsix.c
+        This one uses result of sbus_ioremap as if it is an address.
+This does NOT work on sparc64 and therefore is broken. We will
+convert it at a later date.