Sound Devices

void snd_card_unref(struct snd_card * card)

Unreference the card object

Parameters

struct snd_card * card
the card object to unreference

Description

Call this function for the card object that was obtained via snd_card_ref() or snd_lookup_minor_data().

snd_printk(fmt, )

printk wrapper

Parameters

fmt
format string
...
variable arguments

Description

Works like printk() but prints the file and the line of the caller when configured with CONFIG_SND_VERBOSE_PRINTK.

snd_printd(fmt, )

debug printk

Parameters

fmt
format string
...
variable arguments

Description

Works like snd_printk() for debugging purposes. Ignored when CONFIG_SND_DEBUG is not set.

snd_BUG()

give a BUG warning message and stack trace

Parameters

Description

Calls WARN() if CONFIG_SND_DEBUG is set. Ignored when CONFIG_SND_DEBUG is not set.

snd_printd_ratelimit()

Parameters

snd_BUG_ON(cond)

debugging check macro

Parameters

cond
condition to evaluate

Description

Has the same behavior as WARN_ON when CONFIG_SND_DEBUG is set, otherwise just evaluates the conditional and returns the value.

snd_printdd(format, )

debug printk

Parameters

format
format string
...
variable arguments

Description

Works like snd_printk() for debugging purposes. Ignored when CONFIG_SND_DEBUG_VERBOSE is not set.

int register_sound_special_device(const struct file_operations * fops, int unit, struct device * dev)

register a special sound node

Parameters

const struct file_operations * fops
File operations for the driver
int unit
Unit number to allocate
struct device * dev
device pointer

Description

Allocate a special sound device by minor number from the sound subsystem.

Return

The allocated number is returned on success. On failure,
a negative error code is returned.
int register_sound_mixer(const struct file_operations * fops, int dev)

register a mixer device

Parameters

const struct file_operations * fops
File operations for the driver
int dev
Unit number to allocate

Description

Allocate a mixer device. Unit is the number of the mixer requested. Pass -1 to request the next free mixer unit.

Return

On success, the allocated number is returned. On failure,
a negative error code is returned.
int register_sound_dsp(const struct file_operations * fops, int dev)

register a DSP device

Parameters

const struct file_operations * fops
File operations for the driver
int dev
Unit number to allocate

Description

Allocate a DSP device. Unit is the number of the DSP requested. Pass -1 to request the next free DSP unit.

This function allocates both the audio and dsp device entries together and will always allocate them as a matching pair - eg dsp3/audio3

Return

On success, the allocated number is returned. On failure,
a negative error code is returned.
void unregister_sound_special(int unit)

unregister a special sound device

Parameters

int unit
unit number to allocate

Description

Release a sound device that was allocated with register_sound_special(). The unit passed is the return value from the register function.
void unregister_sound_mixer(int unit)

unregister a mixer

Parameters

int unit
unit number to allocate

Description

Release a sound device that was allocated with register_sound_mixer(). The unit passed is the return value from the register function.
void unregister_sound_dsp(int unit)

unregister a DSP device

Parameters

int unit
unit number to allocate

Description

Release a sound device that was allocated with register_sound_dsp(). The unit passed is the return value from the register function.

Both of the allocated units are released together automatically.

int snd_pcm_stream_linked(struct snd_pcm_substream * substream)

Check whether the substream is linked with others

Parameters

struct snd_pcm_substream * substream
substream to check

Description

Returns true if the given substream is being linked with others.

snd_pcm_stream_lock_irqsave(substream, flags)

Lock the PCM stream

Parameters

substream
PCM substream
flags
irq flags

Description

This locks the PCM stream like snd_pcm_stream_lock() but with the local IRQ (only when nonatomic is false). In nonatomic case, this is identical as snd_pcm_stream_lock().

snd_pcm_group_for_each_entry(s, substream)

iterate over the linked substreams

Parameters

s
the iterator
substream
the substream

Description

Iterate over the all linked substreams to the given substream. When substream isn’t linked with any others, this gives returns substream itself once.

int snd_pcm_running(struct snd_pcm_substream * substream)

Check whether the substream is in a running state

Parameters

struct snd_pcm_substream * substream
substream to check

Description

Returns true if the given substream is in the state RUNNING, or in the state DRAINING for playback.

ssize_t bytes_to_samples(struct snd_pcm_runtime * runtime, ssize_t size)

Unit conversion of the size from bytes to samples

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
ssize_t size
size in bytes
snd_pcm_sframes_t bytes_to_frames(struct snd_pcm_runtime * runtime, ssize_t size)

Unit conversion of the size from bytes to frames

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
ssize_t size
size in bytes
ssize_t samples_to_bytes(struct snd_pcm_runtime * runtime, ssize_t size)

Unit conversion of the size from samples to bytes

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
ssize_t size
size in samples
ssize_t frames_to_bytes(struct snd_pcm_runtime * runtime, snd_pcm_sframes_t size)

Unit conversion of the size from frames to bytes

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
snd_pcm_sframes_t size
size in frames
int frame_aligned(struct snd_pcm_runtime * runtime, ssize_t bytes)

Check whether the byte size is aligned to frames

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
ssize_t bytes
size in bytes
size_t snd_pcm_lib_buffer_bytes(struct snd_pcm_substream * substream)

Get the buffer size of the current PCM in bytes

Parameters

struct snd_pcm_substream * substream
PCM substream
size_t snd_pcm_lib_period_bytes(struct snd_pcm_substream * substream)

Get the period size of the current PCM in bytes

Parameters

struct snd_pcm_substream * substream
PCM substream
snd_pcm_uframes_t snd_pcm_playback_avail(struct snd_pcm_runtime * runtime)

Get the available (writable) space for playback

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance

Description

Result is between 0 … (boundary - 1)

snd_pcm_uframes_t snd_pcm_capture_avail(struct snd_pcm_runtime * runtime)

Get the available (readable) space for capture

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance

Description

Result is between 0 … (boundary - 1)

snd_pcm_sframes_t snd_pcm_playback_hw_avail(struct snd_pcm_runtime * runtime)

Get the queued space for playback

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
snd_pcm_sframes_t snd_pcm_capture_hw_avail(struct snd_pcm_runtime * runtime)

Get the free space for capture

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
int snd_pcm_playback_ready(struct snd_pcm_substream * substream)

check whether the playback buffer is available

Parameters

struct snd_pcm_substream * substream
the pcm substream instance

Description

Checks whether enough free space is available on the playback buffer.

Return

Non-zero if available, or zero if not.

int snd_pcm_capture_ready(struct snd_pcm_substream * substream)

check whether the capture buffer is available

Parameters

struct snd_pcm_substream * substream
the pcm substream instance

Description

Checks whether enough capture data is available on the capture buffer.

Return

Non-zero if available, or zero if not.

int snd_pcm_playback_data(struct snd_pcm_substream * substream)

check whether any data exists on the playback buffer

Parameters

struct snd_pcm_substream * substream
the pcm substream instance

Description

Checks whether any data exists on the playback buffer.

Return

Non-zero if any data exists, or zero if not. If stop_threshold is bigger or equal to boundary, then this function returns always non-zero.

int snd_pcm_playback_empty(struct snd_pcm_substream * substream)

check whether the playback buffer is empty

Parameters

struct snd_pcm_substream * substream
the pcm substream instance

Description

Checks whether the playback buffer is empty.

Return

Non-zero if empty, or zero if not.

