|author||Takashi Iwai <email@example.com>||2021-07-15 09:58:26 +0200|
|committer||Takashi Iwai <firstname.lastname@example.org>||2021-07-19 16:16:35 +0200|
ALSA: doc: Add device-managed resource section
Give brief explanations about the device-managed resources and the newly introduced snd_devm_card_new() helper. Link: https://email@example.com Signed-off-by: Takashi Iwai <firstname.lastname@example.org>
Diffstat (limited to 'Documentation/sound/kernel-api')
1 files changed, 33 insertions, 0 deletions
diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index 01d59b8aea92..255b7d3bebd6 100644
@@ -4172,6 +4172,39 @@ module license as GPL, etc., otherwise the system is shown as “tainted”.
+In the examples above, all resources are allocated and released
+manually. But human beings are lazy in nature, especially developers
+are lazier. So there are some ways to automate the release part; it's
+the (device-)managed resources aka devres or devm family. For
+example, an object allocated via :c:func:`devm_kmalloc()` will be
+freed automatically at unbinding the device.
+ALSA core provides also the device-managed helper, namely,
+:c:func:`snd_devm_card_new()` for creating a card object.
+Call this functions instead of the normal :c:func:`snd_card_new()`,
+and you can forget the explicit :c:func:`snd_card_free()` call, as
+it's called automagically at error and removal paths.
+One caveat is that the call of :c:func:`snd_card_free()` would be put
+at the beginning of the call chain only after you call
+Also, the ``private_free`` callback is always called at the card free,
+so be careful to put the hardware clean-up procedure in
+``private_free`` callback. It might be called even before you
+actually set up at an earlier error path. For avoiding such an
+invalid initialization, you can set ``private_free`` callback after
+:c:func:`snd_card_register()` call succeeds.
+Another thing to be remarked is that you should use device-managed
+helpers for each component as much as possible once when you manage
+the card in that way. Mixing up with the normal and the managed
+resources may screw up the release order.
How To Put Your Driver Into ALSA Tree