Skip to content

Commit 24be2df

Browse files
smcameronsmcameron
committed
import materials
1 parent d1a42ef commit 24be2df

37 files changed

+2571
-0
lines changed

‎DMA.html

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
<html>
2+
<font face="helvetica">
3+
<title>DMA - Direct Memory Access</title>
4+
<body>
5+
<p align=center><font size=+5>DMA - Direct Memory Access</font>
6+
<hr>
7+
<a href="contents.html">Contents</a>
8+
<font size=+3>
9+
<ul>
10+
<li>Some devices can directly read or write into the computer's
11+
(or "the host's") memory.
12+
<li>Typically, the CPU will send some command down to the device,
13+
("hey disk drive, write this memory out to disk") or some external
14+
event will occurr (a network packet arrives) which will
15+
trigger the device to do DMA.
16+
<li>Memory is <em>very slow</em> compared to the CPU.
17+
<li>Consequently, there are often several levels of CPU caching.
18+
<li>DMA cannot read or write from CPU caches.
19+
<li>Consequently, care must be taken with DMA to ensure caching
20+
does not corrupt your data.
21+
<li>For DMA going <em>to</em> the device, the data must be pushed
22+
out of the cache into RAM prior to the DMA operation, and the CPU
23+
must not touch the data until the DMA is completed.
24+
<li>For DMA coming <em>from</em> the device, the CPU must invalidate
25+
any cache entries for the memory prior to accessing any of the DMA'ed
26+
data.
27+
<li>The details of how this happens differ from one architecture to
28+
another.
29+
<li>Linux provides a DMA API to hide these differences from the
30+
driver developer, and make disparate architectures look the same.
31+
</ul>
32+
<p align=right><a href="DMA2.html">Next</a>
33+
</font>
34+
</body>
35+
</html>

