ONLamp.com    
 Published on ONLamp.com (http://www.onlamp.com/)
 See this if you're having trouble printing code examples


Big Scary Daemons

Laptops, PC Cards, and FreeBSD

11/02/2000

FreeBSD on laptops has had a checkered history. For a long time, unique laptop hardware had minimal support. Eventually, various Japanese users began the FreeBSD-PAO project to support this hardware. The main FreeBSD tree finally absorbed most of PAO just before 4.0-RELEASE. Now, various people are working on a complete rewrite of the laptop system to accommodate CardBus. FreeBSD on a laptop is quite comfortable to work in; my main system has been a laptop for the last two years, and I've never regretted it.

Laptops are tricky pieces of hardware. Laptop vendors delight in making their systems proprietary, or revamping components to save a few critical ounces, or reducing battery power to extend life. Much of this trickery is undocumented. This makes hardware support marginal. And Unix was never designed for hot-swappable hardware. As you might guess, vendor support is nonexistent.

When you're considering purchasing a laptop, your biggest concern should be hardware. FreeBSD doesn't support all of the hardware on some of the latest and greatest laptops, and won't until a developer gets his hands on both the hardware and the documentation for it. This usually happens fairly quickly -- many developers want high-end laptops, after all -- but you probably don't want to wait for that support to trickle down to you.

The three big problems in laptop hardware are generally the video card, sound card, and any built-in modem.

Many integrated modems are actually software modems (i.e., Winmodems) and won't work under FreeBSD at all. You can use a PC Card modem, however, so this isn't that critical.

Video and sound cards are more problematic. FreeBSD can use any video card in text mode, but you probably want XFree86 of some version or another. Check the manufacturer documentation to see what sort of video card the laptop has, and then check the XFree86 supported cards list. Similarly, check the freebsd-mobile archives or pcm(4) to see if the sound card is supported.

The first place to check for the latest information on particular laptop models is the freebsd-mobile mailing list archive. People frequently report their successes with particular models or ask if anyone else has that laptop. If the archives contain nothing, a friendly query to freebsd-mobile usually gets at least one or two answers. You could also check David Kulp's FreeBSD Laptop Compatibility Page.

Once you get a laptop, you'll need to configure FreeBSD properly. Your kernel must include device card and device pcic to use PC cards. You probably also want device apm, to handle power management. The exact syntax of these lines varies depending on the version of FreeBSD you're using; check GENERIC for the proper form. (If you're running -current, you'll want to look at /boot/device.hints as well.)

If you don't intend to hot-swap your hardware, and you're running older versions of FreeBSD, you can compile some drivers statically into the kernel. For example, in FreeBSD 3-stable, the 3com Etherlink III works under both the zp and ep drivers. If you never intend to remove the card and will settle for lousy performance, you can use the zp driver and skip the rest of this article. To use more sophisticated hardware, newer hardware, newer FreeBSDs, or to change hardware in midstream, however, you need to use pccardd.

The pccardd daemon watches for card insertion and removal events. Enable pccardd in /etc/rc.conf, or start in on the command line as such:

pccardd -f /etc/defaults/pccard.conf

When you insert a card, you'll see console messages like:

Sep 7 09:44:54 turtledawn pccardd[57]: Card "3Com Corporation"("3C589D") [TP/BNC LAN Card Ver. 2a] [000002] matched "3Com Corporation" ("3C589") [(null)] [(null)]

This first message indicates that pccardd has found your hardware and has matched it to an entry in its configuration file. Then, pccardd hands this information off to the kernel.

Sep 7 09:44:59 turtledawn /boot/kernel/kernel.ko: ep0: <3Com Etherlink III 3C589> at port 0x240-0x24f irq 3 slot 0 on pccard0

The kernel now realizes that it has a new interface, and brings it up.

Sep 7 09:44:59 turtledawn pccardd[57]: ep0: 3Com Corporation (3C589) inserted.

Finally, pccardd reports that it's finished. For now.

The daemon issues warnings if something goes wrong. For example, my modem card doesn't work properly out-of-the-box:

Sep 8 07:33:21 turtledawn pccardd[59]: Card "Toshiba America"("3CXM056-BNW") [3COM/NoteWorthy 56K Modem] [(null)] matched "Toshiba America" ("3CXM056-BNW") [(null)] [(null)] Sep 8 07:33:26 turtledawn pccardd[59]: driver allocation failed for Toshiba America(3CXM056-BNW): Device not configured

It identifies the card correctly, but cannot allocate resources for it. This is not uncommon; we'll look at how to solve this later.

If you want FreeBSD to auto-configure your Ethernet pccard when it's inserted, use something like this in /etc/rc.conf:

pccard_ifconfig="DHCP"

or perhaps

pccard_ifconfig="inet 192.168.1.200 netmask 255.255.255.0"

Ejecting a card is fairly straightforward. If you're fairly lucky, pccardd will handle everything for you when you eject the card. If you have problems, disable the card in software before ejecting. If it's a network card, do an ifconfig down and an ifconfig delete. If it's a storage device or SCSI card, unmount any filesystems on the card. This will keep FreeBSD from attempting to access any resources on the card when you hit the little black button.

The system might panic if you don't disable a card before ejecting it. If you eject a network card that is in promiscuous mode, the kernel will almost certainly panic. Consider yourself warned.

If pccardd doesn't get your card running properly, it's time to troubleshoot. Start with the /etc/defaults/pccard.conf file. This file contains the configuration information for pccardd and general configuration information on the system resources available on your laptop.

Unlike most of the other default files, /etc/defaults/pccard.conf probably needs some changes. If nothing else, your IRQs probably need editing. Most of the card configurations are correct, however. When you find something in /etc/defaults/pccard.conf that doesn't meet your needs, you can make an entry in /etc/pccard.conf. Those entries will override the default file.

The pccard.conf file starts off with a list of available resources.

io      available I/O ports
irq     available IRQs
memory  available memory spaces and sizes

If you need to, you can specify multiple lines for each of these. The irq line accepts a list of space-separated values.

These are the most likely to require changes, especially the irq line. Grep /var/run/dmesg.boot for irq, and confirm that only open IRQs appear here. The pccard daemon won't think twice about assigning your card to a busy IRQ and crashing your system. Similarly, confirm that the I/O ports are actually open. If you have some cards statically compiled into the kernel (such as the zp card mentioned above), they can take memory spaces listed here and interfere with other PC cards.

Beneath this is a list of PC cards. This list contains most of the cards that work with FreeBSD. If you have a card that doesn't appear on this list and have a working configuration for it, please send-pr(1) it.

The pccard.conf file is built from information obtained directly from cards. Each PC card has a small amount of nonvolatile memory. When pccardd detects a card, it reads that memory and tries to match it to an entry in pccard.conf. If every characteristic matches the driver, and the laptop has the proper resources free, the card will run. If the card doesn't run, chances are the entry is incorrect somewhere.

Each entry starts with:

card [manufacturer] [version] [add_info1] [add_info2 ]

The manufacturer and version appear on every PC card. Some cards have one or two fields of additional information. Pccardd uses the manufacturer, version, and other information to match a card to a configuration.

Every entry also contains the line:

config [index] [driver] [interrupt] [flags]

The index entry indicates which of the card's possible configurations to use. The driver is the kernel driver this card uses. The interrupt is the IRQ the card takes. Whenever possible, use ? as the interrupt number. It's much better in the long run to get the irq line correct than to tweak individual entries. The flags are the same ones used in kernel configuration; you can get them from the device driver man page.

The optional ether keyword indicates that the card stores its physical MAC address in the card's memory. The offset is the distance into memory where the information can be found. If you find yourself changing this value, you're probably looking at the wrong entry.

The optional reset keyword tells pccardd to reset the card a certain number of milliseconds after it is inserted. This gives the card a chance to power on and warm up. By default, cards are reset 100 ms after insertion. If your card doesn't work well, you might need to increase this value.

The iosize and memsize keywords allow you to set I/O port and memory size information, if they are not specified on the card itself.

The insert keyword marks a shell command that is run when the card is inserted and activated. Similarly, the remove keyword is a shell command to run when the card is removed.

Lastly, the logstr line is a free-text string that will be entered in the system log when the card is inserted or removed. (This only works in 4.0 and newer.)

You use the above to tell FreeBSD what to match on the card and to issue instructions to the card. The matching part can be a problem if you don't know what the card says. You can read the card directly with the pccardc program.

Make sure your card is inserted and type:

pccardc dumpcis

This will generate a lot of information. Try it again, and redirect the output to a file.

Each card gives information in "tuples." Some tuples include generic card information, while others give specifics on interrupts and memory slots the card can use. For example, my Xircom includes the tuple shown here.

This is a gold mine of card information. First of all, the fourth line down gives you the config index for this card. Near the bottom you'll find IRQs. (IRQs given by "pccardc dumpcis" are hints only. Each card only has one valid interrupt. This gives you a place to start looking, however.) If you look in tuple #3, you find the description and manufacturer. You can use this information to tweak /etc/defaults/pccard.conf or to create your own custom /etc/pccard.conf.

Laptop FreeBSD is a huge topic, and I could easily write much more about management versus polling mode, suspend, resume, and all the horrible little details of Unix management. Getting your system on the network is a vital first step, however, and the above should get you there.

I've worked with a FreeBSD laptop as my primary system for some time now. On one memorable occasion, I plugged it in as a replacement firewall and the users said the network was running faster than with a proprietary solution. It makes a wonderful portable packet sniffer, dumb terminal, e-mail reader, and all-around BSD workstation.

Plus, royal-blooded Unix on a laptop is simply too cool for words.

Thanks to many, many readers of freebsd-mobile for their kind review of this article. Anyone who says that BSD is snobbish should hang out there for a while.

Michael W. Lucas


Read more Big Scary Daemons columns.

Discuss this article in the Operating Systems Forum.

Return to the BSD DevCenter.

 

Copyright © 2009 O'Reilly Media, Inc.