Attachment #51155 for bug #77774

View | Details | Raw Unified | Return to bug 77774
Collapse All | Expand All




      <para>Finally, some really low end devices do not contain
        manufacturer identification at all.  These devices require
        that one matches them using 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
        that are quite popular.  This method should generally be
        avoided, but a number of devices are listed in this section

        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 those devices that use the

        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.
        There is the vendor keyword used to denote the kind of line
        that this is.  There is the name of the vendor.  This name will
        be repeated later in the pccarddevs file, as well as used in
        the driver's match tables, so keep it short and a valid C
        identifier.  There is a numeric ID, in hex, for the
        manufacturer.  Do not add IDs of the form
        <literal>0xffffffff</literal> or <literal>0xffff</literal>
        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.</para>

        product keyword.  Then there is 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.  There is then the product id for this
        card, in hex.  As with the vendors, there is 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

        strings are filtered by the program that generates
        <filename>pccarddevs.h</filename> to replace &amp;sp with a
        real space.  NULL entries mean that that part of the entry
        should be ignored.  In the example I have picked, there is a bad
        entry.  It should not contain the version number in it 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

}</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

        First, one must 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>.  You will likely see something like:</para>

<programlisting>        cbb1 pnpinfo vendor=0x104c device=0xac51 subvendor=0x1265 subdevice=0x0300 class=0x060700 at slot=10 function=1
          cardbus1


<programlisting>vendor BUFFALO			0x026f	BUFFALO (Melco Corporation)</programlisting>

      <para>so we are good there.  Looking for an entry for this card,
        we do not find one.  Instead we find:</para>

