Edit for clarity and readability. Fix title capitalization.

Reviewed by:	imp
This commit is contained in:
Warren Block 2012-04-02 15:26:21 +00:00
parent 079c70279a
commit 1211b57ee0
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=38639

View file

@ -12,22 +12,24 @@
<para>This chapter will talk about the FreeBSD mechanisms for <para>This chapter will talk about the FreeBSD mechanisms for
writing a device driver for a PC Card or CardBus device. However, 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 at present it just documents how to add a new device to an
existing pccard driver.</para> existing pccard driver.</para>
<sect1 id="pccard-adddev"> <sect1 id="pccard-adddev">
<title>Adding a device</title> <title>Adding a Device</title>
<para>Devices drivers know what devices they <para>Device drivers know what devices they support. There is a
support. There is a table of supported devices in the table of supported devices in the kernel that drivers use to
kernel that drivers use to attach to a device.</para> attach to a device.</para>
<sect2 id="pccard-overview"> <sect2 id="pccard-overview">
<title>Overview</title> <title>Overview</title>
<indexterm><primary>CIS</primary></indexterm> <indexterm><primary>CIS</primary></indexterm>
<para>PC Cards are identified in one of two ways, both based on <para>PC Cards are identified in one of two ways, both based on
information in the <acronym>CIS</acronym> of the card. The the <firstterm>Card Information Structure</firstterm>
(<acronym role="Card Information Structure">CIS</acronym>)
stored on the card. The
first method is to use numeric manufacturer and product first method is to use numeric manufacturer and product
numbers. The second method is to use the human readable numbers. The second method is to use the human readable
strings that are also contained in the CIS. The PC Card bus strings that are also contained in the CIS. The PC Card bus
@ -35,34 +37,33 @@
design pattern to help the driver writer match devices to his design pattern to help the driver writer match devices to his
driver.</para> driver.</para>
<para>OEMs manufacturers often develop a reference design for <para>Original equipment manufacturers (<acronym>OEM</acronym>s)
a PC Card product sell this design to other companies to often develop a
market. Those companies refine reference design for a PC Card product, then sell this design
the design, market the product to their target audience or to other companies to market. Those companies refine the
geographic area and put their own name plate onto the card. design, market the product to their target audience or
The refinements to the physical card typically are geographic area, and put their own name plate onto the card.
very minor, if any changes are made at all. However, The refinements to the physical card are typically very minor,
to strengthen their brand, if any changes are made at all. To strengthen their brand,
these vendors place their company name in the human these vendors place their company name in the human readable strings in
strings in the CIS space, but leave the manufacturer and the CIS space, but leave the manufacturer and product IDs
product ids unchanged.</para> unchanged.</para>
<indexterm><primary>NetGear</primary></indexterm> <indexterm><primary>NetGear</primary></indexterm>
<indexterm><primary>Linksys</primary></indexterm> <indexterm><primary>Linksys</primary></indexterm>
<indexterm><primary>D-Link</primary></indexterm> <indexterm><primary>D-Link</primary></indexterm>
<para>Because of this practice, FreeBSD drivers tend to <para>Because of this practice, FreeBSD drivers usually rely on
use the numeric IDs. Using numeric IDs and a centralized numeric IDs for device identification. Using numeric IDs and a centralized database
database complicates adding IDs and support for cards to the complicates adding IDs and support for cards to the system.
system. One must carefully check to see who really made the One must carefully check to see who really made the card,
card, especially when it appears that the vendor who made the especially when it appears that the vendor who made the card
card from might already have a different manufacturer id might already have a different manufacturer ID listed in the
listed in the central database. Linksys, D-Link and NetGear central database. Linksys, D-Link, and NetGear are a number of
are a number of US Manufacturers of LAN hardware that often US manufacturers of LAN hardware that often sell the same
sell the same design. These same designs can be sold in Japan design. These same designs can be sold in Japan under names
under names such as Buffalo and Corega. Yet often, these such as Buffalo and Corega. Often, these devices will all
devices will all have the same manufacturer and product have the same manufacturer and product IDs.</para>
id.</para>
<para>The PC Card bus code keeps a central database of card <para>The PC Card bus code keeps a central database of card
information, but not which driver is associated with them, in information, but not which driver is associated with them, in
@ -72,11 +73,11 @@
devices.</para> devices.</para>
<para>Finally, some really low end devices do not contain <para>Finally, some really low end devices do not contain
manufacturer identification at all. These devices require manufacturer identification at all. These devices must be
that one matches them using the human readable CIS strings. detected by matching the human readable CIS strings.
While it would be nice if we did not need this method as a 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 fallback, it is necessary for some very low end CD-ROM players
and ethernet cards. This method should generally be and Ethernet cards. This method should generally be
avoided, but a number of devices are listed in this section avoided, but a number of devices are listed in this section
because they were added prior to the recognition of the because they were added prior to the recognition of the
<acronym>OEM</acronym> nature of the PC Card business. When <acronym>OEM</acronym> nature of the PC Card business. When
@ -86,51 +87,54 @@
<sect2 id="pccard-pccarddevs"> <sect2 id="pccard-pccarddevs">
<title>Format of <filename>pccarddevs</filename></title> <title>Format of <filename>pccarddevs</filename></title>
<para>There are four sections of the <para>There are four sections in the
<filename>pccarddevs</filename> files. The first section <filename>pccarddevs</filename> files. The first section
lists the manufacturer numbers for those vendors that use lists the manufacturer numbers for vendors that use
them. This section is sorted in numerical order. The next them. This section is sorted in numerical order. The next
section has all of the products that are used by these section has all of the products that are used by these
vendors, along with their product ID numbers and a description vendors, along with their product ID numbers and a description
string. The description string typically is not used (instead string. The description string typically is not used (instead
we set the device's description based on the human readable we set the device's description based on the human readable
CIS, even if we match on the numeric version). These two CIS, even if we match on the numeric version). These two
sections are then repeated for those devices that use the sections are then repeated for devices that use the
string matching method. Finally, C-style comments are allowed string matching method. Finally, C-style comments enclosed in
anywhere in the file.</para> <literal>/*</literal> and <literal>*/</literal> characters are
allowed anywhere in the file.</para>
<para>The first section of the file contains the vendor IDs. <para>The first section of the file contains the vendor IDs.
Please keep this list sorted in numeric order. Also, please Please keep this list sorted in numeric order. Also, please
coordinate changes to this file because we share it with coordinate changes to this file because we share it with
NetBSD to help facilitate a common clearing house for this NetBSD to help facilitate a common clearing house for this
information. For example:</para> information. For example, here are the first few vendor
IDs:</para>
<programlisting>vendor FUJITSU 0x0004 Fujitsu Corporation <programlisting>vendor FUJITSU 0x0004 Fujitsu Corporation
vendor NETGEAR_2 0x000b Netgear vendor NETGEAR_2 0x000b Netgear
vendor PANASONIC 0x0032 Matsushita Electric Industrial Co. vendor PANASONIC 0x0032 Matsushita Electric Industrial Co.
vendor SANDISK 0x0045 Sandisk Corporation</programlisting> vendor SANDISK 0x0045 Sandisk Corporation</programlisting>
<para>shows the first few vendor ids. Chances are very good <para>Chances are very good
that the <literal>NETGEAR_2</literal> entry is really an OEM that the <literal>NETGEAR_2</literal> entry is really an OEM
that NETGEAR purchased cards from and the author of support that NETGEAR purchased cards from and the author of support
for those cards was unaware at the time that Netgear was using for those cards was unaware at the time that Netgear was using
someone else's id. These entries are fairly straightforward. someone else's ID. These entries are fairly straightforward.
There is the vendor keyword used to denote the kind of line The vendor keyword denotes the kind of line that this is,
that this is. There is the name of the vendor. This name followed by the name of the vendor. This name will be
will be repeated later in the pccarddevs file, as well as used repeated later in <filename>pccarddevs</filename>, as
in the driver's match tables, so keep it short and a valid C well as used in the driver's match tables, so keep it short
identifier. There is a numeric ID, in hex, for the and a valid C identifier. A numeric ID in hex identifies the
manufacturer. Do not add IDs of the form manufacturer. Do not add IDs of the form
<literal>0xffffffff</literal> or <literal>0xffff</literal> <literal>0xffffffff</literal> or <literal>0xffff</literal>
because these are reserved ids (the former is 'no id set' because these are reserved IDs (the former is
while the latter is sometimes seen in extremely poor quality <quote>no ID set</quote> while the latter is sometimes seen in
cards to try to indicate 'none). Finally there is a string extremely poor quality cards to try to indicate
description of the company that makes the card. This string <quote>none</quote>). Finally there is a string description
is not used in FreeBSD for anything but commentary of the company that makes the card. This string is not used
purposes.</para> in FreeBSD for anything but commentary purposes.</para>
<para>The second section of the file contains the products. As <para>The second section of the file contains the products. As
you can see in the following example:</para> shown in this example, the format is similar to the vendor
lines:</para>
<programlisting>/* Allied Telesis K.K. */ <programlisting>/* Allied Telesis K.K. */
product ALLIEDTELESIS LA_PCM 0x0002 Allied Telesis LA-PCM product ALLIEDTELESIS LA_PCM 0x0002 Allied Telesis LA-PCM
@ -138,12 +142,12 @@ product ALLIEDTELESIS LA_PCM 0x0002 Allied Telesis LA-PCM
/* Archos */ /* Archos */
product ARCHOS ARC_ATAPI 0x0043 MiniCD</programlisting> product ARCHOS ARC_ATAPI 0x0043 MiniCD</programlisting>
<para>the format is similar to the vendor lines. There is the <para>The
product keyword. Then there is the vendor name, repeated from <literal>product</literal> keyword is followed by the vendor
above. This is followed by the product name, which is used by name, repeated from above. This is followed by the product
the driver and should be a valid C identifier, but may also name, which is used by the driver and should be a valid C
start with a number. There is then the product id for this identifier, but may also start with a number. As with the
card, in hex. As with the vendors, there is the same vendors, the hex product ID for this card follows the same
convention for <literal>0xffffffff</literal> and convention for <literal>0xffffffff</literal> and
<literal>0xffff</literal>. Finally, there is a string <literal>0xffff</literal>. Finally, there is a string
description of the device itself. This string typically is description of the device itself. This string typically is
@ -151,51 +155,51 @@ product ARCHOS ARC_ATAPI 0x0043 MiniCD</programlisting>
construct a string from the human readable CIS entries, but it construct a string from the human readable CIS entries, but it
can be used in the rare cases where this is somehow can be used in the rare cases where this is somehow
insufficient. The products are in alphabetical order by insufficient. The products are in alphabetical order by
manufacturer, then numerical order by product id. They have a manufacturer, then numerical order by product ID. They have a
C comment before each manufacturer's entries and there is a C comment before each manufacturer's entries and there is a
blank line between entries.</para> blank line between entries.</para>
<para>The third section is like the previous vendor section, but <para>The third section is like the previous vendor section, but
with all of the manufacturer numeric ids as with all of the manufacturer numeric IDs set to
<literal>-1</literal>. <literal>-1</literal> means <literal>-1</literal>, meaning
<quote>match anything you find</quote> in the FreeBSD pccard <quote>match anything found</quote> in the FreeBSD pccard
bus code. Since these are C identifiers, their names must be bus code. Since these are C identifiers, their names must be
unique. Otherwise the format is identical to the first unique. Otherwise the format is identical to the first
section of the file.</para> section of the file.</para>
<para>The final section contains the entries for those cards <para>The final section contains the entries for those cards
that we must match with string entries. This sections' format that must be identified by string entries. This section's format
is a little different than the generic section:</para> is a little different from the generic section:</para>
<programlisting>product ADDTRON AWP100 { "Addtron", "AWP-100&amp;spWireless&amp;spPCMCIA", "Version&amp;sp01.02", NULL } <programlisting>product ADDTRON AWP100 { "Addtron", "AWP-100&amp;spWireless&amp;spPCMCIA", "Version&amp;sp01.02", NULL }
product ALLIEDTELESIS WR211PCM { "Allied&amp;spTelesis&amp;spK.K.", "WR211PCM", NULL, NULL } Allied Telesis WR211PCM</programlisting> product ALLIEDTELESIS WR211PCM { "Allied&amp;spTelesis&amp;spK.K.", "WR211PCM", NULL, NULL } Allied Telesis WR211PCM</programlisting>
<para>We have the familiar product keyword, followed by the <para>The familiar <literal>product</literal> keyword is
vendor name followed by the card name, just as in the second followed by the vendor name and the card name, just as in the
section of the file. However, then we deviate from that second section of the file. Here the format deviates from
format. There is a {} grouping, followed by a number of that used earlier. There is a {} grouping, followed by a number of
strings. These strings correspond to the vendor, product and strings. These strings correspond to the vendor, product, and
extra information that is defined in a CIS_INFO tuple. These extra information that is defined in a CIS_INFO tuple. These
strings are filtered by the program that generates strings are filtered by the program that generates
<filename>pccarddevs.h</filename> to replace &amp;sp with a <filename>pccarddevs.h</filename> to replace &amp;sp with a
real space. NULL strings mean that the corresponding part real space. NULL strings mean that the corresponding part of
of the entry should be ignored. In the example I have picked, the entry should be ignored. The example shown here contains
there is a bad entry. It should not contain the version a bad entry. It should not contain the version number unless
number in it unless that is critical for the operation of the that is critical for the operation of the card. Sometimes
card. Sometimes vendors will have many different versions of vendors will have many different versions of the card in the
the card in the field that all work, in which case that field that all work, in which case that information only makes
information only makes it harder for someone with a similar it harder for someone with a similar card to use it with
card to use it with FreeBSD. Sometimes it is necessary when a FreeBSD. Sometimes it is necessary when a vendor wishes to
vendor wishes to sell many different parts under the same sell many different parts under the same brand due to market
brand due to market considerations (availability, price, and considerations (availability, price, and so forth). Then it
so forth). Then it can be critical to disambiguating the card can be critical to disambiguating the card in those rare cases
in those rare cases where the vendor kept the same where the vendor kept the same manufacturer/product pair.
manufacturer/product pair. Regular expression matching is not Regular expression matching is not available at this
available at this time.</para> time.</para>
</sect2> </sect2>
<sect2 id="pccard-probe"> <sect2 id="pccard-probe">
<title>Sample probe routine</title> <title>Sample Probe Routine</title>
<indexterm> <indexterm>
<primary>PC Card</primary> <primary>PC Card</primary>
@ -241,9 +245,10 @@ wi_pccard_probe(dev)
first entry that it matches. Some drivers may use this first entry that it matches. Some drivers may use this
mechanism to convey additional information about some cards to mechanism to convey additional information about some cards to
the rest of the driver, so there may be some variance in the 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 only requirement is that each row of the table
table, the first element of the structure you have a table of must have a <function>struct</function>
be a struct pccard_product.</para> <structname>pccard_product</structname> as the first
element.</para>
<para>Looking at the table <para>Looking at the table
<structname>wi_pccard_products</structname>, one notices that <structname>wi_pccard_products</structname>, one notices that
@ -251,41 +256,41 @@ wi_pccard_probe(dev)
<function>PCMCIA_CARD(<replaceable>foo</replaceable>, <function>PCMCIA_CARD(<replaceable>foo</replaceable>,
<replaceable>bar</replaceable>, <replaceable>bar</replaceable>,
<replaceable>baz</replaceable>)</function>. The <replaceable>baz</replaceable>)</function>. The
<replaceable>foo</replaceable> part is the manufacturer id <replaceable>foo</replaceable> part is the manufacturer ID
from <filename>pccarddevs</filename>. The from <filename>pccarddevs</filename>. The
<replaceable>bar</replaceable> part is the product. The <replaceable>bar</replaceable> part is the product ID.
<replaceable>baz</replaceable> is the expected function number <replaceable>baz</replaceable> is the expected function number
that for this card. Many pccards can have multiple functions, for this card. Many pccards can have multiple functions,
and some way to disambiguate function 1 from function 0 is and some way to disambiguate function 1 from function 0 is
needed. You may see <literal>PCMCIA_CARD_D</literal>, which needed. You may see <literal>PCMCIA_CARD_D</literal>, which
includes the device description from the includes the device description from
<filename>pccarddevs</filename> file. You may also see <filename>pccarddevs</filename>. You may also see
<literal>PCMCIA_CARD2</literal> and <literal>PCMCIA_CARD2</literal> and
<literal>PCMCIA_CARD2_D</literal> which are used when you need <literal>PCMCIA_CARD2_D</literal> which are used when you need
to match CIS both CIS strings and manufacturer numbers, in the to match both CIS strings and manufacturer numbers, in the
<quote>use the default description</quote> and <quote>take the <quote>use the default description</quote> and <quote>take the
description from pccarddevs</quote> flavors.</para> description from pccarddevs</quote> flavors.</para>
</sect2> </sect2>
<sect2 id="pccard-add"> <sect2 id="pccard-add">
<title>Putting it all together</title> <title>Putting it All Together</title>
<para>So, to add a new device, one must do the following steps. <para>To add a new device, one must first obtain the
First, one must obtain the identification information from the identification information from the
device. The easiest way to do this is to insert the device device. The easiest way to do this is to insert the device
into a PC Card or CF slot and issue into a PC Card or CF slot and issue
<command>devinfo -v</command>. You will likely see something <command>devinfo -v</command>. Sample output:</para>
like:</para>
<programlisting> cbb1 pnpinfo vendor=0x104c device=0xac51 subvendor=0x1265 subdevice=0x0300 class=0x060700 at slot=10 function=1 <programlisting> cbb1 pnpinfo vendor=0x104c device=0xac51 subvendor=0x1265 subdevice=0x0300 class=0x060700 at slot=10 function=1
cardbus1 cardbus1
pccard1 pccard1
unknown pnpinfo manufacturer=0x026f product=0x030c cisvendor="BUFFALO" cisproduct="WLI2-CF-S11" function_type=6 at function=0</programlisting> 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 <para><literal>manufacturer</literal>
the numeric IDs for this product. While the cisvendor and and <literal>product</literal> are the numeric IDs for this
cisproduct are the strings that are present in the CIS that product, while <literal>cisvendor</literal> and
describe this product.</para> <literal>cisproduct</literal> are the product description
strings from the CIS.</para>
<para>Since we first want to prefer the numeric option, first <para>Since we first want to prefer the numeric option, first
try to construct an entry based on that. The above card has try to construct an entry based on that. The above card has
@ -295,8 +300,8 @@ wi_pccard_probe(dev)
<programlisting>vendor BUFFALO 0x026f BUFFALO (Melco Corporation)</programlisting> <programlisting>vendor BUFFALO 0x026f BUFFALO (Melco Corporation)</programlisting>
<para>so we are good there. Looking for an entry for this card, <para>But there is no entry for this particular card.
we do not find one. Instead we find:</para> Instead we find:</para>
<programlisting>/* BUFFALO */ <programlisting>/* BUFFALO */
product BUFFALO WLI_PCM_S11 0x0305 BUFFALO AirStation 11Mbps WLAN product BUFFALO WLI_PCM_S11 0x0305 BUFFALO AirStation 11Mbps WLAN
@ -304,21 +309,20 @@ product BUFFALO LPC_CF_CLT 0x0307 BUFFALO LPC-CF-CLT
product BUFFALO LPC3_CLT 0x030a BUFFALO LPC3-CLT Ethernet Adapter product BUFFALO LPC3_CLT 0x030a BUFFALO LPC3-CLT Ethernet Adapter
product BUFFALO WLI_CF_S11G 0x030b BUFFALO AirStation 11Mbps CF WLAN</programlisting> product BUFFALO WLI_CF_S11G 0x030b BUFFALO AirStation 11Mbps CF WLAN</programlisting>
<para>we can just add</para> <para>To add the device, we can just add this entry to <filename>pccarddevs</filename>:</para>
<programlisting>product BUFFALO WLI2_CF_S11G 0x030c BUFFALO AirStation ultra 802.11b CF</programlisting> <programlisting>product BUFFALO WLI2_CF_S11G 0x030c BUFFALO AirStation ultra 802.11b CF</programlisting>
<para>to <filename>pccarddevs</filename>. Presently, there is a <para>At present, there is a
manual step to regenerate the manual step to regenerate
<filename>pccarddevs.h</filename> file used to convey these <filename>pccarddevs.h</filename>, used to convey these
identifiers to the client driver. The following steps identifiers to the client driver. The following steps must be
must be done before you can use them in the driver:</para> done before you can use them in the driver:</para>
<screen>&prompt.root; <userinput>cd src/sys/dev/pccard</userinput> <screen>&prompt.root; <userinput>cd src/sys/dev/pccard</userinput>
&prompt.root; <userinput>make -f Makefile.pccarddevs</userinput> &prompt.root; <userinput>make -f Makefile.pccarddevs</userinput></screen>
</screen>
<para>Once these steps are complete, you can add the card to the <para>Once these steps are complete, the card can be added to the
driver. That is a simple operation of adding one line:</para> driver. That is a simple operation of adding one line:</para>
<programlisting>static const struct pccard_product wi_pccard_products[] = { <programlisting>static const struct pccard_product wi_pccard_products[] = {
@ -334,31 +338,30 @@ product BUFFALO WLI_CF_S11G 0x030b BUFFALO AirStation 11Mbps CF WLAN</programlis
line before the line that I added, but that is simply to line before the line that I added, but that is simply to
highlight the line. Do not add it to the actual driver. Once highlight the line. Do not add it to the actual driver. Once
you have added the line, you can recompile your kernel or you have added the line, you can recompile your kernel or
module and try to see if it recognizes the device. If it does module and test it. If the device is recognized
and works, please submit a patch. If it does not work, please 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. 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 If the device is not recognized at all, you have done something
wrong and should recheck each step.</para> wrong and should recheck each step.</para>
<para>If you are a FreeBSD src committer, and everything appears <para>If you are a FreeBSD src committer, and everything appears
to be working, then you can commit the changes to the tree. to be working, then you can commit the changes to the tree.
However, there are some minor tricky things that you need to However, there are some minor tricky things to be considered.
worry about. First, you must commit the <filename>pccarddevs</filename> must be committed to the tree first.
<filename>pccarddevs</filename> file to the tree. After you Then <filename>pccarddevs.h</filename> must be regenerated
have done that, you must regenerate and committed as a second
<filename>pccarddevs.h</filename> and commit it as a second step, ensuring that the right
commit (this is to make sure that the right &dollar;FreeBSD&dollar; tag is in the latter file. Finally,
&dollar;FreeBSD&dollar; tag is in the latter file). Finally, commit the additions to the driver.</para>
you need to commit the additions to the driver.</para>
</sect2> </sect2>
<sect2 id="pccard-pr"> <sect2 id="pccard-pr">
<title>Submitting a new device</title> <title>Submitting a New Device</title>
<para>Many people send entries for new devices to the author <para>Please do not send entries for new devices to the author
directly. Please do not do this. Please submit them as a PR directly. Instead, submit them as a PR
and send the author the PR number for his records. This makes and send the author the PR number for his records. This
sure that entries are not lost. When submitting a PR, it is ensures that entries are not lost. When submitting a PR, it is
unnecessary to include the <filename>pccardevs.h</filename> unnecessary to include the <filename>pccardevs.h</filename>
diffs in the patch, since those will be regenerated. It is diffs in the patch, since those will be regenerated. It is
necessary to include a description of the device, as well as necessary to include a description of the device, as well as