summaryrefslogtreecommitdiff
path: root/Documentation/sparc/sbus_drivers.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/sparc/sbus_drivers.txt')
-rw-r--r--Documentation/sparc/sbus_drivers.txt272
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.