* [PATCH 0/7] ALSA: kernel doc fixes
@ 2022-07-13 10:47 Takashi Iwai
2022-07-13 10:47 ` [PATCH 1/7] ALSA: compress: Enable kernel doc markers for some functions Takashi Iwai
` (6 more replies)
0 siblings, 7 replies; 8+ messages in thread
From: Takashi Iwai @ 2022-07-13 10:47 UTC (permalink / raw)
To: alsa-devel
Hi,
this is a patch series to address minor warnings at processing kernel
docs.
Takashi
===
Takashi Iwai (7):
ALSA: compress: Enable kernel doc markers for some functions
ALSA: pcm: Fix missing return value comments for kernel docs
ALSA: dmaengine: Fix missing return value comments for kernel docs
ALSA: compress: Fix kernel doc warnings
ALSA: control: Fix missing return value comments for kernel docs
ALSA: memalloc: Fix missing return value comments for kernel docs
ALSA: core: Fix missing return value comments for kernel docs
include/sound/dmaengine_pcm.h | 2 ++
include/sound/pcm.h | 50 +++++++++++++++++++++++++--
include/uapi/sound/compress_offload.h | 2 +-
include/uapi/sound/compress_params.h | 6 ++--
sound/core/compress_offload.c | 9 +++--
sound/core/control.c | 16 +++++++--
sound/core/device.c | 2 ++
sound/core/info.c | 2 ++
sound/core/init.c | 10 ++++++
sound/core/isadma.c | 3 +-
sound/core/memalloc.c | 10 +++++-
sound/core/pcm.c | 4 +++
sound/core/pcm_dmaengine.c | 30 ++++++++++------
sound/core/pcm_memory.c | 4 +++
sound/core/pcm_native.c | 6 ++++
sound/core/vmaster.c | 3 +-
16 files changed, 136 insertions(+), 23 deletions(-)
--
2.35.3
^ permalink raw reply [flat|nested] 8+ messages in thread
* [PATCH 1/7] ALSA: compress: Enable kernel doc markers for some functions
2022-07-13 10:47 [PATCH 0/7] ALSA: kernel doc fixes Takashi Iwai
@ 2022-07-13 10:47 ` Takashi Iwai
2022-07-13 10:47 ` [PATCH 2/7] ALSA: pcm: Fix missing return value comments for kernel docs Takashi Iwai
` (5 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: Takashi Iwai @ 2022-07-13 10:47 UTC (permalink / raw)
To: alsa-devel
The exported functions snd_compress_new() and snd_compr_stop_error()
had already kernel-doc-style comments but they were not processed as
they weren't marked properly. Let's enable them.
This patch also fixes the missing argument id for snd_compress_new
comments, too.
Reported-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/3cd6b93b36b32ad6ae160931aaa00b20688e241a.1656759989.git.mchehab@kernel.org
Signed-off-by: Takashi Iwai <tiwai@suse.de>
---
sound/core/compress_offload.c | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/sound/core/compress_offload.c b/sound/core/compress_offload.c
index de514ec8c83d..cf415fe231ed 100644
--- a/sound/core/compress_offload.c
+++ b/sound/core/compress_offload.c
@@ -810,7 +810,7 @@ static void error_delayed_work(struct work_struct *work)
mutex_unlock(&stream->device->lock);
}
-/*
+/**
* snd_compr_stop_error: Report a fatal error on a stream
* @stream: pointer to stream
* @state: state to transition the stream to
@@ -1157,11 +1157,12 @@ static int snd_compress_dev_free(struct snd_device *device)
return 0;
}
-/*
+/**
* snd_compress_new: create new compress device
* @card: sound card pointer
* @device: device number
* @dirn: device direction, should be of type enum snd_compr_direction
+ * @id: ID string
* @compr: compress device pointer
*/
int snd_compress_new(struct snd_card *card, int device,
--
2.35.3
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 2/7] ALSA: pcm: Fix missing return value comments for kernel docs
2022-07-13 10:47 [PATCH 0/7] ALSA: kernel doc fixes Takashi Iwai
2022-07-13 10:47 ` [PATCH 1/7] ALSA: compress: Enable kernel doc markers for some functions Takashi Iwai
@ 2022-07-13 10:47 ` Takashi Iwai
2022-07-13 10:47 ` [PATCH 3/7] ALSA: dmaengine: " Takashi Iwai
` (4 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: Takashi Iwai @ 2022-07-13 10:47 UTC (permalink / raw)
To: alsa-devel
Each kernel doc comment expects the definition of the return value in
a proper format. This patch adds or fixes the missing entries for PCM
API.
Signed-off-by: Takashi Iwai <tiwai@suse.de>
---
include/sound/pcm.h | 50 +++++++++++++++++++++++++++++++++++++++--
sound/core/pcm.c | 4 ++++
sound/core/pcm_memory.c | 4 ++++
sound/core/pcm_native.c | 6 +++++
4 files changed, 62 insertions(+), 2 deletions(-)
diff --git a/include/sound/pcm.h b/include/sound/pcm.h
index 6b99310b5b88..08cf4a5801f3 100644
--- a/include/sound/pcm.h
+++ b/include/sound/pcm.h
@@ -607,7 +607,7 @@ snd_pcm_debug_name(struct snd_pcm_substream *substream, char *buf, size_t size)
* snd_pcm_stream_linked - Check whether the substream is linked with others
* @substream: substream to check
*
- * Returns true if the given substream is being linked with others.
+ * Return: true if the given substream is being linked with others
*/
static inline int snd_pcm_stream_linked(struct snd_pcm_substream *substream)
{
@@ -673,7 +673,7 @@ void snd_pcm_stream_unlock_irqrestore(struct snd_pcm_substream *substream,
* snd_pcm_running - Check whether the substream is in a running state
* @substream: substream to check
*
- * Returns true if the given substream is in the state RUNNING, or in the
+ * Return: true if the given substream is in the state RUNNING, or in the
* state DRAINING for playback.
*/
static inline int snd_pcm_running(struct snd_pcm_substream *substream)
@@ -687,6 +687,8 @@ static inline int snd_pcm_running(struct snd_pcm_substream *substream)
* bytes_to_samples - Unit conversion of the size from bytes to samples
* @runtime: PCM runtime instance
* @size: size in bytes
+ *
+ * Return: the size in samples
*/
static inline ssize_t bytes_to_samples(struct snd_pcm_runtime *runtime, ssize_t size)
{
@@ -697,6 +699,8 @@ static inline ssize_t bytes_to_samples(struct snd_pcm_runtime *runtime, ssize_t
* bytes_to_frames - Unit conversion of the size from bytes to frames
* @runtime: PCM runtime instance
* @size: size in bytes
+ *
+ * Return: the size in frames
*/
static inline snd_pcm_sframes_t bytes_to_frames(struct snd_pcm_runtime *runtime, ssize_t size)
{
@@ -707,6 +711,8 @@ static inline snd_pcm_sframes_t bytes_to_frames(struct snd_pcm_runtime *runtime,
* samples_to_bytes - Unit conversion of the size from samples to bytes
* @runtime: PCM runtime instance
* @size: size in samples
+ *
+ * Return: the byte size
*/
static inline ssize_t samples_to_bytes(struct snd_pcm_runtime *runtime, ssize_t size)
{
@@ -717,6 +723,8 @@ static inline ssize_t samples_to_bytes(struct snd_pcm_runtime *runtime, ssize_t
* frames_to_bytes - Unit conversion of the size from frames to bytes
* @runtime: PCM runtime instance
* @size: size in frames
+ *
+ * Return: the byte size
*/
static inline ssize_t frames_to_bytes(struct snd_pcm_runtime *runtime, snd_pcm_sframes_t size)
{
@@ -727,6 +735,8 @@ static inline ssize_t frames_to_bytes(struct snd_pcm_runtime *runtime, snd_pcm_s
* frame_aligned - Check whether the byte size is aligned to frames
* @runtime: PCM runtime instance
* @bytes: size in bytes
+ *
+ * Return: true if aligned, or false if not
*/
static inline int frame_aligned(struct snd_pcm_runtime *runtime, ssize_t bytes)
{
@@ -736,6 +746,8 @@ static inline int frame_aligned(struct snd_pcm_runtime *runtime, ssize_t bytes)
/**
* snd_pcm_lib_buffer_bytes - Get the buffer size of the current PCM in bytes
* @substream: PCM substream
+ *
+ * Return: buffer byte size
*/
static inline size_t snd_pcm_lib_buffer_bytes(struct snd_pcm_substream *substream)
{
@@ -746,6 +758,8 @@ static inline size_t snd_pcm_lib_buffer_bytes(struct snd_pcm_substream *substrea
/**
* snd_pcm_lib_period_bytes - Get the period size of the current PCM in bytes
* @substream: PCM substream
+ *
+ * Return: period byte size
*/
static inline size_t snd_pcm_lib_period_bytes(struct snd_pcm_substream *substream)
{
@@ -758,6 +772,8 @@ static inline size_t snd_pcm_lib_period_bytes(struct snd_pcm_substream *substrea
* @runtime: PCM runtime instance
*
* Result is between 0 ... (boundary - 1)
+ *
+ * Return: available frame size
*/
static inline snd_pcm_uframes_t snd_pcm_playback_avail(struct snd_pcm_runtime *runtime)
{
@@ -774,6 +790,8 @@ static inline snd_pcm_uframes_t snd_pcm_playback_avail(struct snd_pcm_runtime *r
* @runtime: PCM runtime instance
*
* Result is between 0 ... (boundary - 1)
+ *
+ * Return: available frame size
*/
static inline snd_pcm_uframes_t snd_pcm_capture_avail(struct snd_pcm_runtime *runtime)
{
@@ -786,6 +804,8 @@ static inline snd_pcm_uframes_t snd_pcm_capture_avail(struct snd_pcm_runtime *ru
/**
* snd_pcm_playback_hw_avail - Get the queued space for playback
* @runtime: PCM runtime instance
+ *
+ * Return: available frame size
*/
static inline snd_pcm_sframes_t snd_pcm_playback_hw_avail(struct snd_pcm_runtime *runtime)
{
@@ -795,6 +815,8 @@ static inline snd_pcm_sframes_t snd_pcm_playback_hw_avail(struct snd_pcm_runtime
/**
* snd_pcm_capture_hw_avail - Get the free space for capture
* @runtime: PCM runtime instance
+ *
+ * Return: available frame size
*/
static inline snd_pcm_sframes_t snd_pcm_capture_hw_avail(struct snd_pcm_runtime *runtime)
{
@@ -934,6 +956,8 @@ static inline const struct snd_interval *hw_param_interval_c(const struct snd_pc
/**
* params_channels - Get the number of channels from the hw params
* @p: hw params
+ *
+ * Return: the number of channels
*/
static inline unsigned int params_channels(const struct snd_pcm_hw_params *p)
{
@@ -943,6 +967,8 @@ static inline unsigned int params_channels(const struct snd_pcm_hw_params *p)
/**
* params_rate - Get the sample rate from the hw params
* @p: hw params
+ *
+ * Return: the sample rate
*/
static inline unsigned int params_rate(const struct snd_pcm_hw_params *p)
{
@@ -952,6 +978,8 @@ static inline unsigned int params_rate(const struct snd_pcm_hw_params *p)
/**
* params_period_size - Get the period size (in frames) from the hw params
* @p: hw params
+ *
+ * Return: the period size in frames
*/
static inline unsigned int params_period_size(const struct snd_pcm_hw_params *p)
{
@@ -961,6 +989,8 @@ static inline unsigned int params_period_size(const struct snd_pcm_hw_params *p)
/**
* params_periods - Get the number of periods from the hw params
* @p: hw params
+ *
+ * Return: the number of periods
*/
static inline unsigned int params_periods(const struct snd_pcm_hw_params *p)
{
@@ -970,6 +1000,8 @@ static inline unsigned int params_periods(const struct snd_pcm_hw_params *p)
/**
* params_buffer_size - Get the buffer size (in frames) from the hw params
* @p: hw params
+ *
+ * Return: the buffer size in frames
*/
static inline unsigned int params_buffer_size(const struct snd_pcm_hw_params *p)
{
@@ -979,6 +1011,8 @@ static inline unsigned int params_buffer_size(const struct snd_pcm_hw_params *p)
/**
* params_buffer_bytes - Get the buffer size (in bytes) from the hw params
* @p: hw params
+ *
+ * Return: the buffer size in bytes
*/
static inline unsigned int params_buffer_bytes(const struct snd_pcm_hw_params *p)
{
@@ -1241,6 +1275,8 @@ int snd_pcm_set_managed_buffer_all(struct snd_pcm *pcm, int type,
* only the given sized buffer and doesn't allow re-allocation nor dynamic
* allocation of a larger buffer unlike the standard one.
* The function may return -ENOMEM error, hence the caller must check it.
+ *
+ * Return: zero if successful, or a negative error code
*/
static inline int __must_check
snd_pcm_set_fixed_buffer(struct snd_pcm_substream *substream, int type,
@@ -1259,6 +1295,8 @@ snd_pcm_set_fixed_buffer(struct snd_pcm_substream *substream, int type,
* Apply the set up of the fixed buffer via snd_pcm_set_fixed_buffer() for
* all substream. If any of allocation fails, it returns -ENOMEM, hence the
* caller must check the return value.
+ *
+ * Return: zero if successful, or a negative error code
*/
static inline int __must_check
snd_pcm_set_fixed_buffer_all(struct snd_pcm *pcm, int type,
@@ -1315,6 +1353,8 @@ static inline int snd_pcm_lib_alloc_vmalloc_32_buffer
* snd_pcm_sgbuf_get_addr - Get the DMA address at the corresponding offset
* @substream: PCM substream
* @ofs: byte offset
+ *
+ * Return: DMA address
*/
static inline dma_addr_t
snd_pcm_sgbuf_get_addr(struct snd_pcm_substream *substream, unsigned int ofs)
@@ -1328,6 +1368,8 @@ snd_pcm_sgbuf_get_addr(struct snd_pcm_substream *substream, unsigned int ofs)
* @substream: PCM substream
* @ofs: byte offset
* @size: byte size to examine
+ *
+ * Return: chunk size
*/
static inline unsigned int
snd_pcm_sgbuf_get_chunk_size(struct snd_pcm_substream *substream,
@@ -1430,6 +1472,8 @@ struct snd_pcm_chmap {
* snd_pcm_chmap_substream - get the PCM substream assigned to the given chmap info
* @info: chmap information
* @idx: the substream number index
+ *
+ * Return: the matched PCM substream, or NULL if not found
*/
static inline struct snd_pcm_substream *
snd_pcm_chmap_substream(struct snd_pcm_chmap *info, unsigned int idx)
@@ -1460,6 +1504,8 @@ int snd_pcm_add_chmap_ctls(struct snd_pcm *pcm, int stream,
/**
* pcm_format_to_bits - Strong-typed conversion of pcm_format to bitwise
* @pcm_format: PCM format
+ *
+ * Return: 64bit mask corresponding to the given PCM format
*/
static inline u64 pcm_format_to_bits(snd_pcm_format_t pcm_format)
{
diff --git a/sound/core/pcm.c b/sound/core/pcm.c
index 977d54320a5c..03fc5fa5813e 100644
--- a/sound/core/pcm.c
+++ b/sound/core/pcm.c
@@ -216,6 +216,8 @@ static const char * const snd_pcm_format_names[] = {
/**
* snd_pcm_format_name - Return a name string for the given PCM format
* @format: PCM format
+ *
+ * Return: the format name string
*/
const char *snd_pcm_format_name(snd_pcm_format_t format)
{
@@ -1138,6 +1140,8 @@ static int snd_pcm_dev_disconnect(struct snd_device *device)
* This adds the given notifier to the global list so that the callback is
* called for each registered PCM devices. This exists only for PCM OSS
* emulation, so far.
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_pcm_notify(struct snd_pcm_notify *notify, int nfree)
{
diff --git a/sound/core/pcm_memory.c b/sound/core/pcm_memory.c
index b8296b6eb2c1..7bde7fb64011 100644
--- a/sound/core/pcm_memory.c
+++ b/sound/core/pcm_memory.c
@@ -350,6 +350,8 @@ EXPORT_SYMBOL(snd_pcm_lib_preallocate_pages_for_all);
* SNDRV_DMA_TYPE_VMALLOC type.
*
* Upon successful buffer allocation and setup, the function returns 0.
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_pcm_set_managed_buffer(struct snd_pcm_substream *substream, int type,
struct device *data, size_t size, size_t max)
@@ -369,6 +371,8 @@ EXPORT_SYMBOL(snd_pcm_set_managed_buffer);
*
* Do pre-allocation to all substreams of the given pcm for the specified DMA
* type and size, and set the managed_buffer_alloc flag to each substream.
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_pcm_set_managed_buffer_all(struct snd_pcm *pcm, int type,
struct device *data,
diff --git a/sound/core/pcm_native.c b/sound/core/pcm_native.c
index 4adaee62ef33..aa0453e51595 100644
--- a/sound/core/pcm_native.c
+++ b/sound/core/pcm_native.c
@@ -3412,6 +3412,8 @@ static long snd_pcm_ioctl(struct file *file, unsigned int cmd,
* The function is provided primarily for OSS layer and USB gadget drivers,
* and it allows only the limited set of ioctls (hw_params, sw_params,
* prepare, start, drain, drop, forward).
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_pcm_kernel_ioctl(struct snd_pcm_substream *substream,
unsigned int cmd, void *arg)
@@ -3810,6 +3812,8 @@ static const struct vm_operations_struct snd_pcm_vm_ops_data_fault = {
*
* This is the default mmap handler for PCM data. When mmap pcm_ops is NULL,
* this function is invoked implicitly.
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_pcm_lib_default_mmap(struct snd_pcm_substream *substream,
struct vm_area_struct *area)
@@ -3836,6 +3840,8 @@ EXPORT_SYMBOL_GPL(snd_pcm_lib_default_mmap);
* When your hardware uses the iomapped pages as the hardware buffer and
* wants to mmap it, pass this function as mmap pcm_ops. Note that this
* is supposed to work only on limited architectures.
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_pcm_lib_mmap_iomem(struct snd_pcm_substream *substream,
struct vm_area_struct *area)
--
2.35.3
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 3/7] ALSA: dmaengine: Fix missing return value comments for kernel docs
2022-07-13 10:47 [PATCH 0/7] ALSA: kernel doc fixes Takashi Iwai
2022-07-13 10:47 ` [PATCH 1/7] ALSA: compress: Enable kernel doc markers for some functions Takashi Iwai
2022-07-13 10:47 ` [PATCH 2/7] ALSA: pcm: Fix missing return value comments for kernel docs Takashi Iwai
@ 2022-07-13 10:47 ` Takashi Iwai
2022-07-13 10:47 ` [PATCH 4/7] ALSA: compress: Fix kernel doc warnings Takashi Iwai
` (3 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: Takashi Iwai @ 2022-07-13 10:47 UTC (permalink / raw)
To: alsa-devel
Each kernel doc comment expects the definition of the return value in
a proper format. This patch adds or fixes the missing entries for PCM
dmaengine API.
Signed-off-by: Takashi Iwai <tiwai@suse.de>
---
include/sound/dmaengine_pcm.h | 2 ++
sound/core/pcm_dmaengine.c | 30 ++++++++++++++++++++----------
2 files changed, 22 insertions(+), 10 deletions(-)
diff --git a/include/sound/dmaengine_pcm.h b/include/sound/dmaengine_pcm.h
index 38ea046e653c..2df54cf02cb3 100644
--- a/include/sound/dmaengine_pcm.h
+++ b/include/sound/dmaengine_pcm.h
@@ -15,6 +15,8 @@
* snd_pcm_substream_to_dma_direction - Get dma_transfer_direction for a PCM
* substream
* @substream: PCM substream
+ *
+ * Return: DMA transfer direction
*/
static inline enum dma_transfer_direction
snd_pcm_substream_to_dma_direction(const struct snd_pcm_substream *substream)
diff --git a/sound/core/pcm_dmaengine.c b/sound/core/pcm_dmaengine.c
index af6f717e1e7e..5b2ca028f5aa 100644
--- a/sound/core/pcm_dmaengine.c
+++ b/sound/core/pcm_dmaengine.c
@@ -48,6 +48,8 @@ EXPORT_SYMBOL_GPL(snd_dmaengine_pcm_get_chan);
*
* This function can be used to initialize a dma_slave_config from a substream
* and hw_params in a dmaengine based PCM driver implementation.
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_hwparams_to_dma_slave_config(const struct snd_pcm_substream *substream,
const struct snd_pcm_hw_params *params,
@@ -175,10 +177,10 @@ static int dmaengine_pcm_prepare_and_submit(struct snd_pcm_substream *substream)
* @substream: PCM substream
* @cmd: Trigger command
*
- * Returns 0 on success, a negative error code otherwise.
- *
* This function can be used as the PCM trigger callback for dmaengine based PCM
* driver implementations.
+ *
+ * Return: 0 on success, a negative error code otherwise
*/
int snd_dmaengine_pcm_trigger(struct snd_pcm_substream *substream, int cmd)
{
@@ -223,6 +225,8 @@ EXPORT_SYMBOL_GPL(snd_dmaengine_pcm_trigger);
*
* This function is deprecated and should not be used by new drivers, as its
* results may be unreliable.
+ *
+ * Return: PCM position in frames
*/
snd_pcm_uframes_t snd_dmaengine_pcm_pointer_no_residue(struct snd_pcm_substream *substream)
{
@@ -237,6 +241,8 @@ EXPORT_SYMBOL_GPL(snd_dmaengine_pcm_pointer_no_residue);
*
* This function can be used as the PCM pointer callback for dmaengine based PCM
* driver implementations.
+ *
+ * Return: PCM position in frames
*/
snd_pcm_uframes_t snd_dmaengine_pcm_pointer(struct snd_pcm_substream *substream)
{
@@ -266,9 +272,9 @@ EXPORT_SYMBOL_GPL(snd_dmaengine_pcm_pointer);
* @filter_fn: Filter function used to request the DMA channel
* @filter_data: Data passed to the DMA filter function
*
- * Returns NULL or the requested DMA channel.
- *
* This function request a DMA channel for usage with dmaengine PCM.
+ *
+ * Return: NULL or the requested DMA channel
*/
struct dma_chan *snd_dmaengine_pcm_request_channel(dma_filter_fn filter_fn,
void *filter_data)
@@ -288,11 +294,11 @@ EXPORT_SYMBOL_GPL(snd_dmaengine_pcm_request_channel);
* @substream: PCM substream
* @chan: DMA channel to use for data transfers
*
- * Returns 0 on success, a negative error code otherwise.
- *
* The function should usually be called from the pcm open callback. Note that
* this function will use private_data field of the substream's runtime. So it
* is not available to your pcm driver implementation.
+ *
+ * Return: 0 on success, a negative error code otherwise
*/
int snd_dmaengine_pcm_open(struct snd_pcm_substream *substream,
struct dma_chan *chan)
@@ -326,12 +332,12 @@ EXPORT_SYMBOL_GPL(snd_dmaengine_pcm_open);
* @filter_fn: Filter function used to request the DMA channel
* @filter_data: Data passed to the DMA filter function
*
- * Returns 0 on success, a negative error code otherwise.
- *
* This function will request a DMA channel using the passed filter function and
* data. The function should usually be called from the pcm open callback. Note
* that this function will use private_data field of the substream's runtime. So
* it is not available to your pcm driver implementation.
+ *
+ * Return: 0 on success, a negative error code otherwise
*/
int snd_dmaengine_pcm_open_request_chan(struct snd_pcm_substream *substream,
dma_filter_fn filter_fn, void *filter_data)
@@ -344,6 +350,8 @@ EXPORT_SYMBOL_GPL(snd_dmaengine_pcm_open_request_chan);
/**
* snd_dmaengine_pcm_close - Close a dmaengine based PCM substream
* @substream: PCM substream
+ *
+ * Return: 0 on success, a negative error code otherwise
*/
int snd_dmaengine_pcm_close(struct snd_pcm_substream *substream)
{
@@ -362,6 +370,8 @@ EXPORT_SYMBOL_GPL(snd_dmaengine_pcm_close);
* @substream: PCM substream
*
* Releases the DMA channel associated with the PCM substream.
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_dmaengine_pcm_close_release_chan(struct snd_pcm_substream *substream)
{
@@ -382,10 +392,10 @@ EXPORT_SYMBOL_GPL(snd_dmaengine_pcm_close_release_chan);
* @hw: PCM hw params
* @chan: DMA channel to use for data transfers
*
- * Returns 0 on success, a negative error code otherwise.
- *
* This function will query DMA capability, then refine the pcm hardware
* parameters.
+ *
+ * Return: 0 on success, a negative error code otherwise
*/
int snd_dmaengine_pcm_refine_runtime_hwparams(
struct snd_pcm_substream *substream,
--
2.35.3
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 4/7] ALSA: compress: Fix kernel doc warnings
2022-07-13 10:47 [PATCH 0/7] ALSA: kernel doc fixes Takashi Iwai
` (2 preceding siblings ...)
2022-07-13 10:47 ` [PATCH 3/7] ALSA: dmaengine: " Takashi Iwai
@ 2022-07-13 10:47 ` Takashi Iwai
2022-07-13 10:47 ` [PATCH 5/7] ALSA: control: Fix missing return value comments for kernel docs Takashi Iwai
` (2 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: Takashi Iwai @ 2022-07-13 10:47 UTC (permalink / raw)
To: alsa-devel
Each kernel doc comment expects the definition of the return value and
the summary for each struct / enum in a proper format. This patch
adds or fixes the missing entries for compress-offload API.
Signed-off-by: Takashi Iwai <tiwai@suse.de>
---
include/uapi/sound/compress_offload.h | 2 +-
include/uapi/sound/compress_params.h | 6 +++---
sound/core/compress_offload.c | 4 ++++
3 files changed, 8 insertions(+), 4 deletions(-)
diff --git a/include/uapi/sound/compress_offload.h b/include/uapi/sound/compress_offload.h
index 9555f31c8425..3aef123dbd7f 100644
--- a/include/uapi/sound/compress_offload.h
+++ b/include/uapi/sound/compress_offload.h
@@ -123,7 +123,7 @@ struct snd_compr_codec_caps {
} __attribute__((packed, aligned(4)));
/**
- * enum sndrv_compress_encoder
+ * enum sndrv_compress_encoder - encoder metadata key
* @SNDRV_COMPRESS_ENCODER_PADDING: no of samples appended by the encoder at the
* end of the track
* @SNDRV_COMPRESS_ENCODER_DELAY: no of samples inserted by the encoder at the
diff --git a/include/uapi/sound/compress_params.h b/include/uapi/sound/compress_params.h
index 79b14389ae41..726361716919 100644
--- a/include/uapi/sound/compress_params.h
+++ b/include/uapi/sound/compress_params.h
@@ -250,7 +250,7 @@ struct snd_enc_wma {
/**
- * struct snd_enc_vorbis
+ * struct snd_enc_vorbis - Vorbis encoder parameters
* @quality: Sets encoding quality to n, between -1 (low) and 10 (high).
* In the default mode of operation, the quality level is 3.
* Normal quality range is 0 - 10.
@@ -279,7 +279,7 @@ struct snd_enc_vorbis {
/**
- * struct snd_enc_real
+ * struct snd_enc_real - RealAudio encoder parameters
* @quant_bits: number of coupling quantization bits in the stream
* @start_region: coupling start region in the stream
* @num_regions: number of regions value
@@ -294,7 +294,7 @@ struct snd_enc_real {
} __attribute__((packed, aligned(4)));
/**
- * struct snd_enc_flac
+ * struct snd_enc_flac - FLAC encoder parameters
* @num: serial number, valid only for OGG formats
* needs to be set by application
* @gain: Add replay gain tags
diff --git a/sound/core/compress_offload.c b/sound/core/compress_offload.c
index cf415fe231ed..243acad89fd3 100644
--- a/sound/core/compress_offload.c
+++ b/sound/core/compress_offload.c
@@ -818,6 +818,8 @@ static void error_delayed_work(struct work_struct *work)
* Stop the stream and set its state.
*
* Should be called with compressed device lock held.
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_compr_stop_error(struct snd_compr_stream *stream,
snd_pcm_state_t state)
@@ -1164,6 +1166,8 @@ static int snd_compress_dev_free(struct snd_device *device)
* @dirn: device direction, should be of type enum snd_compr_direction
* @id: ID string
* @compr: compress device pointer
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_compress_new(struct snd_card *card, int device,
int dirn, const char *id, struct snd_compr *compr)
--
2.35.3
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 5/7] ALSA: control: Fix missing return value comments for kernel docs
2022-07-13 10:47 [PATCH 0/7] ALSA: kernel doc fixes Takashi Iwai
` (3 preceding siblings ...)
2022-07-13 10:47 ` [PATCH 4/7] ALSA: compress: Fix kernel doc warnings Takashi Iwai
@ 2022-07-13 10:47 ` Takashi Iwai
2022-07-13 10:47 ` [PATCH 6/7] ALSA: memalloc: " Takashi Iwai
2022-07-13 10:47 ` [PATCH 7/7] ALSA: core: " Takashi Iwai
6 siblings, 0 replies; 8+ messages in thread
From: Takashi Iwai @ 2022-07-13 10:47 UTC (permalink / raw)
To: alsa-devel
Each kernel doc comment expects the definition of the return value in
proper format. This patch adds or fixes the missing entries for
control API.
Signed-off-by: Takashi Iwai <tiwai@suse.de>
---
sound/core/control.c | 16 ++++++++++++++--
1 file changed, 14 insertions(+), 2 deletions(-)
diff --git a/sound/core/control.c b/sound/core/control.c
index fa04a9233155..4dba3a342458 100644
--- a/sound/core/control.c
+++ b/sound/core/control.c
@@ -2054,6 +2054,8 @@ static int _snd_ctl_register_ioctl(snd_kctl_ioctl_func_t fcn, struct list_head *
* @fcn: ioctl callback function
*
* called from each device manager like pcm.c, hwdep.c, etc.
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_ctl_register_ioctl(snd_kctl_ioctl_func_t fcn)
{
@@ -2066,6 +2068,8 @@ EXPORT_SYMBOL(snd_ctl_register_ioctl);
* snd_ctl_register_ioctl_compat - register the device-specific 32bit compat
* control-ioctls
* @fcn: ioctl callback function
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_ctl_register_ioctl_compat(snd_kctl_ioctl_func_t fcn)
{
@@ -2101,6 +2105,8 @@ static int _snd_ctl_unregister_ioctl(snd_kctl_ioctl_func_t fcn,
/**
* snd_ctl_unregister_ioctl - de-register the device-specific control-ioctls
* @fcn: ioctl callback function to unregister
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_ctl_unregister_ioctl(snd_kctl_ioctl_func_t fcn)
{
@@ -2113,6 +2119,8 @@ EXPORT_SYMBOL(snd_ctl_unregister_ioctl);
* snd_ctl_unregister_ioctl_compat - de-register the device-specific compat
* 32bit control-ioctls
* @fcn: ioctl callback function to unregister
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_ctl_unregister_ioctl_compat(snd_kctl_ioctl_func_t fcn)
{
@@ -2168,7 +2176,7 @@ EXPORT_SYMBOL_GPL(snd_ctl_get_preferred_subdevice);
* snd_ctl_request_layer - request to use the layer
* @module_name: Name of the kernel module (NULL == build-in)
*
- * Return an error code when the module cannot be loaded.
+ * Return: zero if successful, or an error code when the module cannot be loaded
*/
int snd_ctl_request_layer(const char *module_name)
{
@@ -2370,6 +2378,8 @@ int snd_ctl_create(struct snd_card *card)
*
* This is a function that can be used as info callback for a standard
* boolean control with a single mono channel.
+ *
+ * Return: Zero (always successful)
*/
int snd_ctl_boolean_mono_info(struct snd_kcontrol *kcontrol,
struct snd_ctl_elem_info *uinfo)
@@ -2390,6 +2400,8 @@ EXPORT_SYMBOL(snd_ctl_boolean_mono_info);
*
* This is a function that can be used as info callback for a standard
* boolean control with stereo two channels.
+ *
+ * Return: Zero (always successful)
*/
int snd_ctl_boolean_stereo_info(struct snd_kcontrol *kcontrol,
struct snd_ctl_elem_info *uinfo)
@@ -2413,7 +2425,7 @@ EXPORT_SYMBOL(snd_ctl_boolean_stereo_info);
* If the control's accessibility is not the default (readable and writable),
* the caller has to fill @info->access.
*
- * Return: Zero.
+ * Return: Zero (always successful)
*/
int snd_ctl_enum_info(struct snd_ctl_elem_info *info, unsigned int channels,
unsigned int items, const char *const names[])
--
2.35.3
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 6/7] ALSA: memalloc: Fix missing return value comments for kernel docs
2022-07-13 10:47 [PATCH 0/7] ALSA: kernel doc fixes Takashi Iwai
` (4 preceding siblings ...)
2022-07-13 10:47 ` [PATCH 5/7] ALSA: control: Fix missing return value comments for kernel docs Takashi Iwai
@ 2022-07-13 10:47 ` Takashi Iwai
2022-07-13 10:47 ` [PATCH 7/7] ALSA: core: " Takashi Iwai
6 siblings, 0 replies; 8+ messages in thread
From: Takashi Iwai @ 2022-07-13 10:47 UTC (permalink / raw)
To: alsa-devel
Each kernel doc comment expects the definition of the return value in
a proper format. This patch adds or fixes the missing entries for
memory allocation helpers.
Signed-off-by: Takashi Iwai <tiwai@suse.de>
---
sound/core/memalloc.c | 10 +++++++++-
1 file changed, 9 insertions(+), 1 deletion(-)
diff --git a/sound/core/memalloc.c b/sound/core/memalloc.c
index 8cfdaee77905..d3885cb02270 100644
--- a/sound/core/memalloc.c
+++ b/sound/core/memalloc.c
@@ -147,7 +147,7 @@ static void __snd_release_pages(struct device *dev, void *res)
* hence it can't work with SNDRV_DMA_TYPE_CONTINUOUS or
* SNDRV_DMA_TYPE_VMALLOC type.
*
- * The function returns the snd_dma_buffer object at success, or NULL if failed.
+ * Return: the snd_dma_buffer object at success, or NULL if failed
*/
struct snd_dma_buffer *
snd_devm_alloc_dir_pages(struct device *dev, int type,
@@ -179,6 +179,8 @@ EXPORT_SYMBOL_GPL(snd_devm_alloc_dir_pages);
* snd_dma_buffer_mmap - perform mmap of the given DMA buffer
* @dmab: buffer allocation information
* @area: VM area information
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_dma_buffer_mmap(struct snd_dma_buffer *dmab,
struct vm_area_struct *area)
@@ -219,6 +221,8 @@ EXPORT_SYMBOL_GPL(snd_dma_buffer_sync);
* snd_sgbuf_get_addr - return the physical address at the corresponding offset
* @dmab: buffer allocation information
* @offset: offset in the ring buffer
+ *
+ * Return: the physical address
*/
dma_addr_t snd_sgbuf_get_addr(struct snd_dma_buffer *dmab, size_t offset)
{
@@ -235,6 +239,8 @@ EXPORT_SYMBOL(snd_sgbuf_get_addr);
* snd_sgbuf_get_page - return the physical page at the corresponding offset
* @dmab: buffer allocation information
* @offset: offset in the ring buffer
+ *
+ * Return: the page pointer
*/
struct page *snd_sgbuf_get_page(struct snd_dma_buffer *dmab, size_t offset)
{
@@ -253,6 +259,8 @@ EXPORT_SYMBOL(snd_sgbuf_get_page);
* @dmab: buffer allocation information
* @ofs: offset in the ring buffer
* @size: the requested size
+ *
+ * Return: the chunk size
*/
unsigned int snd_sgbuf_get_chunk_size(struct snd_dma_buffer *dmab,
unsigned int ofs, unsigned int size)
--
2.35.3
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 7/7] ALSA: core: Fix missing return value comments for kernel docs
2022-07-13 10:47 [PATCH 0/7] ALSA: kernel doc fixes Takashi Iwai
` (5 preceding siblings ...)
2022-07-13 10:47 ` [PATCH 6/7] ALSA: memalloc: " Takashi Iwai
@ 2022-07-13 10:47 ` Takashi Iwai
6 siblings, 0 replies; 8+ messages in thread
From: Takashi Iwai @ 2022-07-13 10:47 UTC (permalink / raw)
To: alsa-devel
Each kernel doc comment expects the definition of the return value in
a proper format. This patch adds or fixes the missing entries for the
remaining ALSA core API functions.
Signed-off-by: Takashi Iwai <tiwai@suse.de>
---
sound/core/device.c | 2 ++
sound/core/info.c | 2 ++
sound/core/init.c | 10 ++++++++++
sound/core/isadma.c | 3 ++-
sound/core/vmaster.c | 3 ++-
5 files changed, 18 insertions(+), 2 deletions(-)
diff --git a/sound/core/device.c b/sound/core/device.c
index bf0b04a7ee79..b57d80a17052 100644
--- a/sound/core/device.c
+++ b/sound/core/device.c
@@ -247,6 +247,8 @@ void snd_device_free_all(struct snd_card *card)
* device, either @SNDRV_DEV_BUILD, @SNDRV_DEV_REGISTERED or
* @SNDRV_DEV_DISCONNECTED is returned.
* Or for a non-existing device, -1 is returned as an error.
+ *
+ * Return: the current state, or -1 if not found
*/
int snd_device_get_state(struct snd_card *card, void *device_data)
{
diff --git a/sound/core/info.c b/sound/core/info.c
index 782fba87cc04..b8058b341178 100644
--- a/sound/core/info.c
+++ b/sound/core/info.c
@@ -868,6 +868,8 @@ EXPORT_SYMBOL(snd_info_register);
*
* This proc file entry will be registered via snd_card_register() call, and
* it will be removed automatically at the card removal, too.
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_card_rw_proc_new(struct snd_card *card, const char *name,
void *private_data,
diff --git a/sound/core/init.c b/sound/core/init.c
index 1870aee7b64f..3ac95c66a4b5 100644
--- a/sound/core/init.c
+++ b/sound/core/init.c
@@ -215,6 +215,8 @@ static void __snd_card_release(struct device *dev, void *data)
* via snd_card_free() call in the error; otherwise it may lead to UAF due to
* devres call orders. You can use snd_card_free_on_error() helper for
* handling it more easily.
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_devm_card_new(struct device *parent, int idx, const char *xid,
struct module *module, size_t extra_size,
@@ -249,6 +251,8 @@ EXPORT_SYMBOL_GPL(snd_devm_card_new);
* This function handles the explicit snd_card_free() call at the error from
* the probe callback. It's just a small helper for simplifying the error
* handling with the managed devices.
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_card_free_on_error(struct device *dev, int ret)
{
@@ -370,6 +374,8 @@ static int snd_card_init(struct snd_card *card, struct device *parent,
*
* Returns a card object corresponding to the given index or NULL if not found.
* Release the object via snd_card_unref().
+ *
+ * Return: a card object or NULL
*/
struct snd_card *snd_card_ref(int idx)
{
@@ -608,6 +614,8 @@ static int snd_card_do_free(struct snd_card *card)
* resource immediately, but tries to disconnect at first. When the card
* is still in use, the function returns before freeing the resources.
* The card resources will be freed when the refcount gets to zero.
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_card_free_when_closed(struct snd_card *card)
{
@@ -833,6 +841,8 @@ static const struct attribute_group card_dev_attr_group = {
* snd_card_add_dev_attr - Append a new sysfs attribute group to card
* @card: card instance
* @group: attribute group to append
+ *
+ * Return: zero if successful, or a negative error code
*/
int snd_card_add_dev_attr(struct snd_card *card,
const struct attribute_group *group)
diff --git a/sound/core/isadma.c b/sound/core/isadma.c
index 1f45ede023b4..2602246bd5a0 100644
--- a/sound/core/isadma.c
+++ b/sound/core/isadma.c
@@ -116,8 +116,9 @@ static void __snd_release_dma(struct device *dev, void *data)
* @dma: the dma number
* @name: the name string of the requester
*
- * Returns zero on success, or a negative error code.
* The requested DMA will be automatically released at unbinding via devres.
+ *
+ * Return: zero on success, or a negative error code
*/
int snd_devm_request_dma(struct device *dev, int dma, const char *name)
{
diff --git a/sound/core/vmaster.c b/sound/core/vmaster.c
index ab36f9898711..d0f11f37889b 100644
--- a/sound/core/vmaster.c
+++ b/sound/core/vmaster.c
@@ -494,7 +494,8 @@ EXPORT_SYMBOL_GPL(snd_ctl_sync_vmaster);
* @arg: optional function argument
*
* Apply the function @func to each follower kctl of the given vmaster kctl.
- * Returns 0 if successful, or a negative error code.
+ *
+ * Return: 0 if successful, or a negative error code
*/
int snd_ctl_apply_vmaster_followers(struct snd_kcontrol *kctl,
int (*func)(struct snd_kcontrol *vfollower,
--
2.35.3
^ permalink raw reply related [flat|nested] 8+ messages in thread
end of thread, other threads:[~2022-07-13 10:51 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-07-13 10:47 [PATCH 0/7] ALSA: kernel doc fixes Takashi Iwai
2022-07-13 10:47 ` [PATCH 1/7] ALSA: compress: Enable kernel doc markers for some functions Takashi Iwai
2022-07-13 10:47 ` [PATCH 2/7] ALSA: pcm: Fix missing return value comments for kernel docs Takashi Iwai
2022-07-13 10:47 ` [PATCH 3/7] ALSA: dmaengine: " Takashi Iwai
2022-07-13 10:47 ` [PATCH 4/7] ALSA: compress: Fix kernel doc warnings Takashi Iwai
2022-07-13 10:47 ` [PATCH 5/7] ALSA: control: Fix missing return value comments for kernel docs Takashi Iwai
2022-07-13 10:47 ` [PATCH 6/7] ALSA: memalloc: " Takashi Iwai
2022-07-13 10:47 ` [PATCH 7/7] ALSA: core: " Takashi Iwai
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.