380 lines
18 KiB
Text
380 lines
18 KiB
Text
<!--
|
|
The FreeBSD Documentation Project
|
|
|
|
$FreeBSD$
|
|
-->
|
|
|
|
<chapter id="pccard">
|
|
<title>PC Card</title>
|
|
|
|
<indexterm><primary>PC Card</primary></indexterm>
|
|
<indexterm><primary>CardBus</primary></indexterm>
|
|
|
|
<para>This chapter will talk about the FreeBSD mechanisms for
|
|
writing a device driver for a PC Card or CardBus device. However,
|
|
at the present time, it just documents how to add a driver to an
|
|
existing pccard driver.</para>
|
|
|
|
<sect1 id="pccard-adddev">
|
|
<title>Adding a device</title>
|
|
|
|
<para>The procedure for adding a new device to the list of
|
|
supported pccard devices has changed from the system used
|
|
through FreeBSD 4. In prior versions, editing a file in
|
|
<filename>/etc</filename> to list the device was necessary.
|
|
Starting in FreeBSD 5.0, devices drivers know what devices they
|
|
support. There is now a table of supported devices in the
|
|
kernel that drivers use to attach to a device.</para>
|
|
|
|
<sect2 id="pccard-overview">
|
|
<title>Overview</title>
|
|
|
|
<indexterm><primary>CIS</primary></indexterm>
|
|
<para>PC Cards are identified in one of two ways, both based on
|
|
information in the <acronym>CIS</acronym> of 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.</para>
|
|
|
|
<para>There is a widespread practice of one company developing a
|
|
reference design for a PC Card product and then selling 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.
|
|
However, the refinements to the physical card typically are
|
|
very minor, if any changes are made at all. Often, however,
|
|
to strengthen their branding of their version of the card,
|
|
these vendors will place their company name in the human
|
|
strings in the CIS space, but leave the manufacturer and
|
|
product ids unchanged.</para>
|
|
|
|
<indexterm><primary>NetGear</primary></indexterm>
|
|
<indexterm><primary>Linksys</primary></indexterm>
|
|
<indexterm><primary>D-Link</primary></indexterm>
|
|
|
|
<para>Because of the above practice, it is a smaller work load
|
|
for FreeBSD to use the numeric IDs. It also introduces some
|
|
minor complications into the process of adding IDs 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 from 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. Yet often, these
|
|
devices will all have the same manufacturer and product
|
|
id.</para>
|
|
|
|
<para>The PC Card bus keeps its central database of card
|
|
information, but not which driver is associated with them, in
|
|
<filename>/sys/dev/pccard/pccarddevs</filename>. It also
|
|
provides a set of macros that allow one to easily construct
|
|
simple entries in the table the driver uses to claim
|
|
devices.</para>
|
|
|
|
<para>Finally, some really low end devices do not contain
|
|
manufacturer identification at all. These devices require
|
|
that one matches them using 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
|
|
that are quite popular. 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
|
|
<acronym>OEM</acronym> nature of the PC Card business. When
|
|
adding new devices, prefer using the numeric method.</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="pccard-pccarddevs">
|
|
<title>Format of <filename>pccarddevs</filename></title>
|
|
|
|
<para>There are four sections of the
|
|
<filename>pccarddevs</filename> files. The first section
|
|
lists the manufacturer numbers for those 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 those devices that use the
|
|
string matching method. Finally, C-style comments are allowed
|
|
anywhere in the file.</para>
|
|
|
|
<para>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:</para>
|
|
|
|
<programlisting>vendor FUJITSU 0x0004 Fujitsu Corporation
|
|
vendor NETGEAR_2 0x000b Netgear
|
|
vendor PANASONIC 0x0032 Matsushita Electric Industrial Co.
|
|
vendor SANDISK 0x0045 Sandisk Corporation</programlisting>
|
|
|
|
<para>shows the first few vendor ids. Chances are very good
|
|
that the <literal>NETGEAR_2</literal> 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.
|
|
There is the vendor keyword used to denote the kind of line
|
|
that this is. There is the name of the vendor. This name will
|
|
be repeated later in the pccarddevs file, as well as used in
|
|
the driver's match tables, so keep it short and a valid C
|
|
identifier. There is a numeric ID, in hex, for the
|
|
manufacturer. Do not add IDs of the form
|
|
<literal>0xffffffff</literal> or <literal>0xffff</literal>
|
|
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.</para>
|
|
|
|
<para>The second section of the file contains the products. As
|
|
you can see in the following example:</para>
|
|
|
|
<programlisting>/* Allied Telesis K.K. */
|
|
product ALLIEDTELESIS LA_PCM 0x0002 Allied Telesis LA-PCM
|
|
|
|
/* Archos */
|
|
product ARCHOS ARC_ATAPI 0x0043 MiniCD</programlisting>
|
|
|
|
<para>the format is similar to the vendor lines. There is the
|
|
product keyword. Then there is 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. There is then the product id for this
|
|
card, in hex. As with the vendors, there is the same
|
|
convention for <literal>0xffffffff</literal> and
|
|
<literal>0xffff</literal>. 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.</para>
|
|
|
|
<para>The third section is like the previous vendor section, but
|
|
with all of the manufacturer numeric ids as
|
|
<literal>-1</literal>. <literal>-1</literal> means
|
|
<quote>match anything you find</quote> 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.</para>
|
|
|
|
<para>The final section contains the entries for those cards
|
|
that we must match with string entries. This sections' format
|
|
is a little different than the generic section:</para>
|
|
|
|
<programlisting>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</programlisting>
|
|
|
|
<para>We have the familiar product keyword, followed by the
|
|
vendor name followed by the card name, just as in the second
|
|
section of the file. However, then we deviate from that
|
|
format. 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
|
|
<filename>pccarddevs.h</filename> to replace &sp with a
|
|
real space. NULL strings mean that the corresponding part
|
|
of the entry
|
|
should be ignored. In the example I have picked, there is a bad
|
|
entry. It should not contain the version number in it 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.</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="pccard-probe">
|
|
<title>Sample probe routine</title>
|
|
|
|
<indexterm><primary>PC Card</primary><secondary>probe</secondary></indexterm>
|
|
|
|
<para>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.</para>
|
|
|
|
<programlisting>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);
|
|
}</programlisting>
|
|
|
|
<para>Here we have a simple pccard probe routine that matches a
|
|
few devices. As stated above, the name may vary (if it is not
|
|
<function>foo_pccard_probe()</function> it will be
|
|
<function>foo_pccard_match()</function>). The function
|
|
<function>pccard_product_lookup()</function> 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 if you have a different
|
|
table, the first element of the structure you have a table of
|
|
be a struct pccard_product.</para>
|
|
|
|
<para>Looking at the table
|
|
<structname>wi_pccard_products</structname>, one notices that
|
|
all the entries are of the form
|
|
<function>PCMCIA_CARD(<replaceable>foo</replaceable>,
|
|
<replaceable>bar</replaceable>,
|
|
<replaceable>baz</replaceable>)</function>. The
|
|
<replaceable>foo</replaceable> part is the manufacturer id
|
|
from <filename>pccarddevs</filename>. The
|
|
<replaceable>bar</replaceable> part is the product. The
|
|
<replaceable>baz</replaceable> is the expected function number
|
|
that for this card. Many pccards can have multiple functions,
|
|
and some way to disambiguate function 1 from function 0 is
|
|
needed. You may see <literal>PCMCIA_CARD_D</literal>, which
|
|
includes the device description from the
|
|
<filename>pccarddevs</filename> file. You may also see
|
|
<literal>PCMCIA_CARD2</literal> and
|
|
<literal>PCMCIA_CARD2_D</literal> which are used when you need
|
|
to match CIS both CIS strings and manufacturer numbers, in the
|
|
<quote>use the default description</quote> and <quote>take the
|
|
description from pccarddevs</quote> flavors.</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="pccard-add">
|
|
<title>Putting it all together</title>
|
|
|
|
<para>So, to add a new device, one must do the following steps.
|
|
First, one must 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 <command>devinfo
|
|
-v</command>. You will likely see something like:</para>
|
|
|
|
<programlisting> 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</programlisting>
|
|
|
|
<para>as part of the output. The manufacturer and product are
|
|
the numeric IDs for this product. While the cisvendor and
|
|
cisproduct are the strings that are present in the CIS that
|
|
describe this product.</para>
|
|
|
|
<para>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:</para>
|
|
|
|
<programlisting>vendor BUFFALO 0x026f BUFFALO (Melco Corporation)</programlisting>
|
|
|
|
<para>so we are good there. Looking for an entry for this card,
|
|
we do not find one. Instead we find:</para>
|
|
|
|
<programlisting>/* 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</programlisting>
|
|
|
|
<para>we can just add</para>
|
|
|
|
<programlisting>product BUFFALO WLI2_CF_S11G 0x030c BUFFALO AirStation ultra 802.11b CF</programlisting>
|
|
|
|
<para>to <filename>pccarddevs</filename>. Presently, there is a
|
|
manual step to regenerate the
|
|
<filename>pccarddevs.h</filename> file used to convey these
|
|
identifiers to the client driver. The following steps
|
|
must be done before you can use them in the driver:</para>
|
|
|
|
<screen>&prompt.root; <userinput>cd src/sys/dev/pccard</userinput>
|
|
&prompt.root; <userinput>make -f Makefile.pccarddevs</userinput>
|
|
</screen>
|
|
|
|
<para>Once these steps are complete, you can add the card to the
|
|
driver. That is a simple operation of adding one line:</para>
|
|
|
|
<programlisting>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 }
|
|
};</programlisting>
|
|
|
|
<para>Note that I have included a '<literal>+</literal>' 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 try to see if it recognizes the device. If it does 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 it did not recognize it at all, you have done something
|
|
wrong and should recheck each step.</para>
|
|
|
|
<para>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 that you need to
|
|
worry about. First, you must commit the
|
|
<filename>pccarddevs</filename> file to the tree. After you
|
|
have done that, you must regenerate
|
|
<filename>pccarddevs.h</filename> and commit it as a second
|
|
commit (this is to make sure that the right
|
|
$FreeBSD$ tag is in the latter file). Finally,
|
|
you need to commit the additions to the driver.</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="pccard-pr">
|
|
<title>Submitting a new device</title>
|
|
|
|
<para>Many people send entries for new devices to the author
|
|
directly. Please do not do this. Please submit them as a PR
|
|
and send the author the PR number for his records. This makes
|
|
sure that entries are not lost. When submitting a PR, it is
|
|
unnecessary to include the <filename>pccardevs.h</filename>
|
|
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.</para>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|