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: Takashi Iwai <tiwai@suse.de>
This commit is contained in:
Takashi Iwai
parent
539311aa61
commit
4e2b70673f
|
|
@ -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)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue