Commit 4e2b7067 authored by Takashi Iwai's avatar Takashi Iwai
Browse files

ALSA: pcm: Fix missing return value comments for kernel docs 

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.

Link: https://lore.kernel.org/r/20220713104759.4365-3-tiwai@suse.de


Signed-off-by: default avatarTakashi Iwai <tiwai@suse.de>
parent 539311aa

include/sound/pcm.h

+48 −2
Original line number Diff line number Diff line
@@ -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)

{

sound/core/pcm.c

+4 −0
Original line number Diff line number Diff line
@@ -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)

{

sound/core/pcm_memory.c

+4 −0
Original line number Diff line number Diff line
@@ -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,

sound/core/pcm_native.c

+6 −0
Original line number Diff line number Diff line
@@ -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)