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 d75f24a8bb..0cdfdefaed 100644 --- a/en_US.ISO8859-1/books/arch-handbook/pccard/chapter.sgml +++ b/en_US.ISO8859-1/books/arch-handbook/pccard/chapter.sgml @@ -1,369 +1,369 @@ PC Card This chapter will talk about the FreeBSD mechanisms for writing a device driver for a PC Card or CardBus device. However, at the present time, it just documents how to add a driver to an existing pccard driver. Adding a device The procedure for adding a new device to the list of supported pccard devices has changed from the system used through FreeBSD 4. In prior versions, editing a file in /etc to list the device was necessary. Starting in FreeBSD 5.0, devices drivers know what devices they support. There is now a table of supported devices in the kernel that drivers use to attach to a device. Overview PC Cards are identified in one of two ways, both based on information in the CIS of 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. There is a widespread practice of one company developing a reference design for a PC Card product and then selling 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. However, the refinements to the physical card typically are very minor, if any changes are made at all. Often, however, to strengthen their branding of their version of the card, these vendors will place their company name in the human strings in the CIS space, but leave the manufacturer and product ids unchanged. Because of the above practice, it is a smaller work load for FreeBSD to use the numeric IDs. It also introduces some minor complications into the process of adding IDs 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 from 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. Yet often, these devices will all have the same manufacturer and product id. The PC Card bus keeps its central database of card information, but not which driver is associated with them, in /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. 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 didn't need this method as a + 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 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. Format of <filename>pccarddevs</filename> There are four sections of the pccarddevs files. The first section lists the manufacturer numbers for those 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 isn't used (instead + 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 string matching method. Finally, C-style comments are allowed anywhere in the file. 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: vendor FUJITSU 0x0004 Fujitsu Corporation vendor NETGEAR_2 0x000b Netgear vendor PANASONIC 0x0032 Matsushita Electric Industrial Co. vendor SANDISK 0x0045 Sandisk Corporation shows the first few vendor ids. 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. - There's the vendor keyword used to denote the kind of line - that this is. There's the name of the vendor. This name will + 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's a numeric ID, in hex, for the + identifier. There is a numeric ID, in hex, for 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's a string + 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. The second section of the file contains the products. As you can see in the following example: /* Allied Telesis K.K. */ product ALLIEDTELESIS LA_PCM 0x0002 Allied Telesis LA-PCM /* Archos */ product ARCHOS ARC_ATAPI 0x0043 MiniCD the format is similar to the vendor lines. There is the 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's then the product id for this - card, in hex. As with the vendors, there's the same + 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 0xffffffff and - 0xffff. Finally, there's a string + 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. The third section is like the previous vendor section, but with all of the manufacturer numeric ids as -1. -1 means match anything you find 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. The final section contains the entries for those cards that we must match with string entries. This sections' format is a little different than the generic section: 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 We have the familiar product keyword, followed by the vendor name followed by the card name, just as in the second section of the file. However, then we deviate from that format. 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 entries mean that that part of the entry - should be ignored. In the example I've picked, there's a bad - entry. It shouldn't contain the version number in it unless - that's critical for the operation of the card. Sometimes + 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 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. Sample probe routine 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. static const struct pccard_product wi_pccard_products[] = { PCMCIA_CARD(3COM, 3CRWE737A, 0), PCMCIA_CARD(BUFFALO, WLI_PCM_S11, 0), PCMCIA_CARD(BUFFALO, WLI_CF_S11G, 0), PCMCIA_CARD(TDK, LAK_CD011WL, 0), { NULL } }; static int wi_pccard_probe(dev) device_t dev; { const struct pccard_product *pp; if ((pp = pccard_product_lookup(dev, wi_pccard_products, sizeof(wi_pccard_products[0]), NULL)) != NULL) { if (pp->pp_name != NULL) device_set_desc(dev, pp->pp_name); return (0); } return (ENXIO); } Here we have a simple pccard probe routine that matches a - few devices. As stated above, the name may vary (if it isn't + 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 if you have a different table, the first element of the structure you have a table of be a struct pccard_product. 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 pccarddevs. The bar part is the product. The baz is the expected function number that 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 the pccarddevs file. You may also see PCMCIA_CARD2 and PCMCIA_CARD2_D which are used when you need to match CIS both CIS strings and manufacturer numbers, in the use the default description and take the description from pccarddevs flavors. Putting it all together So, to add a new device, one must do the following steps. 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 devinfo - -v. You'll likely see something like: + -v. You will likely see something like: cbb1 pnpinfo vendor=0x104c device=0xac51 subvendor=0x1265 subdevice=0x0300 class=0x060700 at slot=10 function=1 cardbus1 pccard1 unknown pnpinfo manufacturer=0x026f product=0x030c cisvendor="BUFFALO" cisproduct="WLI2-CF-S11" function_type=6 at function=0 as part of the output. The manufacturer and product are the numeric IDs for this product. While the cisvendor and cisproduct are the strings that are present in the CIS that describe this product. 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: vendor BUFFALO 0x026f BUFFALO (Melco Corporation) - so we're good there. Looking for an entry for this card, + so we are good there. Looking for an entry for this card, we do not find one. Instead we find: /* BUFFALO */ product BUFFALO WLI_PCM_S11 0x0305 BUFFALO AirStation 11Mbps WLAN 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 we can just add product BUFFALO WLI2_CF_S11G 0x030c BUFFALO AirStation ultra 802.11b CF to pccarddevs. Presently, there is a manual step to regenerate the pccarddevs.h file used to convey these identifiers to the client driver. The following steps must be done before you can use them in the driver: &prompt.root; cd src/sys/dev/pccard &prompt.root; make -f Makefile.pccarddevs Once these steps are complete, you can add the card 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), PCMCIA_CARD(BUFFALO, WLI_PCM_S11, 0), PCMCIA_CARD(BUFFALO, WLI_CF_S11G, 0), + PCMCIA_CARD(BUFFALO, WLI_CF2_S11G, 0), PCMCIA_CARD(TDK, LAK_CD011WL, 0), { NULL } }; - Note that I've included a '+' in the + 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've added the line, you can recompile your kernel or module + 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 doesn't work, please + 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 didn't recognize it at all, you have done something + If it did not recognize it 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 that you need to worry about. First, you must commit the pccarddevs file to the tree. After you have done that, you must regenerate pccarddevs.h and commit it as a second commit (this is to make sure that the right $FreeBSD$ tag is in the latter file). Finally, you need to commit the additions to the driver. Submitting a new device 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 aren't lost. When submitting a PR, it is + sure 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 don't know the name, + 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. diff --git a/en_US.ISO8859-1/books/arch-handbook/sound/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/sound/chapter.sgml index 0a107812fa..9c211df637 100644 --- a/en_US.ISO8859-1/books/arch-handbook/sound/chapter.sgml +++ b/en_US.ISO8859-1/books/arch-handbook/sound/chapter.sgml @@ -1,690 +1,690 @@ Jean-Francois Dockes Contributed by Sound subsystem Introduction The FreeBSD sound subsystem cleanly separates generic sound handling issues from device-specific ones. This makes it easier to add support for new hardware. The &man.pcm.4; framework is the central piece of the sound subsystem. It mainly implements the following elements: A system call interface (read, write, ioctls) to digitized sound and mixer functions. The ioctl command set is compatible with the legacy OSS or Voxware interface, allowing common multimedia applications to be ported without modification. Common code for processing sound data (format conversions, virtual channels). A uniform software interface to hardware-specific audio interface modules. Additional support for some common hardware interfaces (ac97), or shared hardware-specific code (ex: ISA DMA routines). The support for specific sound cards is implemented by hardware-specific drivers, which provide channel and mixer interfaces to plug into the generic pcm code. In this chapter, the term pcm will refer to the central, common part of the sound driver, as opposed to the hardware-specific modules. The prospective driver writer will of course want to start from an existing module and use the code as the ultimate reference. But, while the sound code is nice and clean, it is also mostly devoid of comments. This document tries to give an overview of the framework interface and answer some questions that may arise while adapting the existing code. As an alternative, or in addition to starting from a working example, you can find a commented driver template at http://people.FreeBSD.org/~cg/template.c Files All the relevant code currently (FreeBSD 4.4) lives in /usr/src/sys/dev/sound/, except for the public ioctl interface definitions, found in /usr/src/sys/sys/soundcard.h Under /usr/src/sys/dev/sound/, the pcm/ directory holds the central code, while the isa/ and pci/ directories have the drivers for ISA and PCI boards. Probing, attaching, etc. Sound drivers probe and attach in almost the same way as any hardware driver module. You might want to look at the ISA or PCI specific sections of the handbook for more information. However, sound drivers differ in some ways: They declare themselves as pcm class devices, with a struct snddev_info device private structure: static driver_t xxx_driver = { "pcm", xxx_methods, sizeof(struct snddev_info) }; DRIVER_MODULE(snd_xxxpci, pci, xxx_driver, pcm_devclass, 0, 0); MODULE_DEPEND(snd_xxxpci, snd_pcm, PCM_MINVER, PCM_PREFVER,PCM_MAXVER); Most sound drivers need to store additional private information about their device. A private data structure is usually allocated in the attach routine. Its address is passed to pcm by the calls to pcm_register() and mixer_init(). pcm later passes back this address as a parameter in calls to the sound driver interfaces. The sound driver attach routine should declare its MIXER or AC97 interface to pcm by calling mixer_init(). For a MIXER interface, this causes in turn a call to xxxmixer_init(). The sound driver attach routine declares its general CHANNEL configuration to pcm by calling pcm_register(dev, sc, nplay, nrec), where sc is the address for the device data structure, used in further calls from pcm, and nplay and nrec are the number of play and record channels. The sound driver attach routine declares each of its channel objects by calls to pcm_addchan(). This sets up the channel glue in pcm and causes in turn a call to xxxchannel_init(). The sound driver detach routine should call pcm_unregister() before releasing its resources. There are two possible methods to handle non-PnP devices: Use a device_identify() method (example: sound/isa/es1888.c). The device_identify() method probes for the hardware at known addresses and, if it finds a supported device, creates a new pcm device which is then passed to probe/attach. Use a custom kernel configuration with appropriate hints for pcm devices (example: sound/isa/mss.c). pcm drivers should implement device_suspend, device_resume and device_shutdown routines, so that power management and module unloading function correctly. Interfaces The interface between the pcm core and the sound drivers is defined in terms of kernel objects. There are two main interfaces that a sound driver will usually provide: CHANNEL and either MIXER or AC97. The AC97 interface is a very small hardware access (register read/write) interface, implemented by drivers for hardware with an AC97 codec. In this case, the actual MIXER interface is provided by the shared AC97 code in pcm. The CHANNEL interface Common notes for function parameters Sound drivers usually have a private data structure to describe their device, and one structure for each play and record data channel that it supports. For all CHANNEL interface functions, the first parameter is an opaque pointer. The second parameter is a pointer to the private channel data structure, except for channel_init() which has a pointer to the private device structure (and returns the channel pointer for further use by pcm). Overview of data transfer operations For sound data transfers, the pcm core and the sound drivers communicate through a shared memory area, described by a struct snd_dbuf. struct snd_dbuf is private to pcm, and sound drivers obtain values of interest by calls to accessor functions (sndbuf_getxxx()). The shared memory area has a size of sndbuf_getsize() and is divided into fixed size blocks of sndbuf_getblksz() bytes. When playing, the general transfer mechanism is as follows (reverse the idea for recording): pcm initially fills up the buffer, then calls the sound driver's xxxchannel_trigger() function with a parameter of PCMTRIG_START. The sound driver then arranges to repeatedly transfer the whole memory area (sndbuf_getbuf(), sndbuf_getsize()) to the device, in blocks of sndbuf_getblksz() bytes. It calls back the chn_intr() pcm function for each transferred block (this will typically happen at interrupt time). chn_intr() arranges to copy new data to the area that was transferred to the device (now free), and make appropriate updates to the snd_dbuf structure. channel_init xxxchannel_init() is called to initialize each of the play or record channels. The calls are initiated from the sound driver attach routine. (See the probe and attach section). static void * xxxchannel_init(kobj_t obj, void *data, struct snd_dbuf *b, struct pcm_channel *c, int dir) { struct xxx_info *sc = data; struct xxx_chinfo *ch; ... return ch; } b is the address for the channel struct snd_dbuf. It should be initialized in the function by calling sndbuf_alloc(). The buffer size to use is normally a small multiple of the 'typical' unit transfer size for your device. c is the pcm channel control structure pointer. This is an opaque object. The function should store it in the local channel structure, to be used in later calls to pcm (ie: chn_intr(c)). dir indicates the channel direction (PCMDIR_PLAY or PCMDIR_REC). The function should return a pointer to the private area used to control this channel. This will be passed as a parameter to other channel interface calls. channel_setformat xxxchannel_setformat() should set up the hardware for the specified channel for the specified sound format. static int xxxchannel_setformat(kobj_t obj, void *data, u_int32_t format) { struct xxx_chinfo *ch = data; ... return 0; } format is specified as an AFMT_XXX value (soundcard.h). channel_setspeed xxxchannel_setspeed() sets up the channel hardware for the specified sampling speed, and returns the possibly adjusted speed. static int xxxchannel_setspeed(kobj_t obj, void *data, u_int32_t speed) { struct xxx_chinfo *ch = data; ... return speed; } channel_setblocksize xxxchannel_setblocksize() sets the block size, which is the size of unit transactions between pcm and the sound driver, and between the sound driver and the device. Typically, this would be the number of bytes transferred before an interrupt occurs. During a transfer, the sound driver should call pcm's chn_intr() every time this size has been transferred. Most sound drivers only take note of the block size here, to be used when an actual transfer will be started. static int xxxchannel_setblocksize(kobj_t obj, void *data, u_int32_t blocksize) { struct xxx_chinfo *ch = data; ... return blocksize; } The function returns the possibly adjusted block size. In case the block size is indeed changed, sndbuf_resize() should be called to adjust the buffer. channel_trigger xxxchannel_trigger() is called by pcm to control data transfer operations in the driver. static int xxxchannel_trigger(kobj_t obj, void *data, int go) { struct xxx_chinfo *ch = data; ... return 0; } go defines the action for the current call. The possible values are: PCMTRIG_START: the driver should start a data transfer from or to the channel buffer. If needed, the buffer base and size can be retrieved through sndbuf_getbuf() and sndbuf_getsize(). PCMTRIG_EMLDMAWR / PCMTRIG_EMLDMARD: this tells the driver that the input or output buffer may have been updated. Most drivers just ignore these calls. PCMTRIG_STOP / PCMTRIG_ABORT: the driver should stop the current transfer. If the driver uses ISA DMA, sndbuf_isadma() should be called before performing actions on the device, and will take care of the DMA chip side of things. channel_getptr xxxchannel_getptr() returns the current offset in the transfer buffer. This will typically be called by chn_intr(), and this is how pcm knows where it can transfer new data. channel_free xxxchannel_free() is called to free up channel resources, for example when the driver is unloaded, and should be implemented if the channel data structures are dynamically allocated or if sndbuf_alloc() was not used for buffer allocation. channel_getcaps struct pcmchan_caps * xxxchannel_getcaps(kobj_t obj, void *data) { return &xxx_caps; } The routine returns a pointer to a (usually statically-defined) pcmchan_caps structure (defined in sound/pcm/channel.h. The structure holds the minimum and maximum sampling frequencies, and the accepted sound formats. Look at any sound driver for an example. More functions channel_reset(), channel_resetdone(), and channel_notify() are for special purposes and should not be implemented in a driver without discussing it with the authorities (&a.cg;). channel_setdir() is deprecated. The MIXER interface mixer_init xxxmixer_init() initializes the hardware and tells pcm what mixer devices are available for playing and recording static int xxxmixer_init(struct snd_mixer *m) { struct xxx_info *sc = mix_getdevinfo(m); u_int32_t v; [Initialize hardware] [Set appropriate bits in v for play mixers] mix_setdevs(m, v); [Set appropriate bits in v for record mixers] mix_setrecdevs(m, v) return 0; } Set bits in an integer value and call mix_setdevs() and mix_setrecdevs() to tell pcm what devices exist. Mixer bits definitions can be found in soundcard.h (SOUND_MASK_XXX values and SOUND_MIXER_XXX bit shifts). mixer_set xxxmixer_set() sets the volume level for one mixer device. static int xxxmixer_set(struct snd_mixer *m, unsigned dev, unsigned left, unsigned right) { struct sc_info *sc = mix_getdevinfo(m); [set volume level] return left | (right << 8); } The device is specified as a SOUND_MIXER_XXX value The volume values are specified in range [0-100]. A value of zero should mute the device. - As the hardware levels probably won't match the + As the hardware levels probably will not match the input scale, and some rounding will occur, the routine returns the actual level values (in range 0-100) as shown. mixer_setrecsrc xxxmixer_setrecsrc() sets the recording source device. static int xxxmixer_setrecsrc(struct snd_mixer *m, u_int32_t src) { struct xxx_info *sc = mix_getdevinfo(m); [look for non zero bit(s) in src, set up hardware] [update src to reflect actual action] return src; } The desired recording devices are specified as a bit field The actual devices set for recording are returned. Some drivers can only set one device for recording. The function should return -1 if an error occurs. mixer_uninit, mixer_reinit xxxmixer_uninit() should ensure that all sound is muted and if possible mixer hardware should be powered down xxxmixer_reinit() should ensure that the mixer hardware is powered up and any settings not controlled by mixer_set() or mixer_setrecsrc() are restored. The AC97 interface The AC97 interface is implemented by drivers with an AC97 codec. It only has three methods: xxxac97_init() returns the number of ac97 codecs found. ac97_read() and ac97_write() read or write a specified register. The AC97 interface is used by the AC97 code in pcm to perform higher level operations. Look at sound/pci/maestro3.c or many others under sound/pci/ for an example.