int snd_pcm_capture_empty(struct snd_pcm_substream * substream)

check whether the capture buffer is empty

Parameters

struct snd_pcm_substream * substream
the pcm substream instance

Description

Checks whether the capture buffer is empty.

Return

Non-zero if empty, or zero if not.

void snd_pcm_trigger_done(struct snd_pcm_substream * substream, struct snd_pcm_substream * master)

Mark the master substream

Parameters

struct snd_pcm_substream * substream
the pcm substream instance
struct snd_pcm_substream * master
the linked master substream

Description

When multiple substreams of the same card are linked and the hardware supports the single-shot operation, the driver calls this in the loop in snd_pcm_group_for_each_entry() for marking the substream as “done”. Then most of trigger operations are performed only to the given master substream.

The trigger_master mark is cleared at timestamp updates at the end of trigger operations.

unsigned int params_channels(const struct snd_pcm_hw_params * p)

Get the number of channels from the hw params

Parameters

const struct snd_pcm_hw_params * p
hw params
unsigned int params_rate(const struct snd_pcm_hw_params * p)

Get the sample rate from the hw params

Parameters

const struct snd_pcm_hw_params * p
hw params
unsigned int params_period_size(const struct snd_pcm_hw_params * p)

Get the period size (in frames) from the hw params

Parameters

const struct snd_pcm_hw_params * p
hw params
unsigned int params_periods(const struct snd_pcm_hw_params * p)

Get the number of periods from the hw params

Parameters

const struct snd_pcm_hw_params * p
hw params
unsigned int params_buffer_size(const struct snd_pcm_hw_params * p)

Get the buffer size (in frames) from the hw params

Parameters

const struct snd_pcm_hw_params * p
hw params
unsigned int params_buffer_bytes(const struct snd_pcm_hw_params * p)

Get the buffer size (in bytes) from the hw params

Parameters

const struct snd_pcm_hw_params * p
hw params
int snd_pcm_hw_constraint_single(struct snd_pcm_runtime * runtime, snd_pcm_hw_param_t var, unsigned int val)

Constrain parameter to a single value

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
snd_pcm_hw_param_t var
The hw_params variable to constrain
unsigned int val
The value to constrain to

Return

Positive if the value is changed, zero if it’s not changed, or a negative error code.

int snd_pcm_format_cpu_endian(snd_pcm_format_t format)

Check the PCM format is CPU-endian

Parameters

snd_pcm_format_t format
the format to check

Return

1 if the given PCM format is CPU-endian, 0 if opposite, or a negative error code if endian not specified.

void snd_pcm_set_runtime_buffer(struct snd_pcm_substream * substream, struct snd_dma_buffer * bufp)

Set the PCM runtime buffer

Parameters

struct snd_pcm_substream * substream
PCM substream to set
struct snd_dma_buffer * bufp
the buffer information, NULL to clear

Description

Copy the buffer information to runtime->dma_buffer when bufp is non-NULL. Otherwise it clears the current buffer information.

void snd_pcm_gettime(struct snd_pcm_runtime * runtime, struct timespec64 * tv)

Fill the timespec64 depending on the timestamp mode

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
struct timespec64 * tv
timespec64 to fill
int snd_pcm_lib_alloc_vmalloc_buffer(struct snd_pcm_substream * substream, size_t size)

allocate virtual DMA buffer

Parameters

struct snd_pcm_substream * substream
the substream to allocate the buffer to
size_t size
the requested buffer size, in bytes

Description

Allocates the PCM substream buffer using vmalloc(), i.e., the memory is contiguous in kernel virtual space, but not in physical memory. Use this if the buffer is accessed by kernel code but not by device DMA.

Return

1 if the buffer was changed, 0 if not changed, or a negative error code.

int snd_pcm_lib_alloc_vmalloc_32_buffer(struct snd_pcm_substream * substream, size_t size)

allocate 32-bit-addressable buffer

Parameters

struct snd_pcm_substream * substream
the substream to allocate the buffer to
size_t size
the requested buffer size, in bytes

Description

This function works like snd_pcm_lib_alloc_vmalloc_buffer(), but uses vmalloc_32(), i.e., the pages are allocated from 32-bit-addressable memory.

Return

1 if the buffer was changed, 0 if not changed, or a negative error code.

dma_addr_t snd_pcm_sgbuf_get_addr(struct snd_pcm_substream * substream, unsigned int ofs)

Get the DMA address at the corresponding offset

Parameters

struct snd_pcm_substream * substream
PCM substream
unsigned int ofs
byte offset
void * snd_pcm_sgbuf_get_ptr(struct snd_pcm_substream * substream, unsigned int ofs)

Get the virtual address at the corresponding offset

Parameters

struct snd_pcm_substream * substream
PCM substream
unsigned int ofs
byte offset
unsigned int snd_pcm_sgbuf_get_chunk_size(struct snd_pcm_substream * substream, unsigned int ofs, unsigned int size)

Compute the max size that fits within the contig. page from the given size

Parameters

struct snd_pcm_substream * substream
PCM substream
unsigned int ofs
byte offset
unsigned int size
byte size to examine
void snd_pcm_mmap_data_open(struct vm_area_struct * area)

increase the mmap counter

Parameters

struct vm_area_struct * area
VMA

Description

PCM mmap callback should handle this counter properly

void snd_pcm_mmap_data_close(struct vm_area_struct * area)

decrease the mmap counter

Parameters

struct vm_area_struct * area
VMA

Description

PCM mmap callback should handle this counter properly

void snd_pcm_limit_isa_dma_size(int dma, size_t * max)

Get the max size fitting with ISA DMA transfer

Parameters

int dma
DMA number
size_t * max
pointer to store the max size
const char * snd_pcm_stream_str(struct snd_pcm_substream * substream)

Get a string naming the direction of a stream

Parameters

struct snd_pcm_substream * substream
the pcm substream instance

Return

A string naming the direction of the stream.

struct snd_pcm_substream * snd_pcm_chmap_substream(struct snd_pcm_chmap * info, unsigned int idx)

get the PCM substream assigned to the given chmap info

Parameters

struct snd_pcm_chmap * info
chmap information
unsigned int idx
the substream number index
u64 pcm_format_to_bits(snd_pcm_format_t pcm_format)

Strong-typed conversion of pcm_format to bitwise

Parameters

snd_pcm_format_t pcm_format
PCM format
const char * snd_pcm_format_name(snd_pcm_format_t format)

Return a name string for the given PCM format

Parameters

snd_pcm_format_t format
PCM format
int snd_pcm_new_stream(struct snd_pcm * pcm, int stream, int substream_count)

create a new PCM stream

Parameters

struct snd_pcm * pcm
the pcm instance
int stream
the stream direction, SNDRV_PCM_STREAM_XXX
int substream_count
the number of substreams

Description

Creates a new stream for the pcm. The corresponding stream on the pcm must have been empty before calling this, i.e. zero must be given to the argument of snd_pcm_new().

Return

Zero if successful, or a negative error code on failure.

int snd_pcm_new(struct snd_card * card, const char * id, int device, int playback_count, int capture_count, struct snd_pcm ** rpcm)

create a new PCM instance

Parameters

struct snd_card * card
the card instance
const char * id
the id string
int device
the device index (zero based)
int playback_count
the number of substreams for playback
int capture_count
the number of substreams for capture
struct snd_pcm ** rpcm
the pointer to store the new pcm instance

