# SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2025-05-01 19:56-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: Title = #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:1 #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:14 #, no-wrap msgid "PC Card" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:1 #, no-wrap msgid "Chapter 16. PC Card" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:52 msgid "" "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." msgstr "" #. type: Title == #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:54 #, no-wrap msgid "Adding a Device" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:57 msgid "" "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." msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:59 #, no-wrap msgid "Overview" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:62 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:64 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:66 msgid "" "Due to 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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:68 msgid "" "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#. It also provides a set of macros that allow one to easily " "construct simple entries in the table the driver uses to claim devices." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:70 msgid "" "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." msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:72 #, no-wrap msgid "Format of [.filename]#pccarddevs#" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:75 msgid "" "There are four sections in the [.filename]#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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:77 msgid "" "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:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:84 #, no-wrap msgid "" "vendor FUJITSU\t\t\t0x0004 Fujitsu Corporation\n" "vendor NETGEAR_2\t\t0x000b Netgear\n" "vendor PANASONIC\t\t0x0032\tMatsushita Electric Industrial Co.\n" "vendor SANDISK\t\t\t0x0045\tSandisk Corporation\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:87 msgid "" "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 [.filename]#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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:89 msgid "" "The second section of the file contains the products. As shown in this " "example, the format is similar to the vendor lines:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:94 #, no-wrap msgid "" "/* Allied Telesis K.K. */\n" "product ALLIEDTELESIS LA_PCM\t0x0002 Allied Telesis LA-PCM\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:97 #, no-wrap msgid "" "/* Archos */\n" "product\tARCHOS ARC_ATAPI\t0x0043 MiniCD\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:100 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:102 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:104 msgid "" "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:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:109 #, no-wrap msgid "" "product ADDTRON AWP100\t\t{ \"Addtron\", \"AWP-100&spWireless&spPCMCIA\", \"Version&sp01.02\", NULL }\n" "product ALLIEDTELESIS WR211PCM\t{ \"Allied&spTelesis&spK.K.\", \"WR211PCM\", NULL, NULL } Allied Telesis WR211PCM\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:112 msgid "" "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 [.filename]#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." msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:114 #, no-wrap msgid "Sample Probe Routine" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:117 msgid "" "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." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:127 #, no-wrap msgid "" "static const struct pccard_product wi_pccard_products[] = {\n" "\tPCMCIA_CARD(3COM, 3CRWE737A, 0),\n" "\tPCMCIA_CARD(BUFFALO, WLI_PCM_S11, 0),\n" "\tPCMCIA_CARD(BUFFALO, WLI_CF_S11G, 0),\n" "\tPCMCIA_CARD(TDK, LAK_CD011WL, 0),\n" "\t{ NULL }\n" "};\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:133 #, no-wrap msgid "" "static int\n" "wi_pccard_probe(dev)\n" "\tdevice_t\tdev;\n" "{\n" "\tconst struct pccard_product *pp;\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:142 #, no-wrap msgid "" "\tif ((pp = pccard_product_lookup(dev, wi_pccard_products,\n" "\t sizeof(wi_pccard_products[0]), NULL)) != NULL) {\n" "\t\tif (pp->pp_name != NULL)\n" "\t\t\tdevice_set_desc(dev, pp->pp_name);\n" "\t\treturn (0);\n" "\t}\n" "\treturn (ENXIO);\n" "}\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:145 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:147 msgid "" "Looking at the table `wi_pccard_products`, one notices that all the entries " "are of the form `PCMCIA_CARD(_foo_, _bar_, _baz_)`. The _foo_ part is the " "manufacturer ID from [.filename]#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 [.filename]#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." msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:149 #, no-wrap msgid "Putting it All Together" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:152 msgid "" "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:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:159 #, no-wrap msgid "" " cbb1 pnpinfo vendor=0x104c device=0xac51 subvendor=0x1265 subdevice=0x0300 class=0x060700 at slot=10 function=1\n" " cardbus1\n" " pccard1\n" " unknown pnpinfo manufacturer=0x026f product=0x030c cisvendor=\"BUFFALO\" cisproduct=\"WLI2-CF-S11\" function_type=6 at function=0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:162 msgid "" "`manufacturer` and `product` are the numeric IDs for this product, while " "`cisvendor` and `cisproduct` are the product description strings from the " "CIS." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:164 msgid "" "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:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:168 #, no-wrap msgid "vendor BUFFALO\t\t\t0x026f\tBUFFALO (Melco Corporation)\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:171 msgid "But there is no entry for this particular card. Instead we find:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:179 #, no-wrap msgid "" "/* BUFFALO */\n" "product BUFFALO WLI_PCM_S11\t0x0305\tBUFFALO AirStation 11Mbps WLAN\n" "product BUFFALO LPC_CF_CLT\t0x0307\tBUFFALO LPC-CF-CLT\n" "product\tBUFFALO\tLPC3_CLT\t0x030a\tBUFFALO LPC3-CLT Ethernet Adapter\n" "product BUFFALO WLI_CF_S11G\t0x030b\tBUFFALO AirStation 11Mbps CF WLAN\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:182 msgid "" "To add the device, we can just add this entry to [.filename]#pccarddevs#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:186 #, no-wrap msgid "product BUFFALO WLI2_CF_S11G\t0x030c\tBUFFALO AirStation ultra 802.11b CF\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:189 msgid "" "Once these steps are complete, the card can be added to the driver. That is " "a simple operation of adding one line:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:200 #, no-wrap msgid "" "static const struct pccard_product wi_pccard_products[] = {\n" "\tPCMCIA_CARD(3COM, 3CRWE737A, 0),\n" "\tPCMCIA_CARD(BUFFALO, WLI_PCM_S11, 0),\n" "\tPCMCIA_CARD(BUFFALO, WLI_CF_S11G, 0),\n" "+\tPCMCIA_CARD(BUFFALO, WLI_CF2_S11G, 0),\n" "\tPCMCIA_CARD(TDK, LAK_CD011WL, 0),\n" "\t{ NULL }\n" "};\n" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:203 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:205 msgid "" "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# must be committed to " "the tree first. Then [.filename]#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." msgstr "" #. type: Title === #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:207 #, no-wrap msgid "Submitting a New Device" msgstr "" #. type: Plain text #: documentation/content/en/books/arch-handbook/pccard/_index.adoc:209 msgid "" "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# 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." msgstr ""