‎DMA2.html

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
<html>
2+
<font face="helvetica">
3+
<title>More about DMA</title>
4+
<body>
5+
<p align=center><font size=+5>More about DMA</font>
6+
<hr>
7+
<a href="contents.html">Contents</a>
8+
<font size=+3>
9+
<ul>
10+
<li>Memory allocated with <b>dma_alloc_coherent</b>
11+
(or <b>pci_alloc_consistent</b>) is not cached, and is
12+
DMA-able at any time, in either direction. (you may have to flush
13+
the processor's write buffers however (see Documentation/DMA-API.txt)
14+
<li>Memory allocated with kmalloc() must be <em>mapped</em> for DMA
15+
prior to the DMA operation, and <em>unmapped</em> afterwards.
16+
<li><b>dma_map_single(), dma_unmap_single()</b>.<br>
17+
"Mapping" a kmalloc'ed region of memory for DMA with dma_map_single
18+
(or pci_map_single) does a few things:
19+
<ul>
20+
<li>Provides you with a bus address to give the device.
21+
<li>Synchronizes the cache (for writes, flushes the cache, for
22+
reads, might discard the cache lines at this point.)
23+
<li>On some archictecturs (e.g. PowerPC) it may program PCI bridges
24+
up to do bus address/physical address translations.
25+
</ul>
26+
"Unmapping" a kmalloc'ed region of memory for DMA with dma_unmap_single
27+
(or pci_unmap_single) does a few things.
28+
<ul>
29+
<li>Synchronizes the cache (for writes, nothing here, for reads,
30+
it may discard cache entries at this point, if it wasn't done at
31+
map time.)
32+
<li>(on some architectures) discard any pci bridge
33+
address translations the mapping had set up.
34+
</ul>
35+
<li><b>dma_map_page(), dma_unmap_page()</b>. -- same as *_map_single, but
36+
a page at a time.
37+
<li><b>dma_sync_single_for_device(), dma_sync_single_for_cpu()</b>
38+
If you leave regions mapped for DMA, you can use them multiple
39+
times, and depending on your transfer direction use these to sync
40+
the cache with memory as necessary.
41+
</ul>
42+
</font>
43+
</body>
44+
</html>

‎codingstyle.html

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
<html>
2+
<font face="helvetica">
3+
<title>Coding Style</title>
4+
<body>
5+
<p align=center><font size=+5>Coding Style</font>
6+
<hr>
7+
<a href="contents.html">Contents</a>
8+
<font size=+3>
9+
<ul>
10+
<li>Why is coding style important?
11+
<ul>
12+
<li><b>Because
13+
if you do not follow the prescribed style,
14+
your patches will not be accepted.</b>
15+
</ul>
16+
<li>Read <a href="http://www.kernel.org/doc/Documentation/CodingStyle">Documentation/CodingStyle</a>
17+
<li>Run scripts/checkpatch.pl on your patches early and often and
18+
<em>always</em> prior to submitting patches to lkml.
19+
<pre>
20+
<em>do {</em>
21+
stg push
22+
<em>do {</em>
23+
stg show | ./scripts/checkpatch.pl -
24+
<em>fix whatever checkpatch finds</em>
25+
stg refresh
26+
<em>} until checkpatch doesn't find anything</em>
27+
<em>} until all your patches are pushed on. </em>
28+
</pre>
29+
<li>Don't write 1000 lines of code and <em>then</em> try to
30+
run checkpatch.pl.
31+
<li>Especially do not make a bunch of patches, and then try
32+
to run checkpatch on them all. Run checkpatch as you go. If
33+
you don't do this, then when you fix the things checkpatch
34+
finds in the early patches, later patches will break
35+
when you push them on after fixing the earlier patches.
36+
</ul>
37+
</font>
38+
</body>
39+
</html>

‎completions.html

+104
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
<html>
2+
<font face="helvetica">
3+
<title>Completions</title>
4+
<body>
5+
<p align=center><font size=+5>Completions</font>
6+
<hr>
7+
<a href="contents.html">Contents</a>
8+
<font size=+3>
9+
<li>
10+
<p>Sometimes your driver may need to wait for some
11+
event to occur. A typical scenario might be that the driver
12+
sends some command down to a device and then sleeps until
13+
that operation completes and then continue. For example,
14+
if it were a disk controller driver it might need to send
15+
down a command to write some data to a disk drive, and
16+
considering the CPU speed, this operation may take awhile.
17+
18+
<p>When the command completes on the disk drive, the interrupt
19+
handler will get called. The interrupt handler does not have
20+
the same process context as the code which initiated the command.
21+
22+
<p>The process which initiated the command is hanging around sleeping.
23+
So, how does the interrupt handler wake up the sleeping process so that
24+
it knows its requested operation has been completed and that it can
25+
continue?
26+
27+
<p>This is what completions are for.
28+
29+
<p>See include/linux/completion.h
30+
31+
<p>There are a couple of macros to declare completions,
32+
DECLARE_COMPLETION, and DECLARE_COMPLETION_ONSTACK. The
33+
latter is used when you're storing your completion on the
34+
kernel stack (e.g. in the local variable of a function.)
35+
36+
<p>There is a function, "wait_for_completion()" which will
37+
sleep until the event it is waiting for "completes".
38+
39+
<p>The completion of the event is signalled by calling another
40+
function, "complete()".
41+
42+
<p>An example (from the hpsa driver) should help clarify this
43+
44+
<hr>
45+
<pre>
46+
static inline void hpsa_scsi_do_simple_cmd_core(struct ctlr_info *h,
47+
struct CommandList *c)
48+
{
49+
DECLARE_COMPLETION_ONSTACK(wait);
50+
51+
c-&gt;waiting = &amp;wait;
52+
enqueue_cmd_and_start_io(h, c);
53+
<font color="red">wait_for_completion(&amp;wait);</font>
54+
}
55+
</pre>
56+
<hr>
57+
58+
<p>The above function declares a completion on the stack, then
59+
calls a function called enqueue_cmd_and_start_io -- which
60+
submits some commands down to a device, and then it calls
61+
wait_for_completion(). Wait for completion goes to sleep
62+
until the thing it's waiting for occurs.
63+
64+
<p>When whatever command was submitted completes on the device,
65+
the interrupt handler is called, and eventually the interrupt
66+
handler executes this code:
67+
68+
<hr>
69+
<pre>
70+
static inline void finish_cmd(struct CommandList *c, u32 raw_tag)
71+
{
72+
removeQ(c);
73+
if (likely(c-&gt;cmd_type == CMD_SCSI))
74+
complete_scsi_command(c, 0, raw_tag);
75+
else if (c-&gt;cmd_type == CMD_IOCTL_PEND)
76+
<font color="red">complete(c-&gt;waiting);</font>
77+
}
78+
</pre>
79+
<hr>
80+
<p>The call to "complete()" which happens in the interrupt
81+
handler causes the thread of execution which is sleeping inside
82+
the "wait_for_completion()" to wake up and continue.
83+
84+
<p>There are other variants of wait_for_completion:
85+
<pre>
86+
extern void wait_for_completion(struct completion *);
87+
extern int wait_for_completion_interruptible(struct completion *x);
88+
extern int wait_for_completion_killable(struct completion *x);
89+
extern unsigned long wait_for_completion_timeout(struct completion *x,
90+
unsigned long timeout);
91+
extern long wait_for_completion_interruptible_timeout(
92+
struct completion *x, unsigned long timeout);
93+
extern long wait_for_completion_killable_timeout(
94+
struct completion *x, unsigned long timeout);
95+
extern bool try_wait_for_completion(struct completion *x);
96+
extern bool completion_done(struct completion *x);
97+
98+
extern void complete(struct completion *);
99+
extern void complete_all(struct completion *);
100+
101+
</pre>
102+
</font>
103+
</body>
104+
</html>

‎contents.html

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
<html>
2+
<font face="helvetica">
3+
<title>Contents</title>
4+
<body>
5+
<p align=center><font size=+5>Intro to linux kernel programming</font>
6+
<hr>
7+
<font size=+1>
8+
<p>Contents
9+
<ul>
10+
<li><a href="p1.html">Introduction</a>
11+
<li><a href="whatisthekernel.html">What is the kernel?</a>
12+
<li><a href="getkernel.html">Getting the kernel source</a>
13+
<ul>
14+
<li>Get it from your distro
15+
<li>Get a tarball from <a href="http://kernel.org">kernel.org</a>
16+
<li>Use git to get it from <a href="http://git.kernel.org">git.kernel.org</a>
17+
</ul>
18+
<li>Building the kernel
19+
<ul>
20+
<li><a href="kernelconfig.html">Configuring the kernel</a>
21+
<li><a href="kernelcompile.html">Compiling the kernel</a>
22+
<li><a href="kernelinstall.html">Installing the kernel</a>
23+
<ul>
24+
<li>Installing modules into /lib/modules
25+
<li>Installing vmlinuz into /boot
26+
<li>making a new initial ram disk initial RAM fs
27+
<li>modifying /boot/grub/menu.lst
28+
<li><a href="makeinstall.html">Behind the scenes of "make install"</a>
29+
</ul>
30+
</ul>
31+
<li><a href="kerneltour1.html">Brief tour of the kernel</a>
32+
<ul>
33+
<li>Tools for browsing and searching the kernel source
34+
<li>Kernel entry points
35+
<ul>
36+
<li><a href="kboot1.html">Booting (or kexec'ing)</a>
37+
<li><a href="kernsyscall.html">System calls</a>
38+
<li><a href="kerninter.html">Interrupts</a>
39+
</ul>
40+
<li><a href="kerneltour2.html">View of the top level directories
41+
in the kernel source tree</a>
42+
</ul>
43+
<li><a href="makingpatches.html">Making Patches</a>
44+
<ul>
45+
<li><a href="lkprocess.html">The linux kernel development process</a>
46+
<li><a href="whatisapatch.html">What is a patch?</a>
47+
<li><a href="http://userweb.kernel.org/~akpm/stuff/tpp.txt">
48+
Andrew Morton's "The Perfect Patch"</a>
49+
<li>Tools for making, applying, and manipulating patches
50+
<ul>
51+
<li><a href="using_stgit.html">Stacked git</a>
52+
<li><a href="/using_stgit.html#patchutils">Patch utils</a>
53+
<li><a href="using_stgit.html#wiggle">wiggle</a>
54+
</ul>
55+
</ul>
56+
<li><a href="module.html">Making your own kernel module</a>
57+
<ul>
58+
<li>What is a kernel module?
59+
<li>Manipulating modules
60+
<ul>
61+
<li>Loading modules: insmod, modprobe
62+
<li>Unloading modules: rmmod
63+
<li>lsmod
64+
<li>modinfo
65+
</ul>
66+
<li><a href="module2.html">Trivial module code</a>
67+
<ul>
68+
<li>Modify Kconfig and Makefile
69+
<li>module macros
70+
<li>init and cleanup entry points
71+
<li><a href="codingstyle.html">Coding style and checkpatch.pl</a>
72+
</ul>
73+
<li>Registering a platform device
74+
<li>Registering a char device on driver load
75+
<li>Unregistering your char device on driver unload
76+
<li>File operations
77+
<ul>
78+
<li>open
79+
<li>read
80+
<li>write
81+
<li>ioctl
82+
</ul>
83+
<li>Register a class (to enable udev to create device nodes)
84+
<li>Register a class device (to enable udev to create device nodes)
85+
<li>Adding some debug code
86+
<li>spinlocks
87+
</ul>
88+
<li>Three types of memory addresses
89+
<ul>
90+
<li>Virtual -- what you use 99% of the time
91+
<li>Bus -- what you pass to devices that need to do DMA
92+
<li>Physical -- what you pass to ioremap(), kmap(), etc.
93+
</ul>
94+
<li>Memory allocation
95+
<ul>
96+
<li><a href="kmalloc.html">kmalloc</a>
97+
<li><a href="pci-alloc-consistent.html">pci_alloc_consistent</a>
98+
<li><a href="vmalloc.html">vmalloc</a>
99+
<li><a href="ioremap.html">ioremap</a>
100+
</ul>
101+
<li><a href="DMA.html">DMA -- Direct Memory Access</a>
102+
<li><a href="DMA2.html">More about DMA</a>
103+
<li><a href="interrupts.html">Interrupts</a>
104+
<li><a href="interrupts2.html">More about interrupts</a>
105+
<li><a href="interrupts3.html">Even more about interrupts</a>
106+
<li><a href="completions.html">wait_for_completion(), complete()</a>
107+
<li><a href="sleeping.html">Sleeping and delaying</a>
108+
<li><a href="debugging.html">debugging</a>
109+
<li><a href="further_reading.html">Further Reading</a>
110+
</ul>
111+
</font>
112+
</body>
113+
</html>

‎debugging.html

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
<html>
2+
<font face="helvetica">
3+
<title>Debugging</title>
4+
<body>
5+
<p align=center><font size=+5>Debugging</font>
6+
<hr>
7+
<a href="contents.html">Contents</a>
8+
<font size=+3>
9+
<ul>
10+
<li>Use printk, dev_warn(), or dev_dbg() or the like.
11+
<li>Use a null modem + serial port to capture console output: add
12+
<pre>console=ttyS0,115200</pre>
13+
line settings: 8N1, no hardware flow control
14+
15+
<li><a href="http://kerneltrap.org/node/3648">Decoding a stack trace (oops or panic):</a>
16+
<ul>
17+
<li>
18+
Check EIP
19+
<li>beware of inlining
20+
<li>(In the old days, had to use the ksymoops program to decode stack traces, nowadays, this is built into the kernel.)
21+
</ul>
22+
<li>Add special debug /proc, /sys or ioctl entry points to allow information gathering
23+
<li>magic sysrq key:
24+
<br>enable by:
25+
<pre>echo 1 &gt; /proc/sys/kernel/sysrq</pre>
26+
27+
<p>alt-sysrq-KEY performs a variety of actions, see
28+
<p>Documenatation/sysrq.txt
29+
30+
<p>Some convenient ones:
31+
<ul>
32+
<li>alt-sysrq-'s' - Will attempt to sync all mounted filesystems.
33+
(useful before you try something suspiciously dangerous which may
34+
crash the system, such as insmod'ing or rmmod'ing your new,
35+
untested driver code (or just run the 'sync' command)
36+
37+
<li>'u' - Will attempt to remount all mounted filesystems read-only.
38+
39+
<li>'t' - Will dump a list of current tasks and their information to your
40+
console.
41+
42+
<li>re'B'oot is good when you're unable to shut down. But you should also 'S'ync and 'U'mount first.
43+
</ul>
44+
45+
<li>kgdb, gdb, the "crash" program - beyond the scope of this class.
46+
</ul>
47+
48+
</font>
49+
</body>
50+
</html>

0 commit comments

Comments
 (0)