Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

sparc: Remove Documentation/sparc/sbus_drivers.txt

None of the text in this document is relevant any more.

Signed-off-by: David S. Miller <davem@davemloft.net>
  • Loading branch information...
commit 0c0db98b50ed1217c0dbf4051722034ba314d06e 1 parent 7eb1aae
davem330 davem330 authored

Showing 1 changed file with 0 additions and 309 deletions. Show diff stats Hide diff stats

  1. +0 309 Documentation/sparc/sbus_drivers.txt
309 Documentation/sparc/sbus_drivers.txt
... ... @@ -1,309 +0,0 @@
1   -
2   - Writing SBUS Drivers
3   -
4   - David S. Miller (davem@redhat.com)
5   -
6   - The SBUS driver interfaces of the Linux kernel have been
7   -revamped completely for 2.4.x for several reasons. Foremost were
8   -performance and complexity concerns. This document details these
9   -new interfaces and how they are used to write an SBUS device driver.
10   -
11   - SBUS drivers need to include <asm/sbus.h> to get access
12   -to functions and structures described here.
13   -
14   - Probing and Detection
15   -
16   - Each SBUS device inside the machine is described by a
17   -structure called "struct sbus_dev". Likewise, each SBUS bus
18   -found in the system is described by a "struct sbus_bus". For
19   -each SBUS bus, the devices underneath are hung in a tree-like
20   -fashion off of the bus structure.
21   -
22   - The SBUS device structure contains enough information
23   -for you to implement your device probing algorithm and obtain
24   -the bits necessary to run your device. The most commonly
25   -used members of this structure, and their typical usage,
26   -will be detailed below.
27   -
28   - Here is a piece of skeleton code for performing a device
29   -probe in an SBUS driver under Linux:
30   -
31   - static int __devinit mydevice_probe_one(struct sbus_dev *sdev)
32   - {
33   - struct mysdevice *mp = kzalloc(sizeof(*mp), GFP_KERNEL);
34   -
35   - if (!mp)
36   - return -ENODEV;
37   -
38   - ...
39   - dev_set_drvdata(&sdev->ofdev.dev, mp);
40   - return 0;
41   - ...
42   - }
43   -
44   - static int __devinit mydevice_probe(struct of_device *dev,
45   - const struct of_device_id *match)
46   - {
47   - struct sbus_dev *sdev = to_sbus_device(&dev->dev);
48   -
49   - return mydevice_probe_one(sdev);
50   - }
51   -
52   - static int __devexit mydevice_remove(struct of_device *dev)
53   - {
54   - struct sbus_dev *sdev = to_sbus_device(&dev->dev);
55   - struct mydevice *mp = dev_get_drvdata(&dev->dev);
56   -
57   - return mydevice_remove_one(sdev, mp);
58   - }
59   -
60   - static struct of_device_id mydevice_match[] = {
61   - {
62   - .name = "mydevice",
63   - },
64   - {},
65   - };
66   -
67   - MODULE_DEVICE_TABLE(of, mydevice_match);
68   -
69   - static struct of_platform_driver mydevice_driver = {
70   - .match_table = mydevice_match,
71   - .probe = mydevice_probe,
72   - .remove = __devexit_p(mydevice_remove),
73   - .driver = {
74   - .name = "mydevice",
75   - },
76   - };
77   -
78   - static int __init mydevice_init(void)
79   - {
80   - return of_register_driver(&mydevice_driver, &sbus_bus_type);
81   - }
82   -
83   - static void __exit mydevice_exit(void)
84   - {
85   - of_unregister_driver(&mydevice_driver);
86   - }
87   -
88   - module_init(mydevice_init);
89   - module_exit(mydevice_exit);
90   -
91   - The mydevice_match table is a series of entries which
92   -describes what SBUS devices your driver is meant for. In the
93   -simplest case you specify a string for the 'name' field. Every
94   -SBUS device with a 'name' property matching your string will
95   -be passed one-by-one to your .probe method.
96   -
97   - You should store away your device private state structure
98   -pointer in the drvdata area so that you can retrieve it later on
99   -in your .remove method.
100   -
101   - Any memory allocated, registers mapped, IRQs registered,
102   -etc. must be undone by your .remove method so that all resources
103   -of your device are released by the time it returns.
104   -
105   - You should _NOT_ use the for_each_sbus(), for_each_sbusdev(),
106   -and for_all_sbusdev() interfaces. They are deprecated, will be
107   -removed, and no new driver should reference them ever.
108   -
109   - Mapping and Accessing I/O Registers
110   -
111   - Each SBUS device structure contains an array of descriptors
112   -which describe each register set. We abuse struct resource for that.
113   -They each correspond to the "reg" properties provided by the OBP firmware.
114   -
115   - Before you can access your device's registers you must map
116   -them. And later if you wish to shutdown your driver (for module
117   -unload or similar) you must unmap them. You must treat them as
118   -a resource, which you allocate (map) before using and free up
119   -(unmap) when you are done with it.
120   -
121   - The mapping information is stored in an opaque value
122   -typed as an "unsigned long". This is the type of the return value
123   -of the mapping interface, and the arguments to the unmapping
124   -interface. Let's say you want to map the first set of registers.
125   -Perhaps part of your driver software state structure looks like:
126   -
127   - struct mydevice {
128   - unsigned long control_regs;
129   - ...
130   - struct sbus_dev *sdev;
131   - ...
132   - };
133   -
134   - At initialization time you then use the sbus_ioremap
135   -interface to map in your registers, like so:
136   -
137   - static void init_one_mydevice(struct sbus_dev *sdev)
138   - {
139   - struct mydevice *mp;
140   - ...
141   -
142   - mp->control_regs = sbus_ioremap(&sdev->resource[0], 0,
143   - CONTROL_REGS_SIZE, "mydevice regs");
144   - if (!mp->control_regs) {
145   - /* Failure, cleanup and return. */
146   - }
147   - }
148   -
149   - Second argument to sbus_ioremap is an offset for
150   -cranky devices with broken OBP PROM. The sbus_ioremap uses only
151   -a start address and flags from the resource structure.
152   -Therefore it is possible to use the same resource to map
153   -several sets of registers or even to fabricate a resource
154   -structure if driver gets physical address from some private place.
155   -This practice is discouraged though. Use whatever OBP PROM
156   -provided to you.
157   -
158   - And here is how you might unmap these registers later at
159   -driver shutdown or module unload time, using the sbus_iounmap
160   -interface:
161   -
162   - static void mydevice_unmap_regs(struct mydevice *mp)
163   - {
164   - sbus_iounmap(mp->control_regs, CONTROL_REGS_SIZE);
165   - }
166   -
167   - Finally, to actually access your registers there are 6
168   -interface routines at your disposal. Accesses are byte (8 bit),
169   -word (16 bit), or longword (32 bit) sized. Here they are:
170   -
171   - u8 sbus_readb(unsigned long reg) /* read byte */
172   - u16 sbus_readw(unsigned long reg) /* read word */
173   - u32 sbus_readl(unsigned long reg) /* read longword */
174   - void sbus_writeb(u8 value, unsigned long reg) /* write byte */
175   - void sbus_writew(u16 value, unsigned long reg) /* write word */
176   - void sbus_writel(u32 value, unsigned long reg) /* write longword */
177   -
178   - So, let's say your device has a control register of some sort
179   -at offset zero. The following might implement resetting your device:
180   -
181   - #define CONTROL 0x00UL
182   -
183   - #define CONTROL_RESET 0x00000001 /* Reset hardware */
184   -
185   - static void mydevice_reset(struct mydevice *mp)
186   - {
187   - sbus_writel(CONTROL_RESET, mp->regs + CONTROL);
188   - }
189   -
190   - Or perhaps there is a data port register at an offset of
191   -16 bytes which allows you to read bytes from a fifo in the device:
192   -
193   - #define DATA 0x10UL
194   -
195   - static u8 mydevice_get_byte(struct mydevice *mp)
196   - {
197   - return sbus_readb(mp->regs + DATA);
198   - }
199   -
200   - It's pretty straightforward, and clueful readers may have
201   -noticed that these interfaces mimick the PCI interfaces of the
202   -Linux kernel. This was not by accident.
203   -
204   - WARNING:
205   -
206   - DO NOT try to treat these opaque register mapping
207   - values as a memory mapped pointer to some structure
208   - which you can dereference.
209   -
210   - It may be memory mapped, it may not be. In fact it
211   - could be a physical address, or it could be the time
212   - of day xor'd with 0xdeadbeef. :-)
213   -
214   - Whatever it is, it's an implementation detail. The
215   - interface was done this way to shield the driver
216   - author from such complexities.
217   -
218   - Doing DVMA
219   -
220   - SBUS devices can perform DMA transactions in a way similar
221   -to PCI but dissimilar to ISA, e.g. DMA masters supply address.
222   -In contrast to PCI, however, that address (a bus address) is
223   -translated by IOMMU before a memory access is performed and therefore
224   -it is virtual. Sun calls this procedure DVMA.
225   -
226   - Linux supports two styles of using SBUS DVMA: "consistent memory"
227   -and "streaming DVMA". CPU view of consistent memory chunk is, well,
228   -consistent with a view of a device. Think of it as an uncached memory.
229   -Typically this way of doing DVMA is not very fast and drivers use it
230   -mostly for control blocks or queues. On some CPUs we cannot flush or
231   -invalidate individual pages or cache lines and doing explicit flushing
232   -over ever little byte in every control block would be wasteful.
233   -
234   -Streaming DVMA is a preferred way to transfer large amounts of data.
235   -This process works in the following way:
236   -1. a CPU stops accessing a certain part of memory,
237   - flushes its caches covering that memory;
238   -2. a device does DVMA accesses, then posts an interrupt;
239   -3. CPU invalidates its caches and starts to access the memory.
240   -
241   -A single streaming DVMA operation can touch several discontiguous
242   -regions of a virtual bus address space. This is called a scatter-gather
243   -DVMA.
244   -
245   -[TBD: Why do not we neither Solaris attempt to map disjoint pages
246   -into a single virtual chunk with the help of IOMMU, so that non SG
247   -DVMA masters would do SG? It'd be very helpful for RAID.]
248   -
249   - In order to perform a consistent DVMA a driver does something
250   -like the following:
251   -
252   - char *mem; /* Address in the CPU space */
253   - u32 busa; /* Address in the SBus space */
254   -
255   - mem = (char *) sbus_alloc_consistent(sdev, MYMEMSIZE, &busa);
256   -
257   - Then mem is used when CPU accesses this memory and u32
258   -is fed to the device so that it can do DVMA. This is typically
259   -done with an sbus_writel() into some device register.
260   -
261   - Do not forget to free the DVMA resources once you are done:
262   -
263   - sbus_free_consistent(sdev, MYMEMSIZE, mem, busa);
264   -
265   - Streaming DVMA is more interesting. First you allocate some
266   -memory suitable for it or pin down some user pages. Then it all works
267   -like this:
268   -
269   - char *mem = argumen1;
270   - unsigned int size = argument2;
271   - u32 busa; /* Address in the SBus space */
272   -
273   - *mem = 1; /* CPU can access */
274   - busa = sbus_map_single(sdev, mem, size);
275   - if (busa == 0) .......
276   -
277   - /* Tell the device to use busa here */
278   - /* CPU cannot access the memory without sbus_dma_sync_single() */
279   -
280   - sbus_unmap_single(sdev, busa, size);
281   - if (*mem == 0) .... /* CPU can access again */
282   -
283   - It is possible to retain mappings and ask the device to
284   -access data again and again without calling sbus_unmap_single.
285   -However, CPU caches must be invalidated with sbus_dma_sync_single
286   -before such access.
287   -
288   -[TBD but what about writeback caches here... do we have any?]
289   -
290   - There is an equivalent set of functions doing the same thing
291   -only with several memory segments at once for devices capable of
292   -scatter-gather transfers. Use the Source, Luke.
293   -
294   - Examples
295   -
296   - drivers/net/sunhme.c
297   - This is a complicated driver which illustrates many concepts
298   -discussed above and plus it handles both PCI and SBUS boards.
299   -
300   - drivers/scsi/esp.c
301   - Check it out for scatter-gather DVMA.
302   -
303   - drivers/sbus/char/bpp.c
304   - A non-DVMA device.
305   -
306   - drivers/net/sunlance.c
307   - Lance driver abuses consistent mappings for data transfer.
308   -It is a nifty trick which we do not particularly recommend...
309   -Just check it out and know that it's legal.

0 comments on commit 0c0db98

Please sign in to comment.
Something went wrong with that request. Please try again.