Description

Creates a new PCM instance.

The pcm operators have to be set afterwards to the new instance via snd_pcm_set_ops().

Return

Zero if successful, or a negative error code on failure.

int snd_pcm_new_internal(struct snd_card * card, const char * id, int device, int playback_count, int capture_count, struct snd_pcm ** rpcm)

create a new internal PCM instance

Parameters

struct snd_card * card
the card instance
const char * id
the id string
int device
the device index (zero based - shared with normal PCMs)
int playback_count
the number of substreams for playback
int capture_count
the number of substreams for capture
struct snd_pcm ** rpcm
the pointer to store the new pcm instance

Description

Creates a new internal PCM instance with no userspace device or procfs entries. This is used by ASoC Back End PCMs in order to create a PCM that will only be used internally by kernel drivers. i.e. it cannot be opened by userspace. It provides existing ASoC components drivers with a substream and access to any private data.

The pcm operators have to be set afterwards to the new instance via snd_pcm_set_ops().

Return

Zero if successful, or a negative error code on failure.

int snd_pcm_notify(struct snd_pcm_notify * notify, int nfree)

Add/remove the notify list

Parameters

struct snd_pcm_notify * notify
PCM notify list
int nfree
0 = register, 1 = unregister

Description

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.

int snd_device_new(struct snd_card * card, enum snd_device_type type, void * device_data, const struct snd_device_ops * ops)

create an ALSA device component

Parameters

struct snd_card * card
the card instance
enum snd_device_type type
the device type, SNDRV_DEV_XXX
void * device_data
the data pointer of this device
const struct snd_device_ops * ops
the operator table

Description

Creates a new device component for the given data pointer. The device will be assigned to the card and managed together by the card.

The data pointer plays a role as the identifier, too, so the pointer address must be unique and unchanged.

Return

Zero if successful, or a negative error code on failure.

void snd_device_disconnect(struct snd_card * card, void * device_data)

disconnect the device

Parameters

struct snd_card * card
the card instance
void * device_data
the data pointer to disconnect

Description

Turns the device into the disconnection state, invoking dev_disconnect callback, if the device was already registered.

Usually called from snd_card_disconnect().

Return

Zero if successful, or a negative error code on failure or if the device not found.

void snd_device_free(struct snd_card * card, void * device_data)

release the device from the card

Parameters

struct snd_card * card
the card instance
void * device_data
the data pointer to release

Description

Removes the device from the list on the card and invokes the callbacks, dev_disconnect and dev_free, corresponding to the state. Then release the device.

int snd_device_register(struct snd_card * card, void * device_data)

register the device

Parameters

struct snd_card * card
the card instance
void * device_data
the data pointer to register

Description

Registers the device which was already created via snd_device_new(). Usually this is called from snd_card_register(), but it can be called later if any new devices are created after invocation of snd_card_register().

Return

Zero if successful, or a negative error code on failure or if the device not found.

int snd_info_get_line(struct snd_info_buffer * buffer, char * line, int len)

read one line from the procfs buffer

Parameters

struct snd_info_buffer * buffer
the procfs buffer
char * line
the buffer to store
int len
the max. buffer size

Description

Reads one line from the buffer and stores the string.

Return

Zero if successful, or 1 if error or EOF.

const char * snd_info_get_str(char * dest, const char * src, int len)

parse a string token

Parameters

char * dest
the buffer to store the string token
const char * src
the original string
int len
the max. length of token - 1

Description

Parses the original string and copy a token to the given string buffer.

Return

The updated pointer of the original string so that it can be used for the next call.

struct snd_info_entry * snd_info_create_module_entry(struct module * module, const char * name, struct snd_info_entry * parent)

create an info entry for the given module

Parameters

struct module * module
the module pointer
const char * name
the file name
struct snd_info_entry * parent
the parent directory

Description

Creates a new info entry and assigns it to the given module.

Return

The pointer of the new instance, or NULL on failure.

struct snd_info_entry * snd_info_create_card_entry(struct snd_card * card, const char * name, struct snd_info_entry * parent)

create an info entry for the given card

Parameters

struct snd_card * card
the card instance
const char * name
the file name
struct snd_info_entry * parent
the parent directory

Description

Creates a new info entry and assigns it to the given card.

Return

The pointer of the new instance, or NULL on failure.

void snd_info_free_entry(struct snd_info_entry * entry)

release the info entry

Parameters

struct snd_info_entry * entry
the info entry

Description

Releases the info entry.

int snd_info_register(struct snd_info_entry * entry)

register the info entry

Parameters

struct snd_info_entry * entry
the info entry

Description

Registers the proc info entry. The all children entries are registered recursively.

Return

Zero if successful, or a negative error code on failure.

