diff --git a/en_US.ISO8859-1/books/arch-handbook/pccard/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/pccard/chapter.sgml index 842005c0f9..bb9bb9d3c6 100644 --- a/en_US.ISO8859-1/books/arch-handbook/pccard/chapter.sgml +++ b/en_US.ISO8859-1/books/arch-handbook/pccard/chapter.sgml @@ -38,32 +38,32 @@ driver. 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. + 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. NetGear Linksys D-Link 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. + 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. The PC Card bus code keeps a central database of card information, but not which driver is associated with them, in @@ -108,7 +108,7 @@ information. For example, here are the first few vendor IDs: -vendor FUJITSU 0x0004 Fujitsu Corporation + vendor FUJITSU 0x0004 Fujitsu Corporation vendor NETGEAR_2 0x000b Netgear vendor PANASONIC 0x0032 Matsushita Electric Industrial Co. vendor SANDISK 0x0045 Sandisk Corporation @@ -136,7 +136,7 @@ vendor SANDISK 0x0045 Sandisk Corporation shown in this example, the format is similar to the vendor lines: -/* Allied Telesis K.K. */ + /* Allied Telesis K.K. */ product ALLIEDTELESIS LA_PCM 0x0002 Allied Telesis LA-PCM /* Archos */ @@ -168,34 +168,34 @@ product ARCHOS ARC_ATAPI 0x0043 MiniCD section of the file. 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: + that must be identified by string entries. This section's + format is a little different from the generic section: -product ADDTRON AWP100 { "Addtron", "AWP-100&spWireless&spPCMCIA", "Version&sp01.02", NULL } + 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 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 - 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. + 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 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. @@ -309,7 +309,8 @@ 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 - To add the device, we can just add this entry to pccarddevs: + To add the device, we can just add this entry to + pccarddevs: product BUFFALO WLI2_CF_S11G 0x030c BUFFALO AirStation ultra 802.11b CF @@ -322,8 +323,9 @@ product BUFFALO WLI_CF_S11G 0x030b BUFFALO AirStation 11Mbps CF WLAN&prompt.root; cd src/sys/dev/pccard &prompt.root; make -f Makefile.pccarddevs - Once these steps are complete, the card can be added to the - driver. That is a simple operation of adding one line: + Once these steps are complete, the card can be added to + the driver. That is a simple operation of adding one + line: static const struct pccard_product wi_pccard_products[] = { PCMCIA_CARD(3COM, 3CRWE737A, 0), @@ -338,38 +340,37 @@ product BUFFALO WLI_CF_S11G 0x030b BUFFALO AirStation 11Mbps CF WLAN + 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. 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. - pccarddevs must be committed to the tree first. - Then 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. + pccarddevs must be committed to the tree + first. Then 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. Submitting a New Device 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 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. + 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 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.