aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/sparc
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/sparc')
-rw-r--r--Documentation/sparc/README-2.546
-rw-r--r--Documentation/sparc/sbus_drivers.txt272
2 files changed, 318 insertions, 0 deletions
diff --git a/Documentation/sparc/README-2.5 b/Documentation/sparc/README-2.5
new file mode 100644
index 000000000000..806fe490a56d
--- /dev/null
+++ b/Documentation/sparc/README-2.5
@@ -0,0 +1,46 @@
1BTFIXUP
2-------
3
4To build new kernels you have to issue "make image". The ready kernel
5in ELF format is placed in arch/sparc/boot/image. Explanation is below.
6
7BTFIXUP is a unique feature of Linux/sparc among other architectures,
8developed by Jakub Jelinek (I think... Obviously David S. Miller took
9part, too). It allows to boot the same kernel at different
10sub-architectures, such as sun4c, sun4m, sun4d, where SunOS uses
11different kernels. This feature is convinient for people who you move
12disks between boxes and for distrution builders.
13
14To function, BTFIXUP must link the kernel "in the draft" first,
15analyze the result, write a special stub code based on that, and
16build the final kernel with the stub (btfix.o).
17
18Kai Germaschewski improved the build system of the kernel in the 2.5 series
19significantly. Unfortunately, the traditional way of running the draft
20linking from architecture specific Makefile before the actual linking
21by generic Makefile is nearly impossible to support properly in the
22new build system. Therefore, the way we integrate BTFIXUP with the
23build system was changed in 2.5.40. Now, generic Makefile performs
24the draft linking and stores the result in file vmlinux. Architecture
25specific post-processing invokes BTFIXUP machinery and final linking
26in the same way as other architectures do bootstraps.
27
28Implications of that change are as follows.
29
301. Hackers must type "make image" now, instead of just "make", in the same
31 way as s390 people do now. It is analogous to "make bzImage" on i386.
32 This does NOT affect sparc64, you continue to use "make" to build sparc64
33 kernels.
34
352. vmlinux is not the final kernel, so RPM builders have to adjust
36 their spec files (if they delivered vmlinux for debugging).
37 System.map generated for vmlinux is still valid.
38
393. Scripts that produce a.out images have to be changed. First, if they
40 invoke make, they have to use "make image". Second, they have to pick up
41 the new kernel in arch/sparc/boot/image instead of vmlinux.
42
434. Since we are compliant with Kai's build system now, make -j is permitted.
44
45-- Pete Zaitcev
46zaitcev@yahoo.com
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 @@
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
7revamped completely for 2.4.x for several reasons. Foremost were
8performance and complexity concerns. This document details these
9new 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
12to functions and structures described here.
13
14 Probing and Detection
15
16 Each SBUS device inside the machine is described by a
17structure called "struct sbus_dev". Likewise, each SBUS bus
18found in the system is described by a "struct sbus_bus". For
19each SBUS bus, the devices underneath are hung in a tree-like
20fashion off of the bus structure.
21
22 The SBUS device structure contains enough information
23for you to implement your device probing algorithm and obtain
24the bits necessary to run your device. The most commonly
25used members of this structure, and their typical usage,
26will be detailed below.
27
28 Here is how probing is performed by an SBUS driver
29under Linux:
30
31 static void init_one_mydevice(struct sbus_dev *sdev)
32 {
33 ...
34 }
35
36 static int mydevice_match(struct sbus_dev *sdev)
37 {
38 if (some_criteria(sdev))
39 return 1;
40 return 0;
41 }
42
43 static void mydevice_probe(void)
44 {
45 struct sbus_bus *sbus;
46 struct sbus_dev *sdev;
47
48 for_each_sbus(sbus) {
49 for_each_sbusdev(sdev, sbus) {
50 if (mydevice_match(sdev))
51 init_one_mydevice(sdev);
52 }
53 }
54 }
55
56 All this does is walk through all SBUS devices in the
57system, checks each to see if it is of the type which
58your driver is written for, and if so it calls the init
59routine to attach the device and prepare to drive it.
60
61 "init_one_mydevice" might do things like allocate software
62state structures, map in I/O registers, place the hardware
63into an initialized state, etc.
64
65 Mapping and Accessing I/O Registers
66
67 Each SBUS device structure contains an array of descriptors
68which describe each register set. We abuse struct resource for that.
69They each correspond to the "reg" properties provided by the OBP firmware.
70
71 Before you can access your device's registers you must map
72them. And later if you wish to shutdown your driver (for module
73unload or similar) you must unmap them. You must treat them as
74a resource, which you allocate (map) before using and free up
75(unmap) when you are done with it.
76
77 The mapping information is stored in an opaque value
78typed as an "unsigned long". This is the type of the return value
79of the mapping interface, and the arguments to the unmapping
80interface. Let's say you want to map the first set of registers.
81Perhaps part of your driver software state structure looks like:
82
83 struct mydevice {
84 unsigned long control_regs;
85 ...
86 struct sbus_dev *sdev;
87 ...
88 };
89
90 At initialization time you then use the sbus_ioremap
91interface to map in your registers, like so:
92
93 static void init_one_mydevice(struct sbus_dev *sdev)
94 {
95 struct mydevice *mp;
96 ...
97
98 mp->control_regs = sbus_ioremap(&sdev->resource[0], 0,
99 CONTROL_REGS_SIZE, "mydevice regs");
100 if (!mp->control_regs) {
101 /* Failure, cleanup and return. */
102 }
103 }
104
105 Second argument to sbus_ioremap is an offset for
106cranky devices with broken OBP PROM. The sbus_ioremap uses only
107a start address and flags from the resource structure.
108Therefore it is possible to use the same resource to map
109several sets of registers or even to fabricate a resource
110structure if driver gets physical address from some private place.
111This practice is discouraged though. Use whatever OBP PROM
112provided to you.
113
114 And here is how you might unmap these registers later at
115driver shutdown or module unload time, using the sbus_iounmap
116interface:
117
118 static void mydevice_unmap_regs(struct mydevice *mp)
119 {
120 sbus_iounmap(mp->control_regs, CONTROL_REGS_SIZE);
121 }
122
123 Finally, to actually access your registers there are 6
124interface routines at your disposal. Accesses are byte (8 bit),
125word (16 bit), or longword (32 bit) sized. Here they are:
126
127 u8 sbus_readb(unsigned long reg) /* read byte */
128 u16 sbus_readw(unsigned long reg) /* read word */
129 u32 sbus_readl(unsigned long reg) /* read longword */
130 void sbus_writeb(u8 value, unsigned long reg) /* write byte */
131 void sbus_writew(u16 value, unsigned long reg) /* write word */
132 void sbus_writel(u32 value, unsigned long reg) /* write longword */
133
134 So, let's say your device has a control register of some sort
135at offset zero. The following might implement resetting your device:
136
137 #define CONTROL 0x00UL
138
139 #define CONTROL_RESET 0x00000001 /* Reset hardware */
140
141 static void mydevice_reset(struct mydevice *mp)
142 {
143 sbus_writel(CONTROL_RESET, mp->regs + CONTROL);
144 }
145
146 Or perhaps there is a data port register at an offset of
14716 bytes which allows you to read bytes from a fifo in the device:
148
149 #define DATA 0x10UL
150
151 static u8 mydevice_get_byte(struct mydevice *mp)
152 {
153 return sbus_readb(mp->regs + DATA);
154 }
155
156 It's pretty straightforward, and clueful readers may have
157noticed that these interfaces mimick the PCI interfaces of the
158Linux kernel. This was not by accident.
159
160 WARNING:
161
162 DO NOT try to treat these opaque register mapping
163 values as a memory mapped pointer to some structure
164 which you can dereference.
165
166 It may be memory mapped, it may not be. In fact it
167 could be a physical address, or it could be the time
168 of day xor'd with 0xdeadbeef. :-)
169
170 Whatever it is, it's an implementation detail. The
171 interface was done this way to shield the driver
172 author from such complexities.
173
174 Doing DVMA
175
176 SBUS devices can perform DMA transactions in a way similar
177to PCI but dissimilar to ISA, e.g. DMA masters supply address.
178In contrast to PCI, however, that address (a bus address) is
179translated by IOMMU before a memory access is performed and therefore
180it is virtual. Sun calls this procedure DVMA.
181
182 Linux supports two styles of using SBUS DVMA: "consistent memory"
183and "streaming DVMA". CPU view of consistent memory chunk is, well,
184consistent with a view of a device. Think of it as an uncached memory.
185Typically this way of doing DVMA is not very fast and drivers use it
186mostly for control blocks or queues. On some CPUs we cannot flush or
187invalidate individual pages or cache lines and doing explicit flushing
188over ever little byte in every control block would be wasteful.
189
190Streaming DVMA is a preferred way to transfer large amounts of data.
191This process works in the following way:
1921. a CPU stops accessing a certain part of memory,
193 flushes its caches covering that memory;
1942. a device does DVMA accesses, then posts an interrupt;
1953. CPU invalidates its caches and starts to access the memory.
196
197A single streaming DVMA operation can touch several discontiguous
198regions of a virtual bus address space. This is called a scatter-gather
199DVMA.
200
201[TBD: Why do not we neither Solaris attempt to map disjoint pages
202into a single virtual chunk with the help of IOMMU, so that non SG
203DVMA masters would do SG? It'd be very helpful for RAID.]
204
205 In order to perform a consistent DVMA a driver does something
206like the following:
207
208 char *mem; /* Address in the CPU space */
209 u32 busa; /* Address in the SBus space */
210
211 mem = (char *) sbus_alloc_consistent(sdev, MYMEMSIZE, &busa);
212
213 Then mem is used when CPU accesses this memory and u32
214is fed to the device so that it can do DVMA. This is typically
215done with an sbus_writel() into some device register.
216
217 Do not forget to free the DVMA resources once you are done:
218
219 sbus_free_consistent(sdev, MYMEMSIZE, mem, busa);
220
221 Streaming DVMA is more interesting. First you allocate some
222memory suitable for it or pin down some user pages. Then it all works
223like this:
224
225 char *mem = argumen1;
226 unsigned int size = argument2;
227 u32 busa; /* Address in the SBus space */
228
229 *mem = 1; /* CPU can access */
230 busa = sbus_map_single(sdev, mem, size);
231 if (busa == 0) .......
232
233 /* Tell the device to use busa here */
234 /* CPU cannot access the memory without sbus_dma_sync_single() */
235
236 sbus_unmap_single(sdev, busa, size);
237 if (*mem == 0) .... /* CPU can access again */
238
239 It is possible to retain mappings and ask the device to
240access data again and again without calling sbus_unmap_single.
241However, CPU caches must be invalidated with sbus_dma_sync_single
242before such access.
243
244[TBD but what about writeback caches here... do we have any?]
245
246 There is an equivalent set of functions doing the same thing
247only with several memory segments at once for devices capable of
248scatter-gather transfers. Use the Source, Luke.
249
250 Examples
251
252 drivers/net/sunhme.c
253 This is a complicated driver which illustrates many concepts
254discussed above and plus it handles both PCI and SBUS boards.
255
256 drivers/scsi/esp.c
257 Check it out for scatter-gather DVMA.
258
259 drivers/sbus/char/bpp.c
260 A non-DVMA device.
261
262 drivers/net/sunlance.c
263 Lance driver abuses consistent mappings for data transfer.
264It is a nifty trick which we do not particularly recommend...
265Just check it out and know that it's legal.
266
267 Bad examples, do NOT use
268
269 drivers/video/cgsix.c
270 This one uses result of sbus_ioremap as if it is an address.
271This does NOT work on sparc64 and therefore is broken. We will
272convert it at a later date.