Sound Devices¶

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_midi(const struct file_operations * fops, int dev)¶: register a midi device

Parameters

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

Description

Allocate a midi device. Unit is the number of the midi device requested. Pass -1 to request the next free midi 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_midi(int unit)¶: unregister a midi device

Parameters

int unit: unit number to allocate

Description

Release a sound device that was allocated with register_sound_midi(). 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 timespec * tv)¶: Fill the timespec depending on the timestamp mode

Parameters

struct snd_pcm_runtime * runtime: PCM runtime instance
struct timespec * tv: timespec 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, 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
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.

Return

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

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_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->:c:func: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.

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

Return

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

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

Return

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

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

Return

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

struct page * snd_pcm_sgbuf_ops_page(struct snd_pcm_substream * substream, unsigned long offset)¶: get the page struct at the given offset

Parameters

struct snd_pcm_substream * substream: the pcm substream instance
unsigned long offset: the buffer offset

Description

Used as the page callback of PCM ops.

Return

The page struct at the given buffer offset. NULL on failure.

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.

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

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(struct snd_pcm_substream * substream)¶: trigger SUSPEND to all linked streams

Parameters

struct snd_pcm_substream * substream: the PCM substream

Description

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

Return

Zero if successful (or substream is NULL), 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.

void * snd_malloc_pages(size_t size, gfp_t gfp_flags)¶: allocate pages with the given size

Parameters

size_t size: the size to allocate in bytes
gfp_t gfp_flags: the allocation conditions, GFP_XXX

Description

Allocates the physically contiguous pages with the given size.

Return

The pointer of the buffer, or NULL if no enough memory.

void snd_free_pages(void * ptr, size_t size)¶: release the pages

Parameters

void * ptr: the buffer pointer to release
size_t size: the allocated buffer size

Description

Releases the buffer allocated via snd_malloc_pages().

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