August 2020 - Alsa-devel - mailman.alsa-project.org

HDA-Intel: HiFi-dual: Fix the Rear Mic's Jack name
by GitHub pull_request - opened 17 Aug '20

17 Aug '20

alsa-project/alsa-ucm-conf pull request #46 was opened from jason77-wang: On the LENOVO P520 (dual codecs machine), the Jack name of Rear Mic is "Rear Mic Jack" instead of "Mic Jack". Below is picked from alsa-info.txt on the LENOVO p520 machine: control.18 { iface CARD name 'Rear Mic Jack' value true comment { access read type BOOLEAN count 1 } } Signed-off-by: Hui Wang <hui.wang(a)canonical.com> Request URL : https://github.com/alsa-project/alsa-ucm-conf/pull/46 Patch URL : https://github.com/alsa-project/alsa-ucm-conf/pull/46.patch Repository URL: https://github.com/alsa-project/alsa-ucm-conf

1 0

[PATCH v2] soundwire: SDCA: detect sdca_cascade interrupt
by Bard Liao 16 Aug '20

16 Aug '20

From: Pierre-Louis Bossart <pierre-louis.bossart(a)linux.intel.com> The SoundWire 1.2 specification defines an "SDCA cascade" bit which handles a logical OR of all SDCA interrupt sources (up to 30 defined). Due to limitations of the addressing space, this bit is located in the SDW_DP0_INT register when DP0 is used, or alternatively in the DP0_SDCA_Support_INTSTAT register when DP0 is not used. To allow for both cases to be handled, this bit will be checked in the main device-level interrupt handling code. This will result in the register being read twice if DP0 is enabled, but it's not clear how to optimize this case. It's also more logical to deal with this interrupt at the device than the port level, this bit is really not DP0 specific and its location in the DP0_INTSTAT bit is only due to the lack of free space in SCP_INTSTAT_1. The SDCA_Cascade bit cannot be masked or cleared, so the interrupt handling only forwards the detection to the Slave driver, which will deal with reading the relevant SDCA status bits and clearing them. The bus driver only signals the detection. The communication with the Slave driver is based on the same interrupt callback, with only an extension to provide the status of the sdca_cascade bit. Signed-off-by: Pierre-Louis Bossart <pierre-louis.bossart(a)linux.intel.com> Reviewed-by: Rander Wang <rander.wang(a)linux.intel.com> Reviewed-by: Guennadi Liakhovetski <guennadi.liakhovetski(a)linux.intel.com> Signed-off-by: Bard Liao <yung-chuan.liao(a)linux.intel.com> --- Changelog: v2: - Re-read SDW_DP0_INT while reading status again. --- drivers/soundwire/bus.c | 28 +++++++++++++++++++++++++++- include/linux/soundwire/sdw.h | 4 ++++ 2 files changed, 31 insertions(+), 1 deletion(-) diff --git a/drivers/soundwire/bus.c b/drivers/soundwire/bus.c index e6e0fb9a81b4..d254c23201b9 100644 --- a/drivers/soundwire/bus.c +++ b/drivers/soundwire/bus.c @@ -1361,6 +1361,7 @@ static int sdw_handle_slave_alerts(struct sdw_slave *slave) int port_num, stat, ret, count = 0; unsigned long port; bool slave_notify = false; + u8 sdca_cascade = 0; u8 buf, buf2[2], _buf, _buf2[2]; sdw_modify_slave_status(slave, SDW_SLAVE_ALERT); @@ -1388,6 +1389,16 @@ static int sdw_handle_slave_alerts(struct sdw_slave *slave) goto io_err; } + if (slave->prop.is_sdca) { + ret = sdw_read(slave, SDW_DP0_INT); + if (ret < 0) { + dev_err(slave->bus->dev, + "SDW_DP0_INT read failed:%d\n", ret); + goto io_err; + } + sdca_cascade = ret & SDW_DP0_SDCA_CASCADE; + } + do { /* * Check parity, bus clash and Slave (impl defined) @@ -1416,6 +1427,10 @@ static int sdw_handle_slave_alerts(struct sdw_slave *slave) slave_notify = true; } + /* the SDCA interrupts are cleared in the codec driver .interrupt_callback() */ + if (sdca_cascade) + slave_notify = true; + /* Check port 0 - 3 interrupts */ port = buf & SDW_SCP_INT1_PORT0_3; @@ -1453,6 +1468,7 @@ static int sdw_handle_slave_alerts(struct sdw_slave *slave) /* Update the Slave driver */ if (slave_notify && slave->ops && slave->ops->interrupt_callback) { + slave_intr.sdca_cascade = sdca_cascade; slave_intr.control_port = clear; memcpy(slave_intr.port, &port_status, sizeof(slave_intr.port)); @@ -1487,11 +1503,21 @@ static int sdw_handle_slave_alerts(struct sdw_slave *slave) goto io_err; } + if (slave->prop.is_sdca) { + ret = sdw_read(slave, SDW_DP0_INT); + if (ret < 0) { + dev_err(slave->bus->dev, + "SDW_DP0_INT read failed:%d\n", ret); + goto io_err; + } + sdca_cascade = ret & SDW_DP0_SDCA_CASCADE; + } + /* Make sure no interrupts are pending */ buf &= _buf; buf2[0] &= _buf2[0]; buf2[1] &= _buf2[1]; - stat = buf || buf2[0] || buf2[1]; + stat = buf || buf2[0] || buf2[1] || sdca_cascade; /* * Exit loop if Slave is continuously in ALERT state even diff --git a/include/linux/soundwire/sdw.h b/include/linux/soundwire/sdw.h index 76052f12c9f7..a51494646a2c 100644 --- a/include/linux/soundwire/sdw.h +++ b/include/linux/soundwire/sdw.h @@ -355,6 +355,7 @@ struct sdw_dpn_prop { * @dp0_prop: Data Port 0 properties * @src_dpn_prop: Source Data Port N properties * @sink_dpn_prop: Sink Data Port N properties + * @is_sdca: the Slave supports the SDCA specification */ struct sdw_slave_prop { u32 mipi_revision; @@ -376,6 +377,7 @@ struct sdw_slave_prop { struct sdw_dp0_prop *dp0_prop; struct sdw_dpn_prop *src_dpn_prop; struct sdw_dpn_prop *sink_dpn_prop; + bool is_sdca; }; /** @@ -465,10 +467,12 @@ struct sdw_slave_id { /** * struct sdw_slave_intr_status - Slave interrupt status + * @sdca_cascade: set if the Slave device reports an SDCA interrupt * @control_port: control port status * @port: data port status */ struct sdw_slave_intr_status { + bool sdca_cascade; u8 control_port; u8 port[15]; }; -- 2.17.1

1 0

Re: [PATCH] dt-bindings: Whitespace clean-ups in schema files
by Sam Ravnborg 16 Aug '20

16 Aug '20

Hi Rob. On Wed, Aug 12, 2020 at 02:36:18PM -0600, Rob Herring wrote: > Clean-up incorrect indentation, extra spaces, long lines, and missing > EOF newline in schema files. Most of the clean-ups are for list > indentation which should always be 2 spaces more than the preceding > keyword. > > Found with yamllint (which I plan to integrate into the checks). I have browsed through the patch - and there was only a few things that jumped at me. With these points considered: Acked-by: Sam Ravnborg <sam(a)ravnborg.org> I expect only some (few) of my points to actually results in any updates. I look forward to have the lint functionality as part of the built-in tools so we catch these things early. Sam > diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml > index f63895c8ce2d..88814a2a14a5 100644 > --- a/Documentation/devicetree/bindings/arm/fsl.yaml > +++ b/Documentation/devicetree/bindings/arm/fsl.yaml > @@ -273,8 +273,8 @@ properties: > - fsl,imx6ull-14x14-evk # i.MX6 UltraLiteLite 14x14 EVK Board > - kontron,imx6ull-n6411-som # Kontron N6411 SOM > - myir,imx6ull-mys-6ulx-eval # MYiR Tech iMX6ULL Evaluation Board > - - toradex,colibri-imx6ull-eval # Colibri iMX6ULL Module on Colibri Evaluation Board > - - toradex,colibri-imx6ull-wifi-eval # Colibri iMX6ULL Wi-Fi / Bluetooth Module on Colibri Evaluation Board > + - toradex,colibri-imx6ull-eval # Colibri iMX6ULL Module on Colibri Eval Board > + - toradex,colibri-imx6ull-wifi-eval # Colibri iMX6ULL Wi-Fi / BT Module on Colibri Eval Board > - const: fsl,imx6ull This change looks bad as it drops the alignment with the comments below. See following patch chunck: > > - description: Kontron N6411 S Board > @@ -312,9 +312,12 @@ properties: > - toradex,colibri-imx7d # Colibri iMX7 Dual Module > - toradex,colibri-imx7d-aster # Colibri iMX7 Dual Module on Aster Carrier Board > - toradex,colibri-imx7d-emmc # Colibri iMX7 Dual 1GB (eMMC) Module > - - toradex,colibri-imx7d-emmc-aster # Colibri iMX7 Dual 1GB (eMMC) Module on Aster Carrier Board > - - toradex,colibri-imx7d-emmc-eval-v3 # Colibri iMX7 Dual 1GB (eMMC) Module on Colibri Evaluation Board V3 > - - toradex,colibri-imx7d-eval-v3 # Colibri iMX7 Dual Module on Colibri Evaluation Board V3 > + - toradex,colibri-imx7d-emmc-aster # Colibri iMX7 Dual 1GB (eMMC) Module on > + # Aster Carrier Board > diff --git a/Documentation/devicetree/bindings/display/panel/ilitek,ili9322.yaml b/Documentation/devicetree/bindings/display/panel/ilitek,ili9322.yaml > index 177d48c5bd97..e89c1ea62ffa 100644 > --- a/Documentation/devicetree/bindings/display/panel/ilitek,ili9322.yaml > +++ b/Documentation/devicetree/bindings/display/panel/ilitek,ili9322.yaml > @@ -25,8 +25,7 @@ properties: > compatible: > items: > - enum: > - - dlink,dir-685-panel > - > + - dlink,dir-685-panel > - const: ilitek,ili9322 > > reset-gpios: true > diff --git a/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml b/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml > index a39332276bab..76a9068a85dd 100644 > --- a/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml > +++ b/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml > @@ -13,8 +13,7 @@ properties: > compatible: > items: > - enum: > - - bananapi,lhr050h41 > - > + - bananapi,lhr050h41 > - const: ilitek,ili9881c > The extra lines is a simple way to indicate that here shall be added more in the future. So I like the empty line. > diff --git a/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml b/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml > index 32e0896c6bc1..47938e372987 100644 > --- a/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml > +++ b/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml > @@ -79,7 +79,8 @@ properties: > description: | > kHz; switching frequency. > $ref: /schemas/types.yaml#/definitions/uint32 > - enum: [ 600, 640, 685, 738, 800, 872, 960, 1066, 1200, 1371, 1600, 1920, 2400, 3200, 4800, 9600 ] > + enum: [ 600, 640, 685, 738, 800, 872, 960, 1066, 1200, 1371, 1600, 1920, > + 2400, 3200, 4800, 9600 ] > > qcom,ovp: > description: | In the modern world we are living in now line length of 100 chars are OK. checkpatch and coding_style is updated to reflected this. > diff --git a/Documentation/devicetree/bindings/spi/mikrotik,rb4xx-spi.yaml b/Documentation/devicetree/bindings/spi/mikrotik,rb4xx-spi.yaml > index 4ddb42a4ae05..9102feae90a2 100644 > --- a/Documentation/devicetree/bindings/spi/mikrotik,rb4xx-spi.yaml > +++ b/Documentation/devicetree/bindings/spi/mikrotik,rb4xx-spi.yaml > @@ -33,4 +33,5 @@ examples: > reg = <0x1f000000 0x10>; > }; > > -... > \ No newline at end of file > +... > + Added one line too much? diff --git a/Documentation/devicetree/bindings/spi/spi-mux.yaml b/Documentation/devicetree/bindings/spi/spi-mux.yaml > index 0ae692dc28b5..3d3fed63409b 100644 > --- a/Documentation/devicetree/bindings/spi/spi-mux.yaml > +++ b/Documentation/devicetree/bindings/spi/spi-mux.yaml > @@ -43,47 +43,47 @@ properties: > maxItems: 1 > > required: > - - compatible > - - reg > - - spi-max-frequency > - - mux-controls > + - compatible > + - reg > + - spi-max-frequency > + - mux-controls > > examples: > - - | > - #include <dt-bindings/gpio/gpio.h> > - mux: mux-controller { > - compatible = "gpio-mux"; > - #mux-control-cells = <0>; > + - | > + #include <dt-bindings/gpio/gpio.h> > + mux: mux-controller { > + compatible = "gpio-mux"; > + #mux-control-cells = <0>; > > - mux-gpios = <&gpio0 3 GPIO_ACTIVE_HIGH>; > - }; > + mux-gpios = <&gpio0 3 GPIO_ACTIVE_HIGH>; > + }; Example is updated to use 4-space indent. I like. But many other examples are left untouched. So I wonder if updating all examples to the same indent should be left for another mega-patch? > diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml > index f3d847832fdc..2baee2c817c1 100644 > --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml > +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml > @@ -993,7 +993,8 @@ patternProperties: > "^sst,.*": > description: Silicon Storage Technology, Inc. > "^sstar,.*": > - description: Xiamen Xingchen(SigmaStar) Technology Co., Ltd. (formerly part of MStar Semiconductor, Inc.) > + description: Xiamen Xingchen(SigmaStar) Technology Co., Ltd. > + (formerly part of MStar Semiconductor, Inc.) > "^st,.*": > description: STMicroelectronics > "^starry,.*": Did you check that they are all in alphabetical order? I would be suprised if this is the only issue in this file.

3 2

[PATCH] sound/isa:fix spelling mistakes in the comments
by Liang Wang 16 Aug '20

16 Aug '20

Fix spelling mistakes in the comments: initailise ==> initialise tranfer ==> transfer Initialse ==> Initialise Signed-off-by: Liang Wang <wangliang101(a)huawei.com> --- sound/isa/sscape.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sound/isa/sscape.c b/sound/isa/sscape.c index 5363d88cc4b9..2e5a5c5279e8 100644 --- a/sound/isa/sscape.c +++ b/sound/isa/sscape.c @@ -308,7 +308,7 @@ static inline int verify_mpu401(const struct snd_mpu401 *mpu) } /* - * This is apparently the standard way to initailise an MPU-401 + * This is apparently the standard way to initialise an MPU-401 */ static inline void initialise_mpu401(const struct snd_mpu401 *mpu) { @@ -339,7 +339,7 @@ static void soundscape_free(struct snd_card *c) } /* - * Tell the SoundScape to begin a DMA tranfer using the given channel. + * Tell the SoundScape to begin a DMA transfer using the given channel. * All locking issues are left to the caller. */ static void sscape_start_dma_unsafe(unsigned io_base, enum GA_REG reg) @@ -803,7 +803,7 @@ static int mpu401_open(struct snd_mpu401 *mpu) } /* - * Initialse an MPU-401 subdevice for MIDI support on the SoundScape. + * Initialise an MPU-401 subdevice for MIDI support on the SoundScape. */ static int create_mpu401(struct snd_card *card, int devnum, unsigned long port, int irq) -- 2.27.0

