--- zzzz-none-000/linux-3.10.107/Documentation/DocBook/writing-an-alsa-driver.tmpl 2017-06-27 09:49:32.000000000 +0000 +++ scorpion-7490-727/linux-3.10.107/Documentation/DocBook/writing-an-alsa-driver.tmpl 2021-02-04 17:41:59.000000000 +0000 @@ -468,8 +468,6 @@ return err; } - snd_card_set_dev(card, &pci->dev); - *rchip = chip; return 0; } @@ -492,7 +490,8 @@ } /* (2) */ - err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card); + err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, + 0, &card); if (err < 0) return err; @@ -591,7 +590,8 @@ struct snd_card *card; int err; .... - err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card); + err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, + 0, &card); ]]> @@ -809,28 +809,34 @@ As mentioned above, to create a card instance, call - snd_card_create(). + snd_card_new(). dev, index, id, module, extra_size, &card); ]]> - The function takes five arguments, the card-index number, the - id string, the module pointer (usually + The function takes six arguments: the parent device pointer, + the card-index number, the id string, the module pointer (usually THIS_MODULE), the size of extra-data space, and the pointer to return the card instance. The extra_size argument is used to allocate card->private_data for the chip-specific data. Note that these data - are allocated by snd_card_create(). + are allocated by snd_card_new(). + + + + The first argument, the pointer of struct + device, specifies the parent device. + For PCI devices, typically &pci-> is passed there. @@ -916,16 +922,16 @@
- 1. Allocating via <function>snd_card_create()</function>. + 1. Allocating via <function>snd_card_new()</function>. As mentioned above, you can pass the extra-data-length - to the 4th argument of snd_card_create(), i.e. + to the 5th argument of snd_card_new(), i.e. dev, index[dev], id[dev], THIS_MODULE, + sizeof(struct mychip), &card); ]]> @@ -954,7 +960,7 @@ After allocating a card instance via - snd_card_create() (with + snd_card_new() (with 0 on the 4th arg), call kzalloc(). @@ -963,7 +969,8 @@ dev, index[dev], id[dev], THIS_MODULE, + 0, &card); ..... chip = kzalloc(sizeof(*chip), GFP_KERNEL); ]]> @@ -1170,8 +1177,6 @@ return err; } - snd_card_set_dev(card, &pci->dev); - *rchip = chip; return 0; } @@ -1526,30 +1531,6 @@
-
- Registration of Device Struct - - At some point, typically after calling snd_device_new(), - you need to register the struct device of the chip - you're handling for udev and co. ALSA provides a macro for compatibility with - older kernels. Simply call like the following: - - -dev); -]]> - - - so that it stores the PCI's device pointer to the card. This will be - referred by ALSA core functions later when the devices are registered. - - - In the case of non-PCI, pass the proper device struct pointer of the BUS - instead. (In the case of legacy ISA without PnP, you don't have to do - anything.) - -
-
PCI Entries @@ -2200,10 +2181,6 @@ struct snd_pcm_hardware hw; struct snd_pcm_hw_constraints hw_constraints; - /* -- interrupt callbacks -- */ - void (*transfer_ack_begin)(struct snd_pcm_substream *substream); - void (*transfer_ack_end)(struct snd_pcm_substream *substream); - /* -- timer -- */ unsigned int timer_resolution; /* timer resolution */ @@ -2228,9 +2205,8 @@ For the operators (callbacks) of each sound driver, most of these records are supposed to be read-only. Only the PCM middle-layer changes / updates them. The exceptions are - the hardware description (hw), interrupt callbacks - (transfer_ack_xxx), DMA buffer information, and the private - data. Besides, if you use the standard buffer allocation + the hardware description (hw) DMA buffer information and the + private data. Besides, if you use the standard buffer allocation method via snd_pcm_lib_malloc_pages(), you don't need to set the DMA buffer information by yourself. @@ -2557,16 +2533,6 @@
-
- Interrupt Callbacks - - The field transfer_ack_begin and - transfer_ack_end are called at - the beginning and at the end of - snd_pcm_period_elapsed(), respectively. - -
-
@@ -2761,7 +2727,9 @@ Another note is that this callback is non-atomic - (schedulable). This is important, because the + (schedulable) as default, i.e. when no + nonatomic flag set. + This is important, because the trigger callback is atomic (non-schedulable). That is, mutexes or any schedule-related functions are not available in @@ -2919,8 +2887,9 @@ - As mentioned, this callback is atomic. You cannot call - functions which may sleep. + As mentioned, this callback is atomic as default unless + nonatomic flag set, and + you cannot call functions which may sleep. The trigger callback should be as minimal as possible, just really triggering the DMA. The other stuff should be initialized hw_params and prepare callbacks properly @@ -2955,7 +2924,7 @@ - This callback is also atomic. + This callback is also atomic as default.
@@ -2991,7 +2960,7 @@ is useful only for such a purpose. - This callback is atomic. + This callback is atomic as default. @@ -3194,6 +3163,21 @@ called with local interrupts disabled. + + The recent changes in PCM core code, however, allow all PCM + operations to be non-atomic. This assumes that the all caller + sides are in non-atomic contexts. For example, the function + snd_pcm_period_elapsed() is called + typically from the interrupt handler. But, if you set up the + driver to use a threaded interrupt handler, this call can be in + non-atomic context, too. In such a case, you can set + nonatomic filed of + snd_pcm object after creating it. + When this flag is set, mutex and rwsem are used internally in + the PCM core instead of spin and rwlocks, so that you can call + all PCM functions safely in a non-atomic context. + +
Constraints @@ -3659,6 +3643,29 @@ + The above callback can be simplified with a helper function, + snd_ctl_enum_info. The final code + looks like below. + (You can pass ARRAY_SIZE(texts) instead of 4 in the third + argument; it's a matter of taste.) + + + + + + + + + Some common info callbacks are available for your convenience: snd_ctl_boolean_mono_info() and snd_ctl_boolean_stereo_info(). @@ -5715,7 +5722,7 @@ suspending the PCM operations via snd_pcm_suspend_all() or snd_pcm_suspend(). It means that the PCM - streams are already stoppped when the register snapshot is + streams are already stopped when the register snapshot is taken. But, remember that you don't have to restart the PCM stream in the resume callback. It'll be restarted via trigger call with SNDRV_PCM_TRIGGER_RESUME @@ -5740,7 +5747,8 @@ struct mychip *chip; int err; .... - err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card); + err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, + 0, &card); .... chip = kzalloc(sizeof(*chip), GFP_KERNEL); .... @@ -5752,7 +5760,7 @@ When you created the chip data with - snd_card_create(), it's anyway accessible + snd_card_new(), it's anyway accessible via private_data field. @@ -5766,8 +5774,8 @@ struct mychip *chip; int err; .... - err = snd_card_create(index[dev], id[dev], THIS_MODULE, - sizeof(struct mychip), &card); + err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, + sizeof(struct mychip), &card); .... chip = card->private_data; ....