Too many users build things as modules for no reason, and dont understand why they have to then list them to be autoloaded. There are other reasons against mindlessly building things as modules too. e.g. http://distrowatch.com/weekly.php?issue=20050509#1 At the end of my installation I found that the module for my Ethernet card was not being loaded, so I had no network. I know that my card uses the via-rhine driver, and typing "modprobe via-rhine" worked, so I added "via-rhine" to file /etc/modules.autoload.d/kernel-2.6 and all was well on the next reboot.
We already have a kernel guide: http://www.gentoo.org/doc/en/gentoo-kernel.xml It's a guide to choosing kernels but could easily be expanded. The Installaiton Handbook does cover the configuration of a kernel already though. The section "manual configuration" does touch on this issue somewhat. It has a good mini-kernel config howto that covers most of the bases. http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&chap=7 Would you like a more in-depth "HOWTO compile a kernel" section in the kernel-guide and link to it from the Installation Handbook? Or would it be better to include this info directly in the Handbook integrated with the already included mini-kernel conf howto? Or would it be better to create a new guide independant of the existing kernel-guide and Installation Handbook? Either way, what sort of information are you looking to be included in this guide that isn't already in the mini-kernel howto in the Installation Handbook? If you give me a basic list of topics you want covered and where this info should be included (kernel-guide, installation handbook, new guide) I will start writing.
I think it deserves its own document in itself. Topic ideas: Gentoo Requirements Modules vs built-in How to use lspci to identify your hardware (with examples) Importance of selecting correct IDE driver Importance of selecting correct USB HCD NLS/Charset VFAT stuff USB mass storage support
*** Bug 97290 has been marked as a duplicate of this bug. ***
I have a first draft that needs to be proofread. dsd, can you look it over for technical accuracy and make sure it covers everything you wanted? smithj, will you proofread it for me like last time? HTML preview is: http://dev.gentoo.org/~curtis119/kernel-configuration.html XML source is: http://dev.gentoo.org/~curtis119/kernel-configuration.xml
Thanks for writing it, here are my comments: 1. I don't agree with the modular vs monolithic argument. One *very* common problem is that users build things as modules with no good reason. They then wonder why certain pieces of hardware aren't working and they don't understand - they built the module, why hasn't it been loaded? So, the users might do some reading and find out about modules.autoload.d and use that (but then, why not just build it into the kernel). They might find coldplug, which isn't always very nice since it sometimes loads things in undesirable orders. They are now *depending* on coldplug and the module loading tools. If any one of these breaks or has a behaviour change, the user is unable to understand the problem, and may well end up reinstalling the entire distro..! Infact one of the main reasons for this document is that I want to clear up the misconception where new users think building things as modules is a good idea. Most of them have no reason to do so and would find it easier if they had put things built in. For example: > It reduces the size of the kernel by including only the things that are required to get the system up and running. ...but if you consider the file on disk, and the kernel footprint size after the module has been loaded, the difference is negligable (although slightly higher with modules). > Modules can then be dynamically loaded as needed. This saves memory and speeds up the boot process by skipping unnecessary probing of devices. ...but if you are automatically loading on bootup, then you still go through the same probing routines, leaving a negligable difference. > Some drivers such as IDE controllers, root filesystem drivers and others must be built directly into the kernel or your system will fail to boot. This is an added complication which is avoided if users build everything into the kernel consistently. > The 2.6.x series of kernels can load modules and create device nodes for you on the fly by using hotplug and udev/devfs in conjunction with the kernels module autoloader so manual loading is not necessary in most cases. The kernel module autoloader only works when the device node already exists, which isn't the case with udev, and is not usually the case with devfs. > If a device driver is causing the kernel to oops (have an unrecoverable error), it is difficult to diagnose which driver is causing the problem in a monolithic kernel. This is not true > The Gentoo init scripts are set up to work with Modular or Monolithic kernels. I don't know of any of the default init scripts that deal with module loading, other than ALSA. Of course, there are some reasons to use modules. Perhaps this could be described further nearer the end. 2. You talk about setting the symbolic link, emerging sources, how to open the configuration system, etc. This sort of thing is already covered elsewhere. I was envisioning this guide as more of a strict "how to know which options to select" guide. But I guess if you guys don't mind duplicating the data then it could stay. 3. Related to #2, as I don't think it quite fits here and is covered elsewhere, but "make oldconfig" gives users a lot of trouble. Too much changes between kernel releases for this to be a reliable upgrade path. It is only ok for revision releases (e.g. 2.6.12-r1 to 2.6.12-r4). 4. "If an option has ---" I don't think this would make much sense to a new user, as you haven't introduced them to the method of Y/N/M, nor have you mentioned where this "---" will exist. 5. "Kernel Userspace Events is used by many applications such as FAM or Gamin" This is not true 6. "Automatic kernel module loading allows the kernel to load modules as needed without user intervention." This is not true - you need a userspace agent for things like that to happen. More importantly, you didn't mention that this is an absolute must-enable - udev does not work without it. 7. We need to talk about SATA disks too. 8. "UDEV requires /proc and virtual memory file systems" I don't think this is true I also have a few ideas for wording and ordering improvements but I will give that more thought for now.
Created attachment 63479 [details, diff] kernel-configuration.xml.diff curtis119: also note that you will need to change this when 2.6.13 goes stable. 13 will provide another option for latency scheduling called "voluntary preemption". just a heads-up. also, gentoo-sources 2.6.12-r4 is stable now i didn't change any of the things mentioned above... just the grammer and such. the patch is against the most recent version on toucan
Created attachment 64395 [details] kernel-configuration.xml This is the latest version. I have a list of updates that *could* be applied but the document seems to be fine in this current state. If DSD and swift can look at it and OK it for inclusion, thanks. I won't have time to work on this anymore so if this version isn't good enough it will have to be picked up by someone else. online: http://curtis119.no-ip.org/doc/en/kernel-configuration.xml
I found someone to work on this, xemoka. He has already started on the list of things I had to do. He's set up his doc editing environment and gorg and has the changes he has already made up for viewing: http://xemoka.net:8008/doc/en/kernel-configuration.xml Thanks xemoka!
Created attachment 64592 [details] Kernel Configuration Guide The "finished" Kernel Configuration Guide. Hopefully it is low on the error list. Available as a live page at http://xemoka.net:8008/doc/en/kernel-configuration.xml
>If you build all drivers into the kernel it is called a Monolithic kernel. A >Monolithic kernel is recommended and will be used during our example configuration > below. maybe a quick explanation of why monolithic is preferred and/or a small pros/cons list?
(In reply to comment #10) > maybe a quick explanation of why monolithic is preferred and/or a small > pros/cons list? That was in the first draft. I removed it on request from the kernel team because this guide is aimed specifically towards those who have never compiled a kernel before and we want this to be as simple as possible (it's already complicated enough). Modules not loading is one of the biggest errors the kernel team sees with people who aren't sure what they are doing. This guide is supposed to bring down the number of errors so monolithic makes more sense. ------------------- Docsteam, is there anything more that needs to be done to this before it can go live? Can we have it proofread and commited to CVS?
(In reply to comment #11) > Docsteam, is there anything more that needs to be done to this before it can go > live? Can we have it proofread and commited to CVS? If dsd and/or the kernel team are fine with the guide in its current state, I guess one of us could get this one in. Curtis, could you also obsolete all but the latest in the attachments to this bug? thanks.
(In reply to comment #12) > Curtis, could you also obsolete all but the latest in the attachments to this > bug? thanks. Nevermind. I now see them as obsolete. Duh.
Very sorry for the long delay in getting around to looking at this. Justin, I can't get to the URL. Any chance you could attach the current work as HTML here? Thanks a lot for working on this :)
Sorry about that, that machine has gone up and down a couple times since this, that server address is now running again, give it another shot...
Created attachment 67950 [details] kernel-configuration.xml Taken file from not stable remote location and attached to bug, for your viewing pleasure...
Created attachment 67990 [details] HTML Formated (In reply to comment #16) > Created an attachment (id=67950) [edit] > kernel-configuration.xml > > Taken file from not stable remote location and attached to bug, for your > viewing pleasure... I'm not quite sure what the difference there was between the file that you attached, and the file that was already there called "Kernel Configuration Guide" that I had attached... in fact, I dont think there is ANY difference. Diff yeilds no difference either. I've attached the HTML format of this, as asked preiviously...
Sorry to stick a foot in and suggest a direction change again, but after giving this some more thought, I have changed my mind slightly. I'm worried that theres a bit of an information overload, the way that lots of kernel options are explained makes the document a headache to go over. While "inspiring confidence" in the reader by explaining stuff in a fair amount of detail is good, I think I'd prefer this to be more of a document which only addresses common problems so is quick to read and put into action for the users. So, here's what I propose, plus some general feedback on the doc so far. If you disagree with any of this, say so, and we can discuss it further :) 1. Introduction should be refined - it should briefly explain very near the start that it's _easier_ for the users to use genkernel (and link to genkernel docs) because its automatic, then briefly explain why some users might choose to compile it manually instead (fine control over what goes into your kernel, slim kernel image, less compilation time, builds up an understanding of the kernel structure and build system, etc...) 2. Also in introduction, don't say that this guide is suitable for "almost any architecture". I think that the process for a lot of archs (ARM, MIPS, SPARC, ...) is quite different (or has more caveats anyway). Instead say that its suitable for the common system architectures. 3. Sections 4/5 (Install Sources/Configuration Methods) should go. It's duplicated from other documentation and goes outside the scope of this one (which I envision as purely general advice on how to _configure_ the kernel). Feel free to add a note (maybe in introduction) saying something like: this doc assumes that you already have installed kernel source and know how to get into a configuration interface, e.g. menuconfig 4. Instead of going over all of the core sections of the configuration (another worry of mine is that this is growing with time), just go over the ones where default values probably need to be changed. Instead we should add a note saying that it's important not to disable options that are on by default if the user isn't sure what they do. For example, we don't need to mention "Code maturity level options --->" since the average user isn't going to want to change the default settings there. 5. Rather than structuring the documentation by section (i.e. right now we have a section for "Processor type and features --->", a bloated section for "Device Drivers", etc), structure it by the issues we are trying to address. For example, one section would be "Selecting the right processor settings", which would describe how to select the processor type and whether to select SMP. Other things such as preemption and MTRR can be ignored since the defaults will work for most people. Other sections would be "Configuring USB Host Controllers", "Enabling USB Mass Storage support", "Selecting the right IDE/SATA chipset", etc. 6. Section 7 should go too. 7. If we take my suggestions we should clarify the purpose of the document near the start. We need to briefly describe the general strategy of going through each menu, matching options to your system and hardware setup, then we can explain that this doc tries to detail the common mistakes/omissions that people make. I have some ideas for small rewording changes to improve the document flow, but I'll leave them until later as I expect the above changes will reduce the document content size (which is good!). In the mean time, if you see any changes you'd like to make, feel free :) Thanks.
One thing to keep in mind for this are the modules that can't be built in, that really need to be left as modules for things to work properly. I believe there is one for the iPod (not sure if the scsi thing has to be a module for an iPod to load properly, but that's what I've seen) and one for realtime-lsm (I know this requires one of the kernel options to be a module). From there, I'm also quite curious to see what is said about what things can be built in since a lot of tutorials recommend things as modules when they don't need to be modules. Another thing from the html formated doc, could you leave a margin on the left side? It buts right up to the side and that is quite annoying for reading.
IMHO, best way to do this should be a database (even a little sqlite one) with all the hardware (lspci lines) and corresponding modules needed. The reason for a similar thing is the possibility to expand to automate hardware setup (one user finds a way to setup, fill a module with the passages he did, and other users can save their time for debbugging or anything else, it could work a bit like portage, but with feedback)
If you want automation then you should use genkernel. A hardware database has some impracticalities and is outside of the scope of a simple document introducing kernel configuration. It also does not cover many topics already discussed on this bug.
Created attachment 75828 [details] slimmed down guide (In reply to comment #18) I slimmed this down quite a bit (by about half) by following your suggestions to make it more of a general guide. I cut down the last section instead of getting rid of it completly, is that OK or would you rather see it disappear completly? Have a look, is this closer to what you envisioned? xml attached. html version available: http://dev.gentoo.org/~curtis119/kernel-configuration.html
Fixing OS field.
(In reply to comment #22) Looks like a good guide so far. However, I do think this: (/dev file system will be removed from the 2.6.13 kernel. Only enable this option if your system does not support udev) should be changed to something more like (The /dev filesystem has been removed from kernels >=2.6.13. If your system does not support udev, you must use a kernel prior to 2.6.13) And, possibly include a brief link to the relevant parts of arch-specific docs for arches that do *not* support udev. Though that might border on cluttering up the doc, it does also does seem useful. :)
Curtis, Thanks. That is looking a lot better. A few comments: - Some of the items I wrote about in comment #18 still need to be addressed, ideally. (If you need me to be any more specific, just ask) - I don't agree with these statements: "[It will slow down your kernel] or even make it impossible for your kernel to run at all" I've never heard of a SMP kernel not booting on a UP machine. (plus I think our LiveCD's boot into SMP kernels by default?) "If you fail to enable the driver for your IDE chipset filesystem corruption and destruction of your hard drive can result." Never heard of that being the case - I'd like to reiterate that this document should be strongly focused towards common problems that users get. While you have covered most of it, I think it could be phrased clearer. For example, you state that it is a good idea to enable the right IDE chipset so that you get DMA. But we don't really say why (except for that corruption/destructrion comment as above). I think it would be better to focus on the fact that if the user does not enable support for their chipset, their disk transfers will be incredibly unbearably slow, and the whole system will majorly decrease in responsiveness which disk I/O is taking place (mouse might jump around the screen, etc). Similar thing for USB HCD's. If the user doesn't enable the right HCD drivers, they are likely to find that none of their USB devices respond in any way, shape, or form, when attached. Picture the situation on the forums where the user says "When I plug in my usb devices, nothing happens. Not even the light on my mouse comes on". If we could then link them to this doc, they would ideally like to see (in this order): - a brief explanation of HCD's - the fact that HCD types present in any particular system will vary - the fact that if you don't select the right ones, you may very well end up with no USB capabilities on your system - how to find out which HCD types you have - where the kernel options are - Section 5 should go - in response to comment #24 As devfs is gone in the current stable kernels I do not feel that we should mention it. Perhaps we should mention towards the top that the guide is geared at recent kernels on common architectures, and may not be accurate for historical artifacts running on doorstops :) Thanks, and if you feel I'm talking nonsense, please slap me around a bit :)
About time we got this guide up and running...
I've added dsd's suggestions to the slimmed down version of the guide. Here's the HTML version of it: http://dev.gentoo.org/~rane/kernel-config.html Could you read it and post more suggestions about the changes that should be made to the guide? (we ignore the language for now, i can see some mistakes but i don't want to go into mess of fixing typos before we agree on the content)
Created attachment 91139 [details] kernel-config.xml with rane's touch ups
Created attachment 91140 [details, diff] diff between slimmed down and rane's versions
I am working on this at http://dev.gentoo.org/~dsd/misc/kernel-config.xml It is mostly rewritten. Any comments on existing content appreciated, I'm fairly happy with what is there - I am mostly adding stuff to the bottom. I'm not looking for feedback that some content is missing - it isn't complete yet, those comments can come later :)
(In reply to comment #30) > I am working on this at http://dev.gentoo.org/~dsd/misc/kernel-config.xml > It is mostly rewritten. > > Any comments on existing content appreciated, I'm fairly happy with what is > there - I am mostly adding stuff to the bottom. I'd suggest changing the blue text in the <pre> sections to be proper red <comment>(comments)</comment> according to GuideXML. Also, "HCD's present" --> "HCDs present". Just cosmetic stuff that we can fix at commit time, basically. I like where you're going with this, Daniel; keep it up. :)
Created attachment 91915 [details] New guide Here's the new version. Also online at http://dev.gentoo.org/~dsd/misc/kernel-config.xml I think it's finished. Any comments?
I'll take care of it.
Our child is in CVS, thanks for the guide to all who participated. :-)
(In reply to comment #34) > Our child is in CVS, thanks for the guide to all who participated. :-) > Excellent, I'm glad to see this finally happend. Thanks dsd.
