os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Whitespace-only changes. Wrap long lines, fix indentation.

Browse source
This commit is contained in:
Warren Block 2012-04-02 15:50:31 +00:00
parent 1c3a3f8502
commit 321bd374f5
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=38641
1 changed files with 70 additions and 69 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

139
en_US.ISO8859-1/books/arch-handbook/pccard/chapter.sgml
View file

@ -38,32 +38,32 @@
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>
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>
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
@ -108,7 +108,7 @@
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 PANASONIC 0x0032 Matsushita Electric Industrial Co.
vendor SANDISK 0x0045 Sandisk Corporation</programlisting>
@ -136,7 +136,7 @@ vendor SANDISK 0x0045 Sandisk Corporation</programlisting>
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
/* Archos */
@ -168,34 +168,34 @@ product ARCHOS ARC_ATAPI 0x0043 MiniCD</programlisting>
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>
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 }
<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>
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">
@ -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</programlisting>
<para>To add the device, we can just add this entry to <filename>pccarddevs</filename>:</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>
@ -322,8 +323,9 @@ product BUFFALO WLI_CF_S11G 0x030b BUFFALO AirStation 11Mbps CF WLAN</programlis
<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>
<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),
@ -338,38 +340,37 @@ product BUFFALO WLI_CF_S11G 0x030b BUFFALO AirStation 11Mbps CF WLAN</programlis
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>
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>
<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>
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>