2 1

[PATCH v2 alsa-lib] README: add patch submission instructions
by Tanu Kaskinen 16 Aug '20

16 Aug '20

Signed-off-by: Tanu Kaskinen <tanuk(a)iki.fi> --- v2: - fixed Markdown syntax: changed ' to ` - added Signed-off-by README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 3cd122d5..56af78d0 100644 --- a/README.md +++ b/README.md @@ -12,3 +12,14 @@ http://www.alsa-project.org/alsa-doc/alsa-lib/ You may give a look for more information about the ALSA project to URL http://www.alsa-project.org. + +### Submitting patches + +The preferred way to submit patches is by sending them by email to the +alsa-devel mailing list. Sending mail to the list requires subscription, +subscribe here: https://mailman.alsa-project.org/mailman/listinfo/alsa-devel + +Add Takashi Iwai `<tiwai(a)suse.de>` and/or Jaroslav Kysela `<perex(a)perex.cz>` to +Cc so that your patch won't be missed. + +Patches are also accepted as GitHub pull requests. -- 2.20.1

2 1

[PATCH v3 0/2] Add mediatek codec mt6359 driver
by Jiaxin Yu 15 Aug '20

15 Aug '20

Add mediatek codec (MT6359) driver MT6359 support playback and capture feature. On downlink path, it includes three DACs for handset, headset, and lineout path. On unlink path, it includeds three ADCs for main mic, second mic, 3rd mic, and headset mic. By scenario, select *_MUX widget to create damp path. And by select mic_type_mux to choose DMIC/AMIC/.... For example, select these MUX widget to create headset path (1) DAC In Mux --> "Normal Path" (2) HPL Mux --> "Audio Playback" (3) HPR Mux --> "Audio Playback" v3 changes: 1. Remove calibration related functions. 2. Conbined 'HPL Mux' and 'HPR Mux' to 'HP Mux'. 3. Move the regulator_enable of 'vaud18' to the component probe. 4. Fix some incorrect coding style. v2 changes: 1. patchwork link: https://patchwork.kernel.org/cover/11706935/ https://patchwork.kernel.org/patch/11708865/ https://patchwork.kernel.org/patch/11706937/ v1 changes: 1.lkml link: https://lkml.org/lkml/2020/3/5/1257 Jiaxin Yu (2): WIP: ASoC: mediatek: mt6359: add codec driver WIP: dt-bindings: mediatek: mt6359: add codec document .../devicetree/bindings/sound/mt6359.yaml | 68 + sound/soc/codecs/Kconfig | 8 + sound/soc/codecs/Makefile | 2 + sound/soc/codecs/mt6359.c | 2737 +++++++++++++++++ sound/soc/codecs/mt6359.h | 2640 ++++++++++++++++ 5 files changed, 5455 insertions(+) create mode 100644 Documentation/devicetree/bindings/sound/mt6359.yaml create mode 100644 sound/soc/codecs/mt6359.c create mode 100644 sound/soc/codecs/mt6359.h -- 2.18.0