<programlisting>/* BUFFALO */

	{ 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 try to see if it recognizes the device.  If it does 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 it did not recognize it at all, you have done something
        wrong and should recheck each step.</para>

      <para>If you are a FreeBSD src committer, and everything appears

      <para>Many people send entries for new devices to the author
        directly.  Please do not do this.  Please submit them as a PR
        and send the author the PR number for his records.  This makes
        sure 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

Lines 594-600 Link Here

(-)sound/chapter.sgml (-1 / +1 lines)
594	</callout>	594	</callout>
595		595
596	<callout arearefs="co-mxset-return">	596	<callout arearefs="co-mxset-return">
597	<para>As the hardware levels probably won't match the	597	<para>As the hardware levels probably will not match the
598	input scale, and some rounding will occur, the routine	598	input scale, and some rounding will occur, the routine
599	returns the actual level values (in range 0-100) as	599	returns the actual level values (in range 0-100) as
600	shown.</para>	600	shown.</para>

Return to bug 77774

Lines 70-76 Link Here

(-)pccard/chapter.sgml (-21 / +21 lines)
70	<para>Finally, some really low end devices do not contain	70	<para>Finally, some really low end devices do not contain
71	manufacturer identification at all. These devices require	71	manufacturer identification at all. These devices require
72	that one matches them using the human readable CIS strings.	72	that one matches them using the human readable CIS strings.
73	While it would be nice if we didn't need this method as a	73	While it would be nice if we did not need this method as a
74	fallback, it is necessary for some very low end CD-ROM players	74	fallback, it is necessary for some very low end CD-ROM players
75	that are quite popular. This method should generally be	75	that are quite popular. This method should generally be
76	avoided, but a number of devices are listed in this section	76	avoided, but a number of devices are listed in this section
Lines 89-95 Link Here
89	them. This section is sorted in numerical order. The next	89	them. This section is sorted in numerical order. The next
90	section has all of the products that are used by these	90	section has all of the products that are used by these
91	vendors, along with their product ID numbers and a description	91	vendors, along with their product ID numbers and a description
92	string. The description string typically isn't used (instead	92	string. The description string typically is not used (instead
93	we set the device's description based on the human readable	93	we set the device's description based on the human readable
94	CIS, even if we match on the numeric version). These two	94	CIS, even if we match on the numeric version). These two
95	sections are then repeated for those devices that use the	95	sections are then repeated for those devices that use the
Lines 112-127 Link Here
112	that NETGEAR purchased cards from and the author of support	112	that NETGEAR purchased cards from and the author of support
113	for those cards was unaware at the time that Netgear was using	113	for those cards was unaware at the time that Netgear was using
114	someone else's id. These entries are fairly straightforward.	114	someone else's id. These entries are fairly straightforward.
115	There's the vendor keyword used to denote the kind of line	115	There is the vendor keyword used to denote the kind of line
116	that this is. There's the name of the vendor. This name will	116	that this is. There is the name of the vendor. This name will
117	be repeated later in the pccarddevs file, as well as used in	117	be repeated later in the pccarddevs file, as well as used in
118	the driver's match tables, so keep it short and a valid C	118	the driver's match tables, so keep it short and a valid C
119	identifier. There's a numeric ID, in hex, for the	119	identifier. There is a numeric ID, in hex, for the
120	manufacturer. Do not add IDs of the form	120	manufacturer. Do not add IDs of the form
121	<literal>0xffffffff</literal> or <literal>0xffff</literal>	121	<literal>0xffffffff</literal> or <literal>0xffff</literal>
122	because these are reserved ids (the former is 'no id set'	122	because these are reserved ids (the former is 'no id set'
123	while the latter is sometimes seen in extremely poor quality	123	while the latter is sometimes seen in extremely poor quality
124	cards to try to indicate 'none). Finally there's a string	124	cards to try to indicate 'none). Finally there is a string
125	description of the company that makes the card. This string	125	description of the company that makes the card. This string
126	is not used in FreeBSD for anything but commentary	126	is not used in FreeBSD for anything but commentary
127	purposes.</para>	127	purposes.</para>
Lines 139-148 Link Here
139	product keyword. Then there is the vendor name, repeated from	139	product keyword. Then there is the vendor name, repeated from
140	above. This is followed by the product name, which is used by	140	above. This is followed by the product name, which is used by
141	the driver and should be a valid C identifier, but may also	141	the driver and should be a valid C identifier, but may also
142	start with a number. There's then the product id for this	142	start with a number. There is then the product id for this
143	card, in hex. As with the vendors, there's the same	143	card, in hex. As with the vendors, there is the same
144	convention for <literal>0xffffffff</literal> and	144	convention for <literal>0xffffffff</literal> and
145	<literal>0xffff</literal>. Finally, there's a string	145	<literal>0xffff</literal>. Finally, there is a string
146	description of the device itself. This string typically is	146	description of the device itself. This string typically is
147	not used in FreeBSD, since FreeBSD's pccard bus driver will	147	not used in FreeBSD, since FreeBSD's pccard bus driver will
148	construct a string from the human readable CIS entries, but it	148	construct a string from the human readable CIS entries, but it
Lines 176-184 Link Here
176	strings are filtered by the program that generates	176	strings are filtered by the program that generates
177	<filename>pccarddevs.h</filename> to replace &sp with a	177	<filename>pccarddevs.h</filename> to replace &sp with a
178	real space. NULL entries mean that that part of the entry	178	real space. NULL entries mean that that part of the entry
179	should be ignored. In the example I've picked, there's a bad	179	should be ignored. In the example I have picked, there is a bad
180	entry. It shouldn't contain the version number in it unless	180	entry. It should not contain the version number in it unless
181	that's critical for the operation of the card. Sometimes	181	that is critical for the operation of the card. Sometimes
182	vendors will have many different versions of the card in the	182	vendors will have many different versions of the card in the
183	field that all work, in which case that information only makes	183	field that all work, in which case that information only makes
184	it harder for someone with a similar card to use it with	184	it harder for someone with a similar card to use it with
Lines 226-232 Link Here
226	}</programlisting>	226	}</programlisting>
227		227
228	<para>Here we have a simple pccard probe routine that matches a	228	<para>Here we have a simple pccard probe routine that matches a
229	few devices. As stated above, the name may vary (if it isn't	229	few devices. As stated above, the name may vary (if it is not
230	<function>foo_pccard_probe()</function> it will be	230	<function>foo_pccard_probe()</function> it will be
231	<function>foo_pccard_match()</function>). The function	231	<function>foo_pccard_match()</function>). The function
232	<function>pccard_product_lookup()</function> is a generalized	232	<function>pccard_product_lookup()</function> is a generalized
Lines 268-274 Link Here
268	First, one must obtain the identification information from the	268	First, one must obtain the identification information from the
269	device. The easiest way to do this is to insert the device	269	device. The easiest way to do this is to insert the device
270	into a PC Card or CF slot and issue <command>devinfo	270	into a PC Card or CF slot and issue <command>devinfo
271	-v</command>. You'll likely see something like:</para>	271	-v</command>. You will likely see something like:</para>
272		272
273	<programlisting> cbb1 pnpinfo vendor=0x104c device=0xac51 subvendor=0x1265 subdevice=0x0300 class=0x060700 at slot=10 function=1	273	<programlisting> cbb1 pnpinfo vendor=0x104c device=0xac51 subvendor=0x1265 subdevice=0x0300 class=0x060700 at slot=10 function=1
274	cardbus1	274	cardbus1
Lines 288-294 Link Here
288		288
289	<programlisting>vendor BUFFALO 0x026f BUFFALO (Melco Corporation)</programlisting>	289	<programlisting>vendor BUFFALO 0x026f BUFFALO (Melco Corporation)</programlisting>
290		290
291	<para>so we're good there. Looking for an entry for this card,	291	<para>so we are good there. Looking for an entry for this card,
292	we do not find one. Instead we find:</para>	292	we do not find one. Instead we find:</para>
293		293
294	<programlisting>/* BUFFALO */	294	<programlisting>/* BUFFALO */
Lines 323-336 Link Here
323	{ NULL }	323	{ NULL }
324	};</programlisting>	324	};</programlisting>
325		325
326	<para>Note that I've included a '<literal>+</literal>' in the	326	<para>Note that I have included a '<literal>+</literal>' in the
327	line before the line that I added, but that is simply to	327	line before the line that I added, but that is simply to
328	highlight the line. Do not add it to the actual driver. Once	328	highlight the line. Do not add it to the actual driver. Once
329	you've added the line, you can recompile your kernel or module	329	you have added the line, you can recompile your kernel or module
330	and try to see if it recognizes the device. If it does and	330	and try to see if it recognizes the device. If it does and
331	works, please submit a patch. If it doesn't work, please	331	works, please submit a patch. If it does not work, please
332	figure out what is needed to make it work and submit a patch.	332	figure out what is needed to make it work and submit a patch.
333	If it didn't recognize it at all, you have done something	333	If it did not recognize it at all, you have done something
334	wrong and should recheck each step.</para>	334	wrong and should recheck each step.</para>
335		335
336	<para>If you are a FreeBSD src committer, and everything appears	336	<para>If you are a FreeBSD src committer, and everything appears
Lines 352-362 Link Here
352	<para>Many people send entries for new devices to the author	352	<para>Many people send entries for new devices to the author
353	directly. Please do not do this. Please submit them as a PR	353	directly. Please do not do this. Please submit them as a PR
354	and send the author the PR number for his records. This makes	354	and send the author the PR number for his records. This makes
355	sure that entries aren't lost. When submitting a PR, it is	355	sure that entries are not lost. When submitting a PR, it is
356	unnecessary to include the <filename>pccardevs.h</filename>	356	unnecessary to include the <filename>pccardevs.h</filename>
357	diffs in the patch, since those will be regenerated. It is	357	diffs in the patch, since those will be regenerated. It is
358	necessary to include a description of the device, as well as	358	necessary to include a description of the device, as well as
359	the patches to the client driver. If you don't know the name,	359	the patches to the client driver. If you do not know the name,
360	use OEM99 as the name, and the author will adjust OEM99	360	use OEM99 as the name, and the author will adjust OEM99
361	accordingly after investigation. Committers should not commit	361	accordingly after investigation. Committers should not commit
362	OEM99, but instead find the highest OEM entry and commit one	362	OEM99, but instead find the highest OEM entry and commit one