_index.po

# SOME DESCRIPTIVE TITLE
# Copyright (C) YEAR The FreeBSD Project
# This file is distributed under the same license as the FreeBSD Documentation package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 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 <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <[email protected]>\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 ""