This chapter will talk about the FreeBSD mechanisms for writing a device driver for a PC Card or CardBus device. However, at present it just documents how to add a new device to an existing pccard driver.
Device drivers know what devices they support. There is a table of supported devices in the kernel that drivers use to attach to a device.
PC Cards are identified in one of two ways, both based on the Card Information Structure (CIS) stored on the card. The first method is to use numeric manufacturer and product numbers. The second method is to use the human readable strings that are also contained in the CIS. The PC Card bus uses a centralized database and some macros to facilitate a design pattern to help the driver writer match devices to his driver.
Original equipment manufacturers (OEMs) often develop a reference design for a PC Card product, then sell this design to other companies to market. Those companies refine the design, market the product to their target audience or geographic area, and put their own name plate onto the card. The refinements to the physical card are typically very minor, if any changes are made at all. To strengthen their brand, these vendors place their company name in the human readable strings in the CIS space, but leave the manufacturer and product IDs unchanged.
Because of this practice, FreeBSD drivers usually rely on numeric IDs for device identification. Using numeric IDs and a centralized database complicates adding IDs and support for cards to the system. One must carefully check to see who really made the card, especially when it appears that the vendor who made the card might already have a different manufacturer ID listed in the central database. Linksys, D-Link, and NetGear are a number of US manufacturers of LAN hardware that often sell the same design. These same designs can be sold in Japan under names such as Buffalo and Corega. Often, these devices will all have the same manufacturer and product IDs.
The PC Card bus code keeps a central database of card
information, but not which driver is associated with them, in
/sys/dev/pccard/pccarddevs
. It also
provides a set of macros that allow one to easily construct
simple entries in the table the driver uses to claim
devices.
Finally, some really low end devices do not contain manufacturer identification at all. These devices must be detected by matching the human readable CIS strings. While it would be nice if we did not need this method as a fallback, it is necessary for some very low end CD-ROM players and Ethernet cards. This method should generally be avoided, but a number of devices are listed in this section because they were added prior to the recognition of the OEM nature of the PC Card business. When adding new devices, prefer using the numeric method.
There are four sections in the
pccarddevs
files. The first section
lists the manufacturer numbers for vendors that use
them. This section is sorted in numerical order. The next
section has all of the products that are used by these
vendors, along with their product ID numbers and a description
string. The description string typically is not used (instead
we set the device's description based on the human readable
CIS, even if we match on the numeric version). These two
sections are then repeated for devices that use the
string matching method. Finally, C-style comments enclosed in
/*
and */
characters are
allowed anywhere in the file.
The first section of the file contains the vendor IDs. Please keep this list sorted in numeric order. Also, please coordinate changes to this file because we share it with NetBSD to help facilitate a common clearing house for this information. For example, here are the first few vendor IDs:
vendor FUJITSU 0x0004 Fujitsu Corporation vendor NETGEAR_2 0x000b Netgear vendor PANASONIC 0x0032 Matsushita Electric Industrial Co. vendor SANDISK 0x0045 Sandisk Corporation
Chances are very good
that the NETGEAR_2
entry is really an OEM
that NETGEAR purchased cards from and the author of support
for those cards was unaware at the time that Netgear was using
someone else's ID. These entries are fairly straightforward.
The vendor keyword denotes the kind of line that this is,
followed by the name of the vendor. This name will be
repeated later in pccarddevs
, as
well as used in the driver's match tables, so keep it short
and a valid C identifier. A numeric ID in hex identifies the
manufacturer. Do not add IDs of the form
0xffffffff
or 0xffff
because these are reserved IDs (the former is
“no ID set” while the latter is sometimes seen in
extremely poor quality cards to try to indicate
“none”). Finally there is a string description
of the company that makes the card. This string is not used
in FreeBSD for anything but commentary purposes.
The second section of the file contains the products. As shown in this example, the format is similar to the vendor lines:
/* Allied Telesis K.K. */ product ALLIEDTELESIS LA_PCM 0x0002 Allied Telesis LA-PCM /* Archos */ product ARCHOS ARC_ATAPI 0x0043 MiniCD
The
product
keyword is followed by the vendor
name, repeated from above. This is followed by the product
name, which is used by the driver and should be a valid C
identifier, but may also start with a number. As with the
vendors, the hex product ID for this card follows the same
convention for 0xffffffff
and
0xffff
. Finally, there is a string
description of the device itself. This string typically is
not used in FreeBSD, since FreeBSD's pccard bus driver will
construct a string from the human readable CIS entries, but it
can be used in the rare cases where this is somehow
insufficient. The products are in alphabetical order by
manufacturer, then numerical order by product ID. They have a
C comment before each manufacturer's entries and there is a
blank line between entries.
The third section is like the previous vendor section, but
with all of the manufacturer numeric IDs set to
-1
, meaning
“match anything found” in the FreeBSD pccard
bus code. Since these are C identifiers, their names must be
unique. Otherwise the format is identical to the first
section of the file.
The final section contains the entries for those cards that must be identified by string entries. This section's format is a little different from the generic section:
product ADDTRON AWP100 { "Addtron", "AWP-100&spWireless&spPCMCIA", "Version&sp01.02", NULL } product ALLIEDTELESIS WR211PCM { "Allied&spTelesis&spK.K.", "WR211PCM", NULL, NULL } Allied Telesis WR211PCM
The familiar product
keyword is
followed by the vendor name and the card name, just as in the
second section of the file. Here the format deviates from
that used earlier. There is a {} grouping, followed by a
number of strings. These strings correspond to the vendor,
product, and extra information that is defined in a CIS_INFO
tuple. These strings are filtered by the program that
generates pccarddevs.h
to replace &sp
with a real space. NULL strings mean that the corresponding
part of the entry should be ignored. The example shown here
contains a bad entry. It should not contain the version
number unless that is critical for the operation of the card.
Sometimes vendors will have many different versions of the
card in the field that all work, in which case that
information only makes it harder for someone with a similar
card to use it with FreeBSD. Sometimes it is necessary when a
vendor wishes to sell many different parts under the same
brand due to market considerations (availability, price, and
so forth). Then it can be critical to disambiguating the card
in those rare cases where the vendor kept the same
manufacturer/product pair. Regular expression matching is not
available at this time.
To understand how to add a device to the list of supported devices, one must understand the probe and/or match routines that many drivers have. It is complicated a little in FreeBSD 5.x because there is a compatibility layer for OLDCARD present as well. Since only the window-dressing is different, an idealized version will be presented here.
static const struct pccard_product wi_pccard_products[] = { PCMCIA_CARD(3COM, 3CRWE737A, 0), PCMCIA_CARD(BUFFALO, WLI_PCM_S11, 0), PCMCIA_CARD(BUFFALO, WLI_CF_S11G, 0), PCMCIA_CARD(TDK, LAK_CD011WL, 0), { NULL } }; static int wi_pccard_probe(dev) device_t dev; { const struct pccard_product *pp; if ((pp = pccard_product_lookup(dev, wi_pccard_products, sizeof(wi_pccard_products[0]), NULL)) != NULL) { if (pp->pp_name != NULL) device_set_desc(dev, pp->pp_name); return (0); } return (ENXIO); }
Here we have a simple pccard probe routine that matches a
few devices. As stated above, the name may vary (if it is not
foo_pccard_probe()
it will be
foo_pccard_match()
). The function
pccard_product_lookup()
is a generalized
function that walks the table and returns a pointer to the
first entry that it matches. Some drivers may use this
mechanism to convey additional information about some cards to
the rest of the driver, so there may be some variance in the
table. The only requirement is that each row of the table
must have a struct
pccard_product
as the first
element.
Looking at the table
wi_pccard_products
, one notices that
all the entries are of the form
PCMCIA_CARD(
. The
foo
,
bar
,
baz
)foo
part is the manufacturer ID
from pccarddevs
. The
bar
part is the product ID.
baz
is the expected function number
for this card. Many pccards can have multiple functions,
and some way to disambiguate function 1 from function 0 is
needed. You may see PCMCIA_CARD_D
, which
includes the device description from
pccarddevs
. You may also see
PCMCIA_CARD2
and
PCMCIA_CARD2_D
which are used when you need
to match both CIS strings and manufacturer numbers, in the
“use the default description” and “take the
description from pccarddevs” flavors.
To add a new device, one must first obtain the
identification information from the
device. The easiest way to do this is to insert the device
into a PC Card or CF slot and issue
devinfo -v
. Sample output:
cbb1 pnpinfo vendor=0x104c device=0xac51 subvendor=0x1265 subdevice=0x0300 class=0x060700 at slot=10 function=1 cardbus1 pccard1 unknown pnpinfo manufacturer=0x026f product=0x030c cisvendor="BUFFALO" cisproduct="WLI2-CF-S11" function_type=6 at function=0
manufacturer
and product
are the numeric IDs for this
product, while cisvendor
and
cisproduct
are the product description
strings from the CIS.
Since we first want to prefer the numeric option, first try to construct an entry based on that. The above card has been slightly fictionalized for the purpose of this example. The vendor is BUFFALO, which we see already has an entry:
vendor BUFFALO 0x026f BUFFALO (Melco Corporation)
But there is no entry for this particular card. Instead we find:
/* BUFFALO */ product BUFFALO WLI_PCM_S11 0x0305 BUFFALO AirStation 11Mbps WLAN product BUFFALO LPC_CF_CLT 0x0307 BUFFALO LPC-CF-CLT product BUFFALO LPC3_CLT 0x030a BUFFALO LPC3-CLT Ethernet Adapter product BUFFALO WLI_CF_S11G 0x030b BUFFALO AirStation 11Mbps CF WLAN
To add the device, we can just add this entry to
pccarddevs
:
product BUFFALO WLI2_CF_S11G 0x030c BUFFALO AirStation ultra 802.11b CF
Once these steps are complete, the card can be added to the driver. That is a simple operation of adding one line:
static const struct pccard_product wi_pccard_products[] = { PCMCIA_CARD(3COM, 3CRWE737A, 0), PCMCIA_CARD(BUFFALO, WLI_PCM_S11, 0), PCMCIA_CARD(BUFFALO, WLI_CF_S11G, 0), + PCMCIA_CARD(BUFFALO, WLI_CF2_S11G, 0), PCMCIA_CARD(TDK, LAK_CD011WL, 0), { NULL } };
Note that I have included a '+
' in the
line before the line that I added, but that is simply to
highlight the line. Do not add it to the actual driver. Once
you have added the line, you can recompile your kernel or
module and test it. If the device is recognized and works,
please submit a patch. If it does not work, please figure out
what is needed to make it work and submit a patch. If the
device is not recognized at all, you have done something wrong
and should recheck each step.
If you are a FreeBSD src committer, and everything appears
to be working, then you can commit the changes to the tree.
However, there are some minor tricky things to be considered.
pccarddevs
must be committed to the tree
first. Then pccarddevs.h
must be
regenerated and committed as a second step, ensuring that the
right $FreeBSD$ tag is in the latter file.
Finally, commit the additions to the driver.
Please do not send entries for new devices to the author
directly. Instead, submit them as a PR and send the author
the PR number for his records. This ensures that entries are
not lost. When submitting a PR, it is unnecessary to include
the pccardevs.h
diffs in the patch, since
those will be regenerated. It is necessary to include a
description of the device, as well as the patches to the
client driver. If you do not know the name, use OEM99 as the
name, and the author will adjust OEM99 accordingly after
investigation. Committers should not commit OEM99, but
instead find the highest OEM entry and commit one more than
that.
All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.