3 5

[PATCH alsa-lib] README: add patch submission instructions
by Tanu Kaskinen 15 Aug '20

15 Aug '20

--- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 3cd122d5..57fd353e 100644 --- a/README.md +++ b/README.md @@ -12,3 +12,14 @@ http://www.alsa-project.org/alsa-doc/alsa-lib/ You may give a look for more information about the ALSA project to URL http://www.alsa-project.org. + +### Submitting patches + +The preferred way to submit patches is by sending them by email to the +alsa-devel mailing list. Sending mail to the list requires subscription, +subscribe here: https://mailman.alsa-project.org/mailman/listinfo/alsa-devel + +Add Takashi Iwai `<tiwai(a)suse.de>` and/or Jaroslav Kysela `<perex(a)perex.cz>' to +Cc so that your patch won't be missed. + +Patches are also accepted as GitHub pull requests. -- 2.20.1

1 0

How to send in patches?
by Tanjeff Moos 15 Aug '20

15 Aug '20

Hi folks, I'd like to send in my first patch for alsa-lib. Is it okay if I simply send it to this list? Or is there a process how to do this? Kind regards, Tanjeff

2 1

[PATCH] ALSA: usb-audio: Add capture support for Saffire 6 (USB 1.1)
by Alexander Tsoy 15 Aug '20

