1 00:00:00,005 --> 00:00:03,000 - [Instructor] Of course, we all like to do web searches 2 00:00:03,000 --> 00:00:04,008 to find the answers to our question, 3 00:00:04,008 --> 00:00:07,003 to find out information about things. 4 00:00:07,003 --> 00:00:10,005 But I'm going to urge you to do more than that 5 00:00:10,005 --> 00:00:14,009 to use information in your kernel source tree. 6 00:00:14,009 --> 00:00:20,006 So first of all, the kernel source code is changing quickly. 7 00:00:20,006 --> 00:00:24,006 Thousands of lines per day are changing on average. 8 00:00:24,006 --> 00:00:28,005 It's amazing how active the Linux kernel project is. 9 00:00:28,005 --> 00:00:30,005 So that means anything you find on the web 10 00:00:30,005 --> 00:00:32,002 might be out of date. 11 00:00:32,002 --> 00:00:35,004 Although of course a lot of it's still relevant. 12 00:00:35,004 --> 00:00:39,001 The source code for the kernel you're running 13 00:00:39,001 --> 00:00:42,007 in some sense is the official documentation, right? 14 00:00:42,007 --> 00:00:46,000 It will tell you exactly how that kernel works. 15 00:00:46,000 --> 00:00:49,001 And that's one of the real benefits of open source. 16 00:00:49,001 --> 00:00:53,001 You have the source code to go look at to figure out 17 00:00:53,001 --> 00:00:55,005 how something really works. 18 00:00:55,005 --> 00:00:59,007 Also, I find really valuable the documentation files 19 00:00:59,007 --> 00:01:01,000 that come in the source tree. 20 00:01:01,000 --> 00:01:02,006 So not only looking at the source code, 21 00:01:02,006 --> 00:01:05,003 which of course can be really hard to figure out, 22 00:01:05,003 --> 00:01:06,006 there's a lot of documentation. 23 00:01:06,006 --> 00:01:10,007 Some of it's very well written, and it's authoritative. 24 00:01:10,007 --> 00:01:16,002 So there is a subdirectory with the nice name documentation, 25 00:01:16,002 --> 00:01:17,005 and a lot of that is written 26 00:01:17,005 --> 00:01:21,009 by whomever wrote the corresponding code. 27 00:01:21,009 --> 00:01:23,008 So it's very authoritative, 28 00:01:23,008 --> 00:01:26,001 and there's some nice lengthy documents there, 29 00:01:26,001 --> 00:01:31,002 manuals in effect that can be really nice to read. 30 00:01:31,002 --> 00:01:33,005 Something I do oftentimes when I'm trying 31 00:01:33,005 --> 00:01:37,000 to learn more is I do a recursive grep 32 00:01:37,000 --> 00:01:41,004 in the documentation like grep -rl semaphore 33 00:01:41,004 --> 00:01:45,001 or something to find all the documents that say semaphore. 34 00:01:45,001 --> 00:01:48,004 And then I can go read those. 35 00:01:48,004 --> 00:01:51,000 So there's lots of documentation files. 36 00:01:51,000 --> 00:01:55,007 One I look at once in a while is called devices.txt. 37 00:01:55,007 --> 00:01:58,003 You can go look for that in your source tree, 38 00:01:58,003 --> 00:02:02,005 and it documents device files. 39 00:02:02,005 --> 00:02:04,005 For example, the character device file 40 00:02:04,005 --> 00:02:09,008 with major number one has a bunch of minors, 41 00:02:09,008 --> 00:02:12,007 dev/null, the well-known one, 42 00:02:12,007 --> 00:02:15,002 is a character device file 43 00:02:15,002 --> 00:02:18,004 with major number one and minor number three for example. 44 00:02:18,004 --> 00:02:21,007 So you can see which ones are related 45 00:02:21,007 --> 00:02:23,000 and where they come from. 46 00:02:23,000 --> 00:02:27,001 And that's kind of handy for classic device files, 47 00:02:27,001 --> 00:02:29,009 but there's way more documentation 48 00:02:29,009 --> 00:02:33,006 for other things of course. 49 00:02:33,006 --> 00:02:38,000 So something I like to do is I look at the manuals, 50 00:02:38,000 --> 00:02:41,001 I like to read the manual, RTFM. 51 00:02:41,001 --> 00:02:44,001 So there might be some that don't build, 52 00:02:44,001 --> 00:02:45,008 maybe they're not quite up to date, 53 00:02:45,008 --> 00:02:48,004 but generally a lot of good stuff. 54 00:02:48,004 --> 00:02:51,009 And you can make a PDF or you can make an HTML, 55 00:02:51,009 --> 00:02:54,009 and you're making it for the version 56 00:02:54,009 --> 00:02:57,007 that best fits your kernel 57 00:02:57,007 --> 00:03:01,005 and it uses a tool called SPHINX. 58 00:03:01,005 --> 00:03:04,000 And so that shows up some places 59 00:03:04,000 --> 00:03:05,007 and there's a few things you need to install, 60 00:03:05,007 --> 00:03:06,008 but it's really pretty good. 61 00:03:06,008 --> 00:03:08,007 If you try to do a make PDF docs, 62 00:03:08,007 --> 00:03:10,009 it typically will check 63 00:03:10,009 --> 00:03:13,001 to make sure you have what you need installed, 64 00:03:13,001 --> 00:03:15,002 and if not, it'll tell you and then you install it 65 00:03:15,002 --> 00:03:16,006 and you do that a few times, 66 00:03:16,006 --> 00:03:17,007 then you have everything installed 67 00:03:17,007 --> 00:03:19,001 and it works. 68 00:03:19,001 --> 00:03:25,008 If you do a make and you set the make variable SPHINXDRS 69 00:03:25,008 --> 00:03:27,002 to a list of directories, 70 00:03:27,002 --> 00:03:28,006 here I just have scheduler, 71 00:03:28,006 --> 00:03:30,002 but I could have scheduler space 72 00:03:30,002 --> 00:03:32,007 in some other subdirectory. 73 00:03:32,007 --> 00:03:35,002 And then a target like PDF docs, 74 00:03:35,002 --> 00:03:39,009 it'll make a PDF for the files in that directory. 75 00:03:39,009 --> 00:03:42,000 Schedules a pretty good one. 76 00:03:42,000 --> 00:03:44,007 You can do similar SPHINXDIR stuff, 77 00:03:44,007 --> 00:03:50,002 but you can make HTML docs if you prefer HTML to PDF. 78 00:03:50,002 --> 00:03:52,008 One of the harder things to understand 79 00:03:52,008 --> 00:03:55,009 about what goes on in the kernel is synchronization, 80 00:03:55,009 --> 00:03:58,001 the kind of locking in the kernel. 81 00:03:58,001 --> 00:03:59,006 If you're interested in that, 82 00:03:59,006 --> 00:04:02,009 maybe you want to make the locking PDF. 83 00:04:02,009 --> 00:04:04,005 So you're doing these make commands 84 00:04:04,005 --> 00:04:06,002 from the top level directory, 85 00:04:06,002 --> 00:04:07,007 not the documentations directory, 86 00:04:07,007 --> 00:04:09,002 top level directory. 87 00:04:09,002 --> 00:04:14,004 So you could say make SPHINXDIRS="Locking" pdfdocs. 88 00:04:14,004 --> 00:04:17,001 And then that runs pretty fast. 89 00:04:17,001 --> 00:04:18,006 And then the output should be 90 00:04:18,006 --> 00:04:22,003 in documentation/output/locking/pdf. 91 00:04:22,003 --> 00:04:25,003 And you should see locking.pdf in there. 92 00:04:25,003 --> 00:04:29,000 Oh, let's give that a try. You give that a try.