path: root/en_US.ISO8859-1/books/arch-handbook/pccard/chapter.sgml

<?xml version="1.0" encoding="ISO8859-1" standalone="no"?>
<!--
     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 present it just documents how to add a new device to an
    existing pccard driver.</para>

  <sect1 id="pccard-adddev">
    <title>Adding a Device</title>

    <para>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.</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
	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
	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>Original equipment manufacturers (<acronym>OEM</acronym>s)
	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.</para>

      <indexterm><primary>NetGear</primary></indexterm>
      <indexterm><primary>Linksys</primary></indexterm>
      <indexterm><primary>D-Link</primary></indexterm>

      <para>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.</para>

      <para>The PC Card bus code keeps a 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 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
	<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 in the
	<filename>pccarddevs</filename> 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
	<literal>/*</literal> and <literal>*/</literal> characters 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, here are the first few vendor
	IDs:</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>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.
	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 <filename>pccarddevs</filename>, 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
	<literal>0xffffffff</literal> or <literal>0xffff</literal>
	because these are reserved IDs (the former is
	<quote>no ID set</quote> while the latter is sometimes seen in
	extremely poor quality cards to try to indicate
	<quote>none</quote>).  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
	shown in this example, the format is similar to the vendor
	lines:</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
	<literal>product</literal> 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 <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 set to
	<literal>-1</literal>, meaning
	<quote>match anything found</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 must be identified by string entries.  This section's
	format 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 }
product ALLIEDTELESIS WR211PCM	{ "Allied&amp;spTelesis&amp;spK.K.", "WR211PCM", NULL, NULL } Allied Telesis WR211PCM</programlisting>

      <para>The familiar <literal>product</literal> 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 <filename>pccarddevs.h</filename> to replace &amp;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.</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-&gt;pp_name != NULL)
			device_set_desc(dev, pp-&gt;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 each row of the table
	must have a <function>struct</function>
	<structname>pccard_product</structname> as the first
	element.</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 ID.
	<replaceable>baz</replaceable> 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 <literal>PCMCIA_CARD_D</literal>, which
	includes the device description from
	<filename>pccarddevs</filename>.  You may also see
	<literal>PCMCIA_CARD2</literal> and
	<literal>PCMCIA_CARD2_D</literal> which are used when you need
	to match 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>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
	<command>devinfo -v</command>.  Sample output:</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><literal>manufacturer</literal>
	and <literal>product</literal> are the numeric IDs for this
	product, while <literal>cisvendor</literal> and
	<literal>cisproduct</literal> are the product description
	strings from the CIS.</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>But there is no entry for this particular card.
	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>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>

      <para>At present, there is a
	manual step to regenerate
	<filename>pccarddevs.h</filename>, 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, the card can be added 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 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.</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 to be considered.
	<filename>pccarddevs</filename> must be committed to the tree
	first.  Then <filename>pccarddevs.h</filename> must be
	regenerated and committed as a second step, ensuring that the
	right &dollar;FreeBSD&dollar; tag is in the latter file.
	Finally, commit the additions to the driver.</para>
    </sect2>

    <sect2 id="pccard-pr">
      <title>Submitting a New Device</title>

      <para>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 <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>