int snd_card_rw_proc_new(struct snd_card * card, const char * name, void * private_data, void (*read) (struct snd_info_entry *, struct snd_info_buffer *, void (*write) (struct snd_info_entry *entry, struct snd_info_buffer *buffer)

Create a read/write text proc file entry for the card

Parameters

struct snd_card * card
the card instance
const char * name
the file name
void * private_data
the arbitrary private data
void (*)(struct snd_info_entry *, struct snd_info_buffer *) read
the read callback
void (*)(struct snd_info_entry *entry, struct snd_info_buffer *buffer) write
the write callback, NULL for read-only

Description

This proc file entry will be registered via snd_card_register() call, and it will be removed automatically at the card removal, too.

int snd_rawmidi_receive(struct snd_rawmidi_substream * substream, const unsigned char * buffer, int count)

receive the input data from the device

Parameters

struct snd_rawmidi_substream * substream
the rawmidi substream
const unsigned char * buffer
the buffer pointer
int count
the data size to read

Description

Reads the data from the internal buffer.

Return

The size of read data, or a negative error code on failure.

int snd_rawmidi_transmit_empty(struct snd_rawmidi_substream * substream)

check whether the output buffer is empty

Parameters

struct snd_rawmidi_substream * substream
the rawmidi substream

Return

1 if the internal output buffer is empty, 0 if not.

int __snd_rawmidi_transmit_peek(struct snd_rawmidi_substream * substream, unsigned char * buffer, int count)

copy data from the internal buffer

Parameters

struct snd_rawmidi_substream * substream
the rawmidi substream
unsigned char * buffer
the buffer pointer
int count
data size to transfer

Description

This is a variant of snd_rawmidi_transmit_peek() without spinlock.

int snd_rawmidi_transmit_peek(struct snd_rawmidi_substream * substream, unsigned char * buffer, int count)

copy data from the internal buffer

Parameters

struct snd_rawmidi_substream * substream
the rawmidi substream
unsigned char * buffer
the buffer pointer
int count
data size to transfer

Description

Copies data from the internal output buffer to the given buffer.

Call this in the interrupt handler when the midi output is ready, and call snd_rawmidi_transmit_ack() after the transmission is finished.

Return

The size of copied data, or a negative error code on failure.

int __snd_rawmidi_transmit_ack(struct snd_rawmidi_substream * substream, int count)

acknowledge the transmission

Parameters

struct snd_rawmidi_substream * substream
the rawmidi substream
int count
the transferred count

Description

This is a variant of __snd_rawmidi_transmit_ack() without spinlock.

int snd_rawmidi_transmit_ack(struct snd_rawmidi_substream * substream, int count)

acknowledge the transmission

Parameters

struct snd_rawmidi_substream * substream
the rawmidi substream
int count
the transferred count

Description

Advances the hardware pointer for the internal output buffer with the given size and updates the condition. Call after the transmission is finished.

Return

The advanced size if successful, or a negative error code on failure.

int snd_rawmidi_transmit(struct snd_rawmidi_substream * substream, unsigned char * buffer, int count)

copy from the buffer to the device

Parameters

struct snd_rawmidi_substream * substream
the rawmidi substream
unsigned char * buffer
the buffer pointer
int count
the data size to transfer

Description

Copies data from the buffer to the device and advances the pointer.

Return

The copied size if successful, or a negative error code on failure.

int snd_rawmidi_proceed(struct snd_rawmidi_substream * substream)

Discard the all pending bytes and proceed

Parameters

struct snd_rawmidi_substream * substream
rawmidi substream

Return

the number of discarded bytes

int snd_rawmidi_new(struct snd_card * card, char * id, int device, int output_count, int input_count, struct snd_rawmidi ** rrawmidi)

create a rawmidi instance

Parameters

struct snd_card * card
the card instance
char * id
the id string
int device
the device index
int output_count
the number of output streams
int input_count
the number of input streams
struct snd_rawmidi ** rrawmidi
the pointer to store the new rawmidi instance

Description

Creates a new rawmidi instance. Use snd_rawmidi_set_ops() to set the operators to the new instance.

Return

Zero if successful, or a negative error code on failure.

void snd_rawmidi_set_ops(struct snd_rawmidi * rmidi, int stream, const struct snd_rawmidi_ops * ops)

set the rawmidi operators

Parameters

struct snd_rawmidi * rmidi
the rawmidi instance
int stream
the stream direction, SNDRV_RAWMIDI_STREAM_XXX
const struct snd_rawmidi_ops * ops
the operator table

Description

Sets the rawmidi operators for the given stream direction.

void snd_request_card(int card)

try to load the card module

Parameters

int card
the card number

Description

Tries to load the module “snd-card-X” for the given card number via request_module. Returns immediately if already loaded.

void * snd_lookup_minor_data(unsigned int minor, int type)

get user data of a registered device

Parameters

unsigned int minor
the minor number
int type
device type (SNDRV_DEVICE_TYPE_XXX)

Description

Checks that a minor device with the specified type is registered, and returns its user data pointer.

This function increments the reference counter of the card instance if an associated instance with the given minor number and type is found. The caller must call snd_card_unref() appropriately later.

Return

The user data pointer if the specified device is found. NULL otherwise.

int snd_register_device(int type, struct snd_card * card, int dev, const struct file_operations * f_ops, void * private_data, struct device * device)

Register the ALSA device file for the card

Parameters

int type
the device type, SNDRV_DEVICE_TYPE_XXX
struct snd_card * card
the card instance
int dev
the device index
const struct file_operations * f_ops
the file operations
void * private_data
user pointer for f_ops->open()
struct device * device
the device to register

Description

Registers an ALSA device file for the given card. The operators have to be set in reg parameter.

Return

Zero if successful, or a negative error code on failure.

int snd_unregister_device(struct device * dev)

unregister the device on the given card

Parameters

struct device * dev
the device instance

Description

Unregisters the device file already registered via snd_register_device().

Return

Zero if successful, or a negative error code on failure.

int copy_to_user_fromio(void __user * dst, const volatile void __iomem * src, size_t count)

copy data from mmio-space to user-space

Parameters

void __user * dst
the destination pointer on user-space
const volatile void __iomem * src
the source pointer on mmio
size_t count
the data size to copy in bytes

Description

Copies the data from mmio-space to user-space.

Return

Zero if successful, or non-zero on failure.

int copy_from_user_toio(volatile void __iomem * dst, const void __user * src, size_t count)

copy data from user-space to mmio-space

Parameters

volatile void __iomem * dst
the destination pointer on mmio-space
const void __user * src
the source pointer on user-space
size_t count
the data size to copy in bytes

Description

Copies the data from user-space to mmio-space.

Return

Zero if successful, or non-zero on failure.

void snd_pcm_lib_preallocate_free_for_all(struct snd_pcm * pcm)

release all pre-allocated buffers on the pcm

Parameters

struct snd_pcm * pcm
the pcm instance

Description

Releases all the pre-allocated buffers on the given pcm.

void snd_pcm_lib_preallocate_pages(struct snd_pcm_substream * substream, int type, struct device * data, size_t size, size_t max)

pre-allocation for the given DMA type

Parameters

struct snd_pcm_substream * substream
the pcm substream instance
int type
DMA type (SNDRV_DMA_TYPE_*)
struct device * data
DMA type dependent data
size_t size
the requested pre-allocation size in bytes
size_t max
the max. allowed pre-allocation size

Description

Do pre-allocation for the given DMA buffer type.

void snd_pcm_lib_preallocate_pages_for_all(struct snd_pcm * pcm, int type, void * data, size_t size, size_t max)

pre-allocation for continuous memory type (all substreams)

Parameters

struct snd_pcm * pcm
the pcm instance
int type
DMA type (SNDRV_DMA_TYPE_*)
void * data
DMA type dependent data
size_t size
the requested pre-allocation size in bytes
size_t max
the max. allowed pre-allocation size

Description

Do pre-allocation to all substreams of the given pcm for the specified DMA type.

void snd_pcm_set_managed_buffer(struct snd_pcm_substream * substream, int type, struct device * data, size_t size, size_t max)

set up buffer management for a substream

Parameters

struct snd_pcm_substream * substream
the pcm substream instance
int type
DMA type (SNDRV_DMA_TYPE_*)
struct device * data
DMA type dependent data
size_t size
the requested pre-allocation size in bytes
size_t max
the max. allowed pre-allocation size

Description

Do pre-allocation for the given DMA buffer type, and set the managed buffer allocation mode to the given substream. In this mode, PCM core will allocate a buffer automatically before PCM hw_params ops call, and release the buffer after PCM hw_free ops call as well, so that the driver doesn’t need to invoke the allocation and the release explicitly in its callback. When a buffer is actually allocated before the PCM hw_params call, it turns on the runtime buffer_changed flag for drivers changing their h/w parameters accordingly.

void snd_pcm_set_managed_buffer_all(struct snd_pcm * pcm, int type, struct device * data, size_t size, size_t max)

set up buffer management for all substreams for all substreams

Parameters

struct snd_pcm * pcm
the pcm instance
int type
DMA type (SNDRV_DMA_TYPE_*)
struct device * data
DMA type dependent data
size_t size
the requested pre-allocation size in bytes
size_t max
the max. allowed pre-allocation size

Description

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.

int snd_pcm_lib_malloc_pages(struct snd_pcm_substream * substream, size_t size)

allocate the DMA buffer

Parameters

struct snd_pcm_substream * substream
the substream to allocate the DMA buffer to
size_t size
the requested buffer size in bytes

Description

Allocates the DMA buffer on the BUS type given earlier to snd_pcm_lib_preallocate_xxx_pages().

Return

1 if the buffer is changed, 0 if not changed, or a negative code on failure.

int snd_pcm_lib_free_pages(struct snd_pcm_substream * substream)

release the allocated DMA buffer.

Parameters

struct snd_pcm_substream * substream
the substream to release the DMA buffer

Description

Releases the DMA buffer allocated via snd_pcm_lib_malloc_pages().

Return

Zero if successful, or a negative error code on failure.

int snd_pcm_lib_free_vmalloc_buffer(struct snd_pcm_substream * substream)

free vmalloc buffer

Parameters

struct snd_pcm_substream * substream
the substream with a buffer allocated by snd_pcm_lib_alloc_vmalloc_buffer()

Return

Zero if successful, or a negative error code on failure.

struct page * snd_pcm_lib_get_vmalloc_page(struct snd_pcm_substream * substream, unsigned long offset)

map vmalloc buffer offset to page struct

Parameters

struct snd_pcm_substream * substream
the substream with a buffer allocated by snd_pcm_lib_alloc_vmalloc_buffer()
unsigned long offset
offset in the buffer

Description

This function is to be used as the page callback in the PCM ops.

Return

The page struct, or NULL on failure.

void snd_device_initialize(struct device * dev, struct snd_card * card)

Initialize struct device for sound devices

Parameters

struct device * dev
device to initialize
struct snd_card * card
card to assign, optional
int snd_card_new(struct device * parent, int idx, const char * xid, struct module * module, int extra_size, struct snd_card ** card_ret)

create and initialize a soundcard structure

Parameters

struct device * parent
the parent device object
int idx
card index (address) [0 … (SNDRV_CARDS-1)]
const char * xid
card identification (ASCII string)
struct module * module
top level module for locking
int extra_size
allocate this extra size after the main soundcard structure
struct snd_card ** card_ret
the pointer to store the created card instance

Description

Creates and initializes a soundcard structure.

The function allocates snd_card instance via kzalloc with the given space for the driver to use freely. The allocated struct is stored in the given card_ret pointer.

Return

Zero if successful or a negative error code.

struct snd_card * snd_card_ref(int idx)

Get the card object from the index

Parameters

int idx
the card index

Description

Returns a card object corresponding to the given index or NULL if not found. Release the object via snd_card_unref().

int snd_card_disconnect(struct snd_card * card)

disconnect all APIs from the file-operations (user space)

Parameters

struct snd_card * card
soundcard structure

Description

Disconnects all APIs from the file-operations (user space).

Return

Zero, otherwise a negative error code.

Note

The current implementation replaces all active file->f_op with special
dummy file operations (they do nothing except release).
void snd_card_disconnect_sync(struct snd_card * card)

disconnect card and wait until files get closed

Parameters

struct snd_card * card
card object to disconnect

Description

This calls snd_card_disconnect() for disconnecting all belonging components and waits until all pending files get closed. It assures that all accesses from user-space finished so that the driver can release its resources gracefully.

int snd_card_free_when_closed(struct snd_card * card)

Disconnect the card, free it later eventually

Parameters

struct snd_card * card
soundcard structure

Description

Unlike snd_card_free(), this function doesn’t try to release the 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.

int snd_card_free(struct snd_card * card)

frees given soundcard structure

Parameters

struct snd_card * card
soundcard structure

Description

This function releases the soundcard structure and the all assigned devices automatically. That is, you don’t have to release the devices by yourself.

This function waits until the all resources are properly released.

Return

Zero. Frees all associated devices and frees the control interface associated to given soundcard.

void snd_card_set_id(struct snd_card * card, const char * nid)

set card identification name

Parameters

struct snd_card * card
soundcard structure
const char * nid
new identification string

Description

This function sets the card identification and checks for name collisions.
int snd_card_add_dev_attr(struct snd_card * card, const struct attribute_group * group)

Append a new sysfs attribute group to card

Parameters

struct snd_card * card
card instance
const struct attribute_group * group
attribute group to append
int snd_card_register(struct snd_card * card)

register the soundcard

Parameters

struct snd_card * card
soundcard structure

Description

This function registers all the devices assigned to the soundcard. Until calling this, the ALSA control interface is blocked from the external accesses. Thus, you should call this function at the end of the initialization of the card.

Return

Zero otherwise a negative error code if the registration failed.

int snd_component_add(struct snd_card * card, const char * component)

add a component string

Parameters

struct snd_card * card
soundcard structure
const char * component
the component id string

Description

This function adds the component id string to the supported list. The component can be referred from the alsa-lib.

Return

Zero otherwise a negative error code.

int snd_card_file_add(struct snd_card * card, struct file * file)

add the file to the file list of the card

Parameters

struct snd_card * card
soundcard structure
struct file * file
file pointer

Description

This function adds the file to the file linked-list of the card. This linked-list is used to keep tracking the connection state, and to avoid the release of busy resources by hotplug.

Return

zero or a negative error code.

int snd_card_file_remove(struct snd_card * card, struct file * file)

remove the file from the file list

Parameters

struct snd_card * card
soundcard structure
struct file * file
file pointer

Description

This function removes the file formerly added to the card via snd_card_file_add() function. If all files are removed and snd_card_free_when_closed() was called beforehand, it processes the pending release of resources.

Return

Zero or a negative error code.

int snd_power_wait(struct snd_card * card, unsigned int power_state)

wait until the power-state is changed.

Parameters

struct snd_card * card
soundcard structure
unsigned int power_state
expected power state

Description

Waits until the power-state is changed.

Return

Zero if successful, or a negative error code.

void snd_dma_program(unsigned long dma, unsigned long addr, unsigned int size, unsigned short mode)

program an ISA DMA transfer

Parameters

unsigned long dma
the dma number
unsigned long addr
the physical address of the buffer
unsigned int size
the DMA transfer size
unsigned short mode
the DMA transfer mode, DMA_MODE_XXX

Description

Programs an ISA DMA transfer for the given buffer.

void snd_dma_disable(unsigned long dma)

stop the ISA DMA transfer

Parameters

unsigned long dma
the dma number

Description

Stops the ISA DMA transfer.

unsigned int snd_dma_pointer(unsigned long dma, unsigned int size)

return the current pointer to DMA transfer buffer in bytes

Parameters

unsigned long dma
the dma number
unsigned int size
the dma transfer size

Return

The current pointer in DMA transfer buffer in bytes.

void snd_ctl_notify(struct snd_card * card, unsigned int mask, struct snd_ctl_elem_id * id)

Send notification to user-space for a control change

Parameters

struct snd_card * card
the card to send notification
unsigned int mask
the event mask, SNDRV_CTL_EVENT_*
struct snd_ctl_elem_id * id
the ctl element id to send notification

Description

This function adds an event record with the given id and mask, appends to the list and wakes up the user-space for notification. This can be called in the atomic context.

struct snd_kcontrol * snd_ctl_new1(const struct snd_kcontrol_new * ncontrol, void * private_data)

create a control instance from the template

Parameters

const struct snd_kcontrol_new * ncontrol
the initialization record
void * private_data
the private data to set

Description

Allocates a new struct snd_kcontrol instance and initialize from the given template. When the access field of ncontrol is 0, it’s assumed as READWRITE access. When the count field is 0, it’s assumes as one.

Return

The pointer of the newly generated instance, or NULL on failure.

void snd_ctl_free_one(struct snd_kcontrol * kcontrol)

release the control instance

Parameters

struct snd_kcontrol * kcontrol
the control instance

Description

Releases the control instance created via snd_ctl_new() or snd_ctl_new1(). Don’t call this after the control was added to the card.

int snd_ctl_add(struct snd_card * card, struct snd_kcontrol * kcontrol)

add the control instance to the card

Parameters

struct snd_card * card
the card instance
struct snd_kcontrol * kcontrol
the control instance to add

Description

Adds the control instance created via snd_ctl_new() or snd_ctl_new1() to the given card. Assigns also an unique numid used for fast search.

It frees automatically the control which cannot be added.

Return

Zero if successful, or a negative error code on failure.

int snd_ctl_replace(struct snd_card * card, struct snd_kcontrol * kcontrol, bool add_on_replace)

replace the control instance of the card

Parameters

struct snd_card * card
the card instance
struct snd_kcontrol * kcontrol
the control instance to replace
bool add_on_replace
add the control if not already added

Description

Replaces the given control. If the given control does not exist and the add_on_replace flag is set, the control is added. If the control exists, it is destroyed first.

It frees automatically the control which cannot be added or replaced.

Return

Zero if successful, or a negative error code on failure.

int snd_ctl_remove(struct snd_card * card, struct snd_kcontrol * kcontrol)

remove the control from the card and release it

Parameters

struct snd_card * card
the card instance
struct snd_kcontrol * kcontrol
the control instance to remove

Description

Removes the control from the card and then releases the instance. You don’t need to call snd_ctl_free_one(). You must be in the write lock - down_write(card->controls_rwsem).

Return

0 if successful, or a negative error code on failure.

int snd_ctl_remove_id(struct snd_card * card, struct snd_ctl_elem_id * id)

remove the control of the given id and release it

Parameters

struct snd_card * card
the card instance
struct snd_ctl_elem_id * id
the control id to remove

Description

Finds the control instance with the given id, removes it from the card list and releases it.

Return

0 if successful, or a negative error code on failure.

int snd_ctl_activate_id(struct snd_card * card, struct snd_ctl_elem_id * id, int active)

activate/inactivate the control of the given id

Parameters

struct snd_card * card
the card instance
struct snd_ctl_elem_id * id
the control id to activate/inactivate
int active
non-zero to activate

Description

Finds the control instance with the given id, and activate or inactivate the control together with notification, if changed. The given ID data is filled with full information.

Return

0 if unchanged, 1 if changed, or a negative error code on failure.

int snd_ctl_rename_id(struct snd_card * card, struct snd_ctl_elem_id * src_id, struct snd_ctl_elem_id * dst_id)

replace the id of a control on the card

Parameters

struct snd_card * card
the card instance
struct snd_ctl_elem_id * src_id
the old id
struct snd_ctl_elem_id * dst_id
the new id

Description

Finds the control with the old id from the card, and replaces the id with the new one.

Return

Zero if successful, or a negative error code on failure.

struct snd_kcontrol * snd_ctl_find_numid(struct snd_card * card, unsigned int numid)

find the control instance with the given number-id

Parameters

struct snd_card * card
the card instance
unsigned int numid
the number-id to search

Description

Finds the control instance with the given number-id from the card.

The caller must down card->controls_rwsem before calling this function (if the race condition can happen).

Return

The pointer of the instance if found, or NULL if not.

struct snd_kcontrol * snd_ctl_find_id(struct snd_card * card, struct snd_ctl_elem_id * id)

find the control instance with the given id

Parameters

struct snd_card * card
the card instance
struct snd_ctl_elem_id * id
the id to search

Description

Finds the control instance with the given id from the card.

The caller must down card->controls_rwsem before calling this function (if the race condition can happen).

Return

The pointer of the instance if found, or NULL if not.

int snd_ctl_register_ioctl(snd_kctl_ioctl_func_t fcn)

register the device-specific control-ioctls

Parameters

snd_kctl_ioctl_func_t fcn
ioctl callback function

Description

called from each device manager like pcm.c, hwdep.c, etc.

int snd_ctl_register_ioctl_compat(snd_kctl_ioctl_func_t fcn)

register the device-specific 32bit compat control-ioctls

Parameters

snd_kctl_ioctl_func_t fcn
ioctl callback function
int snd_ctl_unregister_ioctl(snd_kctl_ioctl_func_t fcn)

de-register the device-specific control-ioctls

Parameters

snd_kctl_ioctl_func_t fcn
ioctl callback function to unregister
int snd_ctl_unregister_ioctl_compat(snd_kctl_ioctl_func_t fcn)

de-register the device-specific compat 32bit control-ioctls

Parameters

snd_kctl_ioctl_func_t fcn
ioctl callback function to unregister
int snd_ctl_boolean_mono_info(struct snd_kcontrol * kcontrol, struct snd_ctl_elem_info * uinfo)

Helper function for a standard boolean info callback with a mono channel

Parameters

struct snd_kcontrol * kcontrol
the kcontrol instance
struct snd_ctl_elem_info * uinfo
info to store

Description

This is a function that can be used as info callback for a standard boolean control with a single mono channel.

int snd_ctl_boolean_stereo_info(struct snd_kcontrol * kcontrol, struct snd_ctl_elem_info * uinfo)

Helper function for a standard boolean info callback with stereo two channels

Parameters

struct snd_kcontrol * kcontrol
the kcontrol instance
struct snd_ctl_elem_info * uinfo
info to store

Description

This is a function that can be used as info callback for a standard boolean control with stereo two channels.

int snd_ctl_enum_info(struct snd_ctl_elem_info * info, unsigned int channels, unsigned int items, const char *const names)

fills the info structure for an enumerated control

Parameters

struct snd_ctl_elem_info * info
the structure to be filled
unsigned int channels
the number of the control’s channels; often one
unsigned int items
the number of control values; also the size of names
const char *const names
an array containing the names of all control values

Description

Sets all required fields in info to their appropriate values. If the control’s accessibility is not the default (readable and writable), the caller has to fill info->access.

Return

Zero.

void snd_pcm_set_ops(struct snd_pcm * pcm, int direction, const struct snd_pcm_ops * ops)

set the PCM operators

Parameters

struct snd_pcm * pcm
the pcm instance
int direction
stream direction, SNDRV_PCM_STREAM_XXX
const struct snd_pcm_ops * ops
the operator table

Description

Sets the given PCM operators to the pcm instance.

void snd_pcm_set_sync(struct snd_pcm_substream * substream)

set the PCM sync id

Parameters

struct snd_pcm_substream * substream
the pcm substream

Description

Sets the PCM sync identifier for the card.

int snd_interval_refine(struct snd_interval * i, const struct snd_interval * v)

refine the interval value of configurator

Parameters

struct snd_interval * i
the interval value to refine
const struct snd_interval * v
the interval value to refer to

Description

Refines the interval value with the reference value. The interval is changed to the range satisfying both intervals. The interval status (min, max, integer, etc.) are evaluated.

Return

Positive if the value is changed, zero if it’s not changed, or a negative error code.

int snd_interval_ratnum(struct snd_interval * i, unsigned int rats_count, const struct snd_ratnum * rats, unsigned int * nump, unsigned int * denp)

refine the interval value

Parameters

struct snd_interval * i
interval to refine
unsigned int rats_count
number of ratnum_t
const struct snd_ratnum * rats
ratnum_t array
unsigned int * nump
pointer to store the resultant numerator
unsigned int * denp
pointer to store the resultant denominator

Return

Positive if the value is changed, zero if it’s not changed, or a negative error code.

int snd_interval_list(struct snd_interval * i, unsigned int count, const unsigned int * list, unsigned int mask)

refine the interval value from the list

Parameters

struct snd_interval * i
the interval value to refine
unsigned int count
the number of elements in the list
const unsigned int * list
the value list
unsigned int mask
the bit-mask to evaluate

Description

Refines the interval value from the list. When mask is non-zero, only the elements corresponding to bit 1 are evaluated.

Return

Positive if the value is changed, zero if it’s not changed, or a negative error code.

int snd_interval_ranges(struct snd_interval * i, unsigned int count, const struct snd_interval * ranges, unsigned int mask)

refine the interval value from the list of ranges

Parameters

struct snd_interval * i
the interval value to refine
unsigned int count
the number of elements in the list of ranges
const struct snd_interval * ranges
the ranges list
unsigned int mask
the bit-mask to evaluate

Description

Refines the interval value from the list of ranges. When mask is non-zero, only the elements corresponding to bit 1 are evaluated.

Return

Positive if the value is changed, zero if it’s not changed, or a negative error code.

int snd_pcm_hw_rule_add(struct snd_pcm_runtime * runtime, unsigned int cond, int var, snd_pcm_hw_rule_func_t func, void * private, int dep, ...)

add the hw-constraint rule

Parameters

struct snd_pcm_runtime * runtime
the pcm runtime instance
unsigned int cond
condition bits
int var
the variable to evaluate
snd_pcm_hw_rule_func_t func
the evaluation function
void * private
the private data pointer passed to function
int dep
the dependent variables
...
variable arguments

Return

Zero if successful, or a negative error code on failure.

int snd_pcm_hw_constraint_mask64(struct snd_pcm_runtime * runtime, snd_pcm_hw_param_t var, u_int64_t mask)

apply the given bitmap mask constraint

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
snd_pcm_hw_param_t var
hw_params variable to apply the mask
u_int64_t mask
the 64bit bitmap mask

Description

Apply the constraint of the given bitmap mask to a 64-bit mask parameter.

Return

Zero if successful, or a negative error code on failure.

int snd_pcm_hw_constraint_integer(struct snd_pcm_runtime * runtime, snd_pcm_hw_param_t var)

apply an integer constraint to an interval

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
snd_pcm_hw_param_t var
hw_params variable to apply the integer constraint

Description

Apply the constraint of integer to an interval parameter.

Return

Positive if the value is changed, zero if it’s not changed, or a negative error code.

int snd_pcm_hw_constraint_minmax(struct snd_pcm_runtime * runtime, snd_pcm_hw_param_t var, unsigned int min, unsigned int max)

apply a min/max range constraint to an interval

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
snd_pcm_hw_param_t var
hw_params variable to apply the range
unsigned int min
the minimal value
unsigned int max
the maximal value

Description

Apply the min/max range constraint to an interval parameter.

Return

Positive if the value is changed, zero if it’s not changed, or a negative error code.

int snd_pcm_hw_constraint_list(struct snd_pcm_runtime * runtime, unsigned int cond, snd_pcm_hw_param_t var, const struct snd_pcm_hw_constraint_list * l)

apply a list of constraints to a parameter

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
unsigned int cond
condition bits
snd_pcm_hw_param_t var
hw_params variable to apply the list constraint
const struct snd_pcm_hw_constraint_list * l
list

Description

Apply the list of constraints to an interval parameter.

Return

Zero if successful, or a negative error code on failure.

int snd_pcm_hw_constraint_ranges(struct snd_pcm_runtime * runtime, unsigned int cond, snd_pcm_hw_param_t var, const struct snd_pcm_hw_constraint_ranges * r)

apply list of range constraints to a parameter

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
unsigned int cond
condition bits
snd_pcm_hw_param_t var
hw_params variable to apply the list of range constraints
const struct snd_pcm_hw_constraint_ranges * r
ranges

Description

Apply the list of range constraints to an interval parameter.

Return

Zero if successful, or a negative error code on failure.

int snd_pcm_hw_constraint_ratnums(struct snd_pcm_runtime * runtime, unsigned int cond, snd_pcm_hw_param_t var, const struct snd_pcm_hw_constraint_ratnums * r)

apply ratnums constraint to a parameter

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
unsigned int cond
condition bits
snd_pcm_hw_param_t var
hw_params variable to apply the ratnums constraint
const struct snd_pcm_hw_constraint_ratnums * r
struct snd_ratnums constriants

Return

Zero if successful, or a negative error code on failure.

int snd_pcm_hw_constraint_ratdens(struct snd_pcm_runtime * runtime, unsigned int cond, snd_pcm_hw_param_t var, const struct snd_pcm_hw_constraint_ratdens * r)

apply ratdens constraint to a parameter

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
unsigned int cond
condition bits
snd_pcm_hw_param_t var
hw_params variable to apply the ratdens constraint
const struct snd_pcm_hw_constraint_ratdens * r
struct snd_ratdens constriants

Return

Zero if successful, or a negative error code on failure.

int snd_pcm_hw_constraint_msbits(struct snd_pcm_runtime * runtime, unsigned int cond, unsigned int width, unsigned int msbits)

add a hw constraint msbits rule

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
unsigned int cond
condition bits
unsigned int width
sample bits width
unsigned int msbits
msbits width

Description

This constraint will set the number of most significant bits (msbits) if a sample format with the specified width has been select. If width is set to 0 the msbits will be set for any sample format with a width larger than the specified msbits.

Return

Zero if successful, or a negative error code on failure.

int snd_pcm_hw_constraint_step(struct snd_pcm_runtime * runtime, unsigned int cond, snd_pcm_hw_param_t var, unsigned long step)

add a hw constraint step rule

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
unsigned int cond
condition bits
snd_pcm_hw_param_t var
hw_params variable to apply the step constraint
unsigned long step
step size

Return

Zero if successful, or a negative error code on failure.

int snd_pcm_hw_constraint_pow2(struct snd_pcm_runtime * runtime, unsigned int cond, snd_pcm_hw_param_t var)

add a hw constraint power-of-2 rule

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
unsigned int cond
condition bits
snd_pcm_hw_param_t var
hw_params variable to apply the power-of-2 constraint

Return

Zero if successful, or a negative error code on failure.

int snd_pcm_hw_rule_noresample(struct snd_pcm_runtime * runtime, unsigned int base_rate)

add a rule to allow disabling hw resampling

Parameters

struct snd_pcm_runtime * runtime
PCM runtime instance
unsigned int base_rate
the rate at which the hardware does not resample

Return

Zero if successful, or a negative error code on failure.

int snd_pcm_hw_param_value(const struct snd_pcm_hw_params * params, snd_pcm_hw_param_t var, int * dir)

return params field var value

Parameters

const struct snd_pcm_hw_params * params
the hw_params instance
snd_pcm_hw_param_t var
parameter to retrieve
int * dir
pointer to the direction (-1,0,1) or NULL

Return

The value for field var if it’s fixed in configuration space defined by params. -EINVAL otherwise.

int snd_pcm_hw_param_first(struct snd_pcm_substream * pcm, struct snd_pcm_hw_params * params, snd_pcm_hw_param_t var, int * dir)

refine config space and return minimum value

Parameters

struct snd_pcm_substream * pcm
PCM instance
struct snd_pcm_hw_params * params
the hw_params instance
snd_pcm_hw_param_t var
parameter to retrieve
int * dir
pointer to the direction (-1,0,1) or NULL

Description

Inside configuration space defined by params remove from var all values > minimum. Reduce configuration space accordingly.

Return

The minimum, or a negative error code on failure.

int snd_pcm_hw_param_last(struct snd_pcm_substream * pcm, struct snd_pcm_hw_params * params, snd_pcm_hw_param_t var, int * dir)

refine config space and return maximum value

Parameters

struct snd_pcm_substream * pcm
PCM instance
struct snd_pcm_hw_params * params
the hw_params instance
snd_pcm_hw_param_t var
parameter to retrieve
int * dir
pointer to the direction (-1,0,1) or NULL

Description

Inside configuration space defined by params remove from var all values < maximum. Reduce configuration space accordingly.

Return

The maximum, or a negative error code on failure.

int snd_pcm_lib_ioctl(struct snd_pcm_substream * substream, unsigned int cmd, void * arg)

a generic PCM ioctl callback

Parameters

struct snd_pcm_substream * substream
the pcm substream instance
unsigned int cmd
ioctl command
void * arg
ioctl argument

Description

Processes the generic ioctl commands for PCM. Can be passed as the ioctl callback for PCM ops.

Return

Zero if successful, or a negative error code on failure.

void snd_pcm_period_elapsed(struct snd_pcm_substream * substream)

update the pcm status for the next period

Parameters

struct snd_pcm_substream * substream
the pcm substream instance

Description

This function is called from the interrupt handler when the PCM has processed the period size. It will update the current pointer, wake up sleepers, etc.

Even if more than one periods have elapsed since the last call, you have to call this only once.

int snd_pcm_add_chmap_ctls(struct snd_pcm * pcm, int stream, const struct snd_pcm_chmap_elem * chmap, int max_channels, unsigned long private_value, struct snd_pcm_chmap ** info_ret)

create channel-mapping control elements

Parameters

struct snd_pcm * pcm
the assigned PCM instance
int stream
stream direction
const struct snd_pcm_chmap_elem * chmap
channel map elements (for query)
int max_channels
the max number of channels for the stream
unsigned long private_value
the value passed to each kcontrol’s private_value field
struct snd_pcm_chmap ** info_ret
store struct snd_pcm_chmap instance if non-NULL

Description

Create channel-mapping control elements assigned to the given PCM stream(s).

Return

Zero if successful, or a negative error value.

int snd_hwdep_new(struct snd_card * card, char * id, int device, struct snd_hwdep ** rhwdep)

create a new hwdep instance

Parameters

struct snd_card * card
the card instance
char * id
the id string
int device
the device index (zero-based)
struct snd_hwdep ** rhwdep
the pointer to store the new hwdep instance

Description

Creates a new hwdep instance with the given index on the card. The callbacks (hwdep->ops) must be set on the returned instance after this call manually by the caller.

Return

Zero if successful, or a negative error code on failure.

void snd_pcm_stream_lock(struct snd_pcm_substream * substream)

Lock the PCM stream

Parameters

struct snd_pcm_substream * substream
PCM substream

Description

This locks the PCM stream’s spinlock or mutex depending on the nonatomic flag of the given substream. This also takes the global link rw lock (or rw sem), too, for avoiding the race with linked streams.

void snd_pcm_stream_unlock(struct snd_pcm_substream * substream)

Unlock the PCM stream

Parameters

struct snd_pcm_substream * substream
PCM substream

Description

This unlocks the PCM stream that has been locked via snd_pcm_stream_lock().

void snd_pcm_stream_lock_irq(struct snd_pcm_substream * substream)

Lock the PCM stream

Parameters

struct snd_pcm_substream * substream
PCM substream

Description

This locks the PCM stream like snd_pcm_stream_lock() and disables the local IRQ (only when nonatomic is false). In nonatomic case, this is identical as snd_pcm_stream_lock().

void snd_pcm_stream_unlock_irq(struct snd_pcm_substream * substream)

Unlock the PCM stream

Parameters

struct snd_pcm_substream * substream
PCM substream

Description

This is a counter-part of snd_pcm_stream_lock_irq().

void snd_pcm_stream_unlock_irqrestore(struct snd_pcm_substream * substream, unsigned long flags)

Unlock the PCM stream

Parameters

struct snd_pcm_substream * substream
PCM substream
unsigned long flags
irq flags

Description

This is a counter-part of snd_pcm_stream_lock_irqsave().

int snd_pcm_stop(struct snd_pcm_substream * substream, snd_pcm_state_t state)

try to stop all running streams in the substream group

Parameters

struct snd_pcm_substream * substream
the PCM substream instance
snd_pcm_state_t state
PCM state after stopping the stream

Description

The state of each stream is then changed to the given state unconditionally.

Return

Zero if successful, or a negative error code.

int snd_pcm_stop_xrun(struct snd_pcm_substream * substream)

stop the running streams as XRUN

Parameters

struct snd_pcm_substream * substream
the PCM substream instance

Description

This stops the given running substream (and all linked substreams) as XRUN. Unlike snd_pcm_stop(), this function takes the substream lock by itself.

Return

Zero if successful, or a negative error code.

int snd_pcm_suspend_all(struct snd_pcm * pcm)

trigger SUSPEND to all substreams in the given pcm

Parameters

struct snd_pcm * pcm
the PCM instance

Description

After this call, all streams are changed to SUSPENDED state.

Return

Zero if successful (or pcm is NULL), or a negative error code.

int snd_pcm_kernel_ioctl(struct snd_pcm_substream * substream, unsigned int cmd, void * arg)

Execute PCM ioctl in the kernel-space

Parameters

struct snd_pcm_substream * substream
PCM substream
unsigned int cmd
IOCTL cmd
void * arg
IOCTL argument

Description

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).

int snd_pcm_lib_default_mmap(struct snd_pcm_substream * substream, struct vm_area_struct * area)

Default PCM data mmap function

Parameters

struct snd_pcm_substream * substream
PCM substream
struct vm_area_struct * area
VMA

Description

This is the default mmap handler for PCM data. When mmap pcm_ops is NULL, this function is invoked implicitly.

int snd_pcm_lib_mmap_iomem(struct snd_pcm_substream * substream, struct vm_area_struct * area)

Default PCM data mmap function for I/O mem

Parameters

struct snd_pcm_substream * substream
PCM substream
struct vm_area_struct * area
VMA

Description

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.

int snd_dma_alloc_pages(int type, struct device * device, size_t size, struct snd_dma_buffer * dmab)

allocate the buffer area according to the given type

Parameters

int type
the DMA buffer type
struct device * device
the device pointer
size_t size
the buffer size to allocate
struct snd_dma_buffer * dmab
buffer allocation record to store the allocated data

Description

Calls the memory-allocator function for the corresponding buffer type.

Return

Zero if the buffer with the given size is allocated successfully, otherwise a negative value on error.

int snd_dma_alloc_pages_fallback(int type, struct device * device, size_t size, struct snd_dma_buffer * dmab)

allocate the buffer area according to the given type with fallback

Parameters

int type
the DMA buffer type
struct device * device
the device pointer
size_t size
the buffer size to allocate
struct snd_dma_buffer * dmab
buffer allocation record to store the allocated data

Description

Calls the memory-allocator function for the corresponding buffer type. When no space is left, this function reduces the size and tries to allocate again. The size actually allocated is stored in res_size argument.

Return

Zero if the buffer with the given size is allocated successfully, otherwise a negative value on error.

void snd_dma_free_pages(struct snd_dma_buffer * dmab)

release the allocated buffer

Parameters

struct snd_dma_buffer * dmab
the buffer allocation record to release

Description

Releases the allocated buffer via snd_dma_alloc_pages().