15 Aug '20

Capture and playback endpoints on Saffire 6 (USB 1.1) resides on the same interface. This was not supported by the composite quirk back in the day when initial support for this device was added, thus only playback was enabled until now. Signed-off-by: Alexander Tsoy <alexander(a)tsoy.me> --- sound/usb/quirks-table.h | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/sound/usb/quirks-table.h b/sound/usb/quirks-table.h index d79e3ddc5690..e6202608e043 100644 --- a/sound/usb/quirks-table.h +++ b/sound/usb/quirks-table.h @@ -2673,28 +2673,58 @@ YAMAHA_DEVICE(0x7010, "UB99"), { USB_DEVICE(0x1235, 0x0010), .driver_info = (unsigned long) &(const struct snd_usb_audio_quirk) { .vendor_name = "Focusrite", .product_name = "Saffire 6 USB", .ifnum = QUIRK_ANY_INTERFACE, .type = QUIRK_COMPOSITE, .data = (const struct snd_usb_audio_quirk[]) { + { + .ifnum = 0, + .type = QUIRK_AUDIO_STANDARD_MIXER, + }, { .ifnum = 0, .type = QUIRK_AUDIO_FIXED_ENDPOINT, .data = &(const struct audioformat) { .formats = SNDRV_PCM_FMTBIT_S24_3LE, .channels = 4, .iface = 0, .altsetting = 1, .altset_idx = 1, .attributes = UAC_EP_CS_ATTR_SAMPLE_RATE, .endpoint = 0x01, .ep_attr = USB_ENDPOINT_XFER_ISOC, + .datainterval = 1, + .maxpacksize = 0x024c, + .rates = SNDRV_PCM_RATE_44100 | + SNDRV_PCM_RATE_48000, + .rate_min = 44100, + .rate_max = 48000, + .nr_rates = 2, + .rate_table = (unsigned int[]) { + 44100, 48000 + } + } + }, + { + .ifnum = 0, + .type = QUIRK_AUDIO_FIXED_ENDPOINT, + .data = &(const struct audioformat) { + .formats = SNDRV_PCM_FMTBIT_S24_3LE, + .channels = 2, + .iface = 0, + .altsetting = 1, + .altset_idx = 1, + .attributes = 0, + .endpoint = 0x82, + .ep_attr = USB_ENDPOINT_XFER_ISOC, + .datainterval = 1, + .maxpacksize = 0x0126, .rates = SNDRV_PCM_RATE_44100 | SNDRV_PCM_RATE_48000, .rate_min = 44100, .rate_max = 48000, .nr_rates = 2, .rate_table = (unsigned int[]) { 44100, 48000 } -- 2.26.2

2 1

[PATCH] Add documentation for snd_ctl_elem_list_*
by Tanjeff Moos 15 Aug '20

15 Aug '20

I added doxygen documentation to alsa-lib. The patch was created using git format-patch. This is my first patch. Please let me know if I need to improve it. >From 731895b67fcae743551989a5dd04382003e66560 Mon Sep 17 00:00:00 2001 From: "Tanjeff-N. Moos" <tanjeff(a)cccmz.de> Date: Fri, 14 Aug 2020 08:40:28 +0200 Subject: [PATCH] Add documentation for snd_ctl_elem_list_*. --- include/control.h | 81 +++++++++++++++++++++++++++++++++++++++++-- src/control/control.c | 80 ++++++++++++++++++++++++++++++++++++------ 2 files changed, 148 insertions(+), 13 deletions(-) diff --git a/include/control.h b/include/control.h index 02db72d4..9deec6f3 100644 --- a/include/control.h +++ b/include/control.h @@ -56,7 +56,75 @@ typedef struct _snd_ctl_card_info snd_ctl_card_info_t; /** CTL element identifier container */ typedef struct _snd_ctl_elem_id snd_ctl_elem_id_t; -/** CTL element identifier list container */ +/** CTL element list container + * + * This is a list of CTL elements. The list contains management + * information (e.g. how many elements the sound card has) as well as + * the element identifiers. All functions which operate on the list + * are named snd_ctl_elem_list_*(). + * + * \par Memory management + * + * There are two memory areas to deal with: The list container itself + * and the memory for the element identifiers. + * + * To manage the area for the list container, the following functions + * are used: + * + * - snd_ctl_elem_list_malloc() / snd_ctl_elem_list_free() to allocate + * and free memory on the heap, or + * - snd_ctl_elem_list_alloca() to allocate the memory on the + * stack. This memory is auto-released when the stack is unwound. + * + * To manage the space for the element identifiers, the + * snd_ctl_elem_list_alloc_space() and snd_ctl_elem_list_free_space() + * are used. Allocating the right amount of space can be achieved by + * first obtaining the number of elements and then calling + * snd_ctl_elem_list_alloc_space(): + * + * \code + * snd_ctl_elem_list_t* list; + * int count; + * + * // Initialise list + * snd_ctl_elem_list_malloc(&list); + * + * // Get number of elements + * snd_ctl_elem_list(ctl, list); + * count = snd_ctl_elem_list_get_count(list); + * + * // Allocate space for identifiers + * snd_ctl_elem_list_alloc_space(list, count); + * + * // Get identifiers + * snd_ctl_elem_list(ctl, list); // yes, this is same as above :) + * + * // Do something useful with the list... + * + * // Cleanup + * snd_ctl_elem_list_free_space(list); + * snd_ctl_elem_list_free(list); + * \endcode + * + * + * \par The Elements + * + * The elements in the list are accessed using an index. This index is + * the location in the list; Don't confuse it with the 'index' of the + * element identifier. For example: + * + * \code + * snd_ctl_elem_list_t list; + * unsigned int element_index; + * + * // Allocate space, fill list ... + * + * element_index = snd_ctl_elem_list_get_index(&list, 2); + * \endcode + * + * This will access the 3rd element in the list (index=2) and get the + * elements index from the driver (which might be 13, for example). + */ typedef struct _snd_ctl_elem_list snd_ctl_elem_list_t; /** CTL element info container */ @@ -354,11 +422,18 @@ void snd_ctl_event_copy(snd_ctl_event_t *dst, const snd_ctl_event_t *src); snd_ctl_event_type_t snd_ctl_event_get_type(const snd_ctl_event_t *obj); size_t snd_ctl_elem_list_sizeof(void); + /** \hideinitializer - * \brief allocate an invalid #snd_ctl_elem_list_t using standard alloca - * \param ptr returned pointer + * + * \brief Allocate a #snd_ctl_elem_list_t using standard alloca. + * + * The memory is allocated on the stack and will automatically be + * released when the stack unwinds (i.e. no free() is needed). + * + * \param ptr Pointer to allocated memory. */ #define snd_ctl_elem_list_alloca(ptr) __snd_alloca(ptr, snd_ctl_elem_list) + int snd_ctl_elem_list_malloc(snd_ctl_elem_list_t **ptr); void snd_ctl_elem_list_free(snd_ctl_elem_list_t *obj); void snd_ctl_elem_list_clear(snd_ctl_elem_list_t *obj); diff --git a/src/control/control.c b/src/control/control.c index e21e8f1d..1bcf1ab2 100644 --- a/src/control/control.c +++ b/src/control/control.c @@ -280,6 +280,21 @@ int snd_ctl_card_info(snd_ctl_t *ctl, snd_ctl_card_info_t *info) /** * \brief Get a list of element identifiers + * + * Before calling this function, memoru must be allocated using + * snd_ctl_elem_list_malloc(). + * + * This function obtains data from the sound card driver and puts it + * into the list. + * + * If there was space allocated for the element identifiers (using + * snd_ctl_elem_list_alloc_space()), information will be filled in. If + * too little space was allocated, only a part of the elements will be + * queried. If there was too much space allocated, some of it remains + * unused. Use snd_ctl_elem_list_get_count() and + * snd_ctl_elem_list_get_used() to obtain information about space + * usage. See #snd_ctl_elem_list_t to learn more. + * * \param ctl CTL handle * \param list CTL element identifiers list pointer * \return 0 on success otherwise a negative error code @@ -1508,9 +1523,14 @@ const char *snd_ctl_event_type_name(snd_ctl_event_type_t type) /** * \brief allocate space for CTL element identifiers list - * \param obj CTL element identifiers list - * \param entries Entries to allocate - * \return 0 on success otherwise a negative error code + * + * The space can be released with snd_ctl_elem_list_free_space(). + * + * \param obj CTL element identifiers list. + * \param entries How many entries to allocate. See + * #snd_ctl_elem_list_t to learn how to obtain + * this number in advance. + * \return 0 on success otherwise a negative error code. */ int snd_ctl_elem_list_alloc_space(snd_ctl_elem_list_t *obj, unsigned int entries) { @@ -1526,6 +1546,10 @@ int snd_ctl_elem_list_alloc_space(snd_ctl_elem_list_t *obj, unsigned int entries /** * \brief free previously allocated space for CTL element identifiers list + * + * Releases space previously allocated using + * snd_ctl_elem_list_alloc_space(). + * * \param obj CTL element identifiers list */ void snd_ctl_elem_list_free_space(snd_ctl_elem_list_t *obj) @@ -2016,7 +2040,7 @@ snd_ctl_event_type_t snd_ctl_event_get_type(const snd_ctl_event_t *obj) } /** - * \brief get size of #snd_ctl_elem_list_t + * \brief get size of #snd_ctl_elem_list_t. * \return size in bytes */ size_t snd_ctl_elem_list_sizeof() @@ -2025,7 +2049,10 @@ size_t snd_ctl_elem_list_sizeof() } /** - * \brief allocate an invalid #snd_ctl_elem_list_t using standard malloc + * \brief allocate a #snd_ctl_elem_list_t using standard malloc. + * + * The memory can be released using snd_ctl_elem_list_free(). + * * \param ptr returned pointer * \return 0 on success otherwise negative error code */ @@ -2039,7 +2066,15 @@ int snd_ctl_elem_list_malloc(snd_ctl_elem_list_t **ptr) } /** - * \brief frees a previously allocated #snd_ctl_elem_list_t + * \brief frees a previously allocated #snd_ctl_elem_list_t. + * + * Release memory previously allocated using + * snd_ctl_elem_list_malloc(). + * + * If you used snd_ctl_elem_list_alloc_space() on the list, you must + * use snd_ctl_elem_list_free_space() \em before calling this + * function. + * * \param obj pointer to object to free */ void snd_ctl_elem_list_free(snd_ctl_elem_list_t *obj) @@ -2048,7 +2083,15 @@ void snd_ctl_elem_list_free(snd_ctl_elem_list_t *obj) } /** - * \brief clear given #snd_ctl_elem_list_t object + * \brief Clear given #snd_ctl_elem_list_t object. + * + * This will make the stored identifiers inaccessible without freeing + * their space. + * + * \warning The element identifier space cannot be freed after calling + * this function. Therefore, snd_ctl_elem_list_free_space() + * must be called in advance. + * * \param obj pointer to object to clear */ void snd_ctl_elem_list_clear(snd_ctl_elem_list_t *obj) @@ -2057,7 +2100,11 @@ void snd_ctl_elem_list_clear(snd_ctl_elem_list_t *obj) } /** - * \brief copy one #snd_ctl_elem_list_t to another + * \brief copy one #snd_ctl_elem_list_t to another. + * + * This performs a shallow copy. That means the both lists will share + * the same space for the elements. The elements will not be copied. + * * \param dst pointer to destination * \param src pointer to source */ @@ -2080,6 +2127,12 @@ void snd_ctl_elem_list_set_offset(snd_ctl_elem_list_t *obj, unsigned int val) /** * \brief Get number of used entries in CTL element identifiers list + * + * This function returns how many entries are actually filled with + * useful information. + * + * See also snd_ctl_elem_list_get_count(). + * * \param obj CTL element identifier list * \return number of used entries */ @@ -2090,7 +2143,14 @@ unsigned int snd_ctl_elem_list_get_used(const snd_ctl_elem_list_t *obj) } /** - * \brief Get total count of elements present in CTL device (information present in every filled CTL element identifiers list) + * \brief Get total count of elements present in CTL device + * + * This function returns how many entries were allocated using + * snd_ctl_elem_list_alloc_space(). This information is present after + * snd_ctl_elem_list() was called. + * + * See also snd_ctl_elem_list_get_used(). + * * \param obj CTL element identifier list * \return total number of elements */ @@ -2140,7 +2200,7 @@ snd_ctl_elem_iface_t snd_ctl_elem_list_get_interface(const snd_ctl_elem_list_t * } /** - * \brief Get device part of CTL element identifier for an entry of a CTL element identifiers list + * \brief Get the device part of CTL element identifier for an entry of a CTL element identifiers list * \param obj CTL element identifier list * \param idx Index of entry * \return CTL element related device -- 2.17.1

1 0