Date: Tue, 16 Jan 2007 15:47:43 -0700 From: "Steve Franks" <stevefranks@ieee.org> To: "Giorgos Keramidas" <keramida@ceid.upatras.gr> Cc: freebsd-questions@freebsd.org Subject: Re: Contributing to FreeBSD documentation (was: Re: no ath0 on new system with good card) Message-ID: <539c60b90701161447u36fc78a5jd1e40f265ea884a6@mail.gmail.com> In-Reply-To: <20070107162537.GB2261@kobe.laptop> References: <539c60b90701060908o460d1d98wab2f2514a3a9d1e2@mail.gmail.com> <20070106202147.GB2532@kobe.laptop> <539c60b90701061849u35ddc61ch16a49484bd3baf12@mail.gmail.com> <20070107031750.GA5828@kobe.laptop> <539c60b90701070754r33ba9ae8q6b22f96be0ab6ea0@mail.gmail.com> <20070107162537.GB2261@kobe.laptop>
next in thread | previous in thread | raw e-mail | index | archive | help
On 1/7/07, Giorgos Keramidas <keramida@ceid.upatras.gr> wrote: > > On 2007-01-07 08:54, Steve Franks <stevefranks@ieee.org> wrote: > > Apologies on not hitting the list. Alyays forget to reply-all. > > No problem. I just didn't copy the list because I wasn't sure I should. > > > So, I figured I'd try to fix the safe-mode end of things on my own, > > and I found a post several years old (looked like it even could have > > been yours) about safemode, which doesn't show up anywhere on the > > freebsd site. So I did what it said and grep'd boot/beastie.4th for > > safemode, which came up with this suprisingly total solution: > > > > add apic.0.disabled="1" to boot/device.hints. Not only does my system > > come up in regular boot mode, but, as you suspected, the pccard works > > too, so all appears well. > > Excellent news! Thanks for sharing the answer :) > > > So my final question, what in all the land is an "apic", > > "Advanced Programmable Interrupt Controller". This is the part of your > system which assigns priorities to interrupt lines of a device. The > full details are probably too technical for some percentage of our user > base, but more details can be found at the following pages: > > http://en.wikipedia.org/wiki/Advanced_Programmable_Interrupt_Controller > http://en.wikipedia.org/wiki/Programmable_Interrupt_Controller > http://en.wikipedia.org/wiki/Intel_8259 > http://en.wikipedia.org/wiki/Intel_APIC_Architecture > > > and why isn't apic or safemode mentioned in the handbook, manpages, or > > even on the freebsd site? > > IIRC it is mentioned in the Developer's Handbook, but you are right that > it should be in the main Handbook too. > > > Further, I'd like to write a handbook page on "freebsd and laptops", > > because we're on my third one here now, and I'm starting to get the > > drift of what could usefully be added to the handbook, namely a > > thourough discussion of booting and device.hints. > > That would be great! If you can help writing such a section for the > Handbook, a lot of users will be highly indebted to you, for sure :) > > > I presume someone 'peer-reviews' handbook submissions for correctness > > and format? I recall reading somewhere about contributing, but I get > > the impression you are involved enough to tell me whether it's a bad > > idea or not. > > Yes, you are right. We have peer reviews. A lot of the documentation > changes are filtered through the freebsd-doc mailing list, where > documentation people hang out. Patches are mailed back and forth; > edited; fixed for technical accuracy, syntax and grammar correctness; > adapted to our writing style; expanded as necessary; and eventually > committed to our documentation source code. > > You can definitely contribute as much as you feel, whenever you feel you > have the time, and in any way you consider appropriate. We have a short > article which describes how you can contribute to the FreeBSD Project, > in general: > > http://www.freebsd.org/doc/en_US.ISO8859-1/articles/contributing/ > > Most of it applies directly to documentation too. Please skim through > this article; it should be a good start. > > About your last question now... > > Yes, it's a good idea. Not just a good idea, though. It's an > *excellent* idea. > > One of the "chicken and egg" problems documentation writing usually has > to face is that: > > * New users don't know enough about the system, so they frequently > pose good questions. These questions would result in higher quality > documentation if properly channeled through experienced > documentation writers, but you have to convince the new users that > they can actually *help* by not knowing it all. > > * Once new users step over the thin line between being newcomers to > the system and being experienced in some area, we have lost all the > "insight" they can provide about how a new user thinks. > > As a result, it's easier to write documentation if we are targetting a > very experienced, very technical audience. But, IMHO, the contributions > of new users -- in the form of "interesting" questions" -- are at least > as valuable, if not more :) > > Regards, > Giorgos > > So, this is what I have so for. It was a bit late at night, so I appologise if my tone is a bit silly at times...where do we go from here? Steve So, you've burned the latest FreeBSD .iso file, pop it in your drive, anticipation rising, and *freeze*!! Hopes & Dreams go tricking away...what next? Well, the first thing is to realize that alot of people have worked very hard in their spare time to get things to the point where they are. Unfortunately, new hardware is always one step ahead. All FreeBSD drivers are written by the users - not the paid engineers of the hardware companies, so some delay at times is inevitable - there are many exceptions, however! Just compare the sata & raid support in FreeBSD to that in Windows XP. But back to moving forward: one of those new or imcompatible pieces of hardware (in most cases) has just frozen up your fresh install - what to do? First, restart the computer, and choose "3 - safe mode" from the "FreeBSD" logo boot-menu. If your computer still will not reach the installation screen, you can still send email to questions@freebsd.org. In most cases you are now at the install screen. Proceed to install FreeBSD as per the instructions in the handbook. Remove the cdrom, reboot, and again choose safe mode to avoid a freeze Now you have some sleuthing to do. First, you may look at the safe-mode section of boot/beastie.4th. You'll see it does very few opertations. These have far-reaching implicatoins however (insert explanation of how safemode disables serial ports and other nasty drivers, because I have no idea - appears to me it only disables apic, acpi, and dma). To make your system boot normally, you have to determine the source of the freeze, and disable the offending driver. First, if you have read the acpi section of the handbook, you may suspect acpi. It is frequently not the culprit, as the handbook would have you believe, but may be a safe starting point in any event. A word of caution at this point: You want to disable the minumum number of drivers to yield a usable system, and leave as much hardware in a funtional point as possible. As any good scientist will tell you, though it may become tedious quite quickly, only change one item at a time - this is the only way to avoid ambiguity about what is your real solution. The primary (and non-destructive) method of disabling drivers in FreeBSD is to edit /boot/device.hints To disable an item, add a line, <device>.0.disabled="1" i.e. acpi.0.disabled="1" Don't forget the "."! Many other FreeBSD configuration files (i.e. rc.conf) use a "<device>0" nomenclature, and once you become used to it, you may forget the dot. Things to try disabling: first, any hardware you know you don't have: such as usb(ohci, ehci) on older systems, floppies and ports on newer systems, pcmcia on desktops, etc. sio.0 and sio.1 are the first two serial ports ppc.0 is the paralell port apic.0, the advanced programmable interrupt controller acpi.0, etc. Things *not* to disable in any event: sc.0: this is the system console, otherwise known as the main user interface. Disabling this will force you to do a picky login, without the help of man pages to remember syntax, and it may be easier to simply reinstall on a fresh system! vga.0? psm.0? You may also want to try physically removing hardware, one piece at a time, to see if this yields a working system. Things to try are: anything usb pcmcia and flash cards network cards special funtion boards, such as video capture or data acquisition/engineering boards extra harddisks & cdroms etc. -- Steve Franks, KE7BTE Staff Engineer La Palma Devices, LLC http://www.lapalmadevices.com (520) 312-0089
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?539c60b90701161447u36fc78a5jd1e40f265ea884a6>