summaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorTakashi Iwai <tiwai@suse.de>2014-01-29 12:51:12 +0100
committerTakashi Iwai <tiwai@suse.de>2014-02-12 10:58:20 +0100
commit393aa9c1cc514774332d7bc861307a76206e358d (patch)
treeb419a57e8af4b904247c0ffd3a7f0cc924bf2278 /Documentation
parent80d7d771ae839d6fc2286f443ad8445b6721a7f3 (diff)
downloadop-kernel-dev-393aa9c1cc514774332d7bc861307a76206e358d.zip
op-kernel-dev-393aa9c1cc514774332d7bc861307a76206e358d.tar.gz
ALSA: Mandate to pass a device pointer at card creation time
This is a part of preliminary works for modernizing the ALSA device structure. So far, we set card->dev at later point after the object creation. Because of this, the core layer doesn't always know which device is being handled before it's actually registered, and it makes impossible to show the device in error messages, for example. The first goal is to achieve a proper struct device initialization at the very beginning of probing. As a first step, this patch introduces snd_card_new() function (yes there was the same named function in the very past), in order to receive the parent device pointer from the very beginning. snd_card_create() is marked as deprecated. At this point, there is no functional change other than that. The actual change of the device creation scheme will follow later. Signed-off-by: Takashi Iwai <tiwai@suse.de>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/DocBook/writing-an-alsa-driver.tmpl72
1 files changed, 27 insertions, 45 deletions
diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl
index 06741e9..d0056a4 100644
--- a/Documentation/DocBook/writing-an-alsa-driver.tmpl
+++ b/Documentation/DocBook/writing-an-alsa-driver.tmpl
@@ -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);
]]>
</programlisting>
</informalexample>
@@ -809,28 +809,34 @@
<para>
As mentioned above, to create a card instance, call
- <function>snd_card_create()</function>.
+ <function>snd_card_new()</function>.
<informalexample>
<programlisting>
<![CDATA[
struct snd_card *card;
int err;
- err = snd_card_create(index, id, module, extra_size, &card);
+ err = snd_card_new(&pci->dev, index, id, module, extra_size, &card);
]]>
</programlisting>
</informalexample>
</para>
<para>
- 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
<constant>THIS_MODULE</constant>),
the size of extra-data space, and the pointer to return the
card instance. The extra_size argument is used to
allocate card-&gt;private_data for the
chip-specific data. Note that these data
- are allocated by <function>snd_card_create()</function>.
+ are allocated by <function>snd_card_new()</function>.
+ </para>
+
+ <para>
+ The first argument, the pointer of struct
+ <structname>device</structname>, specifies the parent device.
+ For PCI devices, typically &amp;pci-&gt; is passed there.
</para>
</section>
@@ -916,16 +922,16 @@
</para>
<section id="card-management-chip-specific-snd-card-new">
- <title>1. Allocating via <function>snd_card_create()</function>.</title>
+ <title>1. Allocating via <function>snd_card_new()</function>.</title>
<para>
As mentioned above, you can pass the extra-data-length
- to the 4th argument of <function>snd_card_create()</function>, i.e.
+ to the 5th argument of <function>snd_card_new()</function>, i.e.
<informalexample>
<programlisting>
<![CDATA[
- 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);
]]>
</programlisting>
</informalexample>
@@ -954,7 +960,7 @@
<para>
After allocating a card instance via
- <function>snd_card_create()</function> (with
+ <function>snd_card_new()</function> (with
<constant>0</constant> on the 4th arg), call
<function>kzalloc()</function>.
@@ -963,7 +969,8 @@
<![CDATA[
struct snd_card *card;
struct mychip *chip;
- 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);
]]>
@@ -1170,8 +1177,6 @@
return err;
}
- snd_card_set_dev(card, &pci->dev);
-
*rchip = chip;
return 0;
}
@@ -1526,30 +1531,6 @@
</section>
- <section id="pci-resource-device-struct">
- <title>Registration of Device Struct</title>
- <para>
- At some point, typically after calling <function>snd_device_new()</function>,
- you need to register the struct <structname>device</structname> of the chip
- you're handling for udev and co. ALSA provides a macro for compatibility with
- older kernels. Simply call like the following:
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_card_set_dev(card, &pci->dev);
-]]>
- </programlisting>
- </informalexample>
- 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.
- </para>
- <para>
- 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.)
- </para>
- </section>
-
<section id="pci-resource-entries">
<title>PCI Entries</title>
<para>
@@ -5740,7 +5721,8 @@ struct _snd_pcm_runtime {
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 +5734,7 @@ struct _snd_pcm_runtime {
</informalexample>
When you created the chip data with
- <function>snd_card_create()</function>, it's anyway accessible
+ <function>snd_card_new()</function>, it's anyway accessible
via <structfield>private_data</structfield> field.
<informalexample>
@@ -5766,8 +5748,8 @@ struct _snd_pcm_runtime {
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;
....
OpenPOWER on IntegriCloud