Alsa driver documentation pdf

This stops the given running substream and all linked substreams as XRUN. Zero if successful or substream is NULL , or a negative error code. Zero if successful or pcm is NULL , or a negative error code. This is the default mmap handler for PCM data. Note that this is supposed to work only on limited architectures. Iterate over the all linked substreams to the given substream. Non-zero if any data exists, or zero if not.

Then most of trigger operations are performed only to the given master substream. Otherwise it clears the current buffer information. Allocates the PCM substream buffer using vmalloc , i. Use this if the buffer is accessed by kernel code but not by device DMA. The format pattern to fill or NULL if error. This function computes the rates that are supported by both rate masks passed to the function.

This function has an implicit assumption: the rates in the given range have only the pre-defined rates like or The page struct at the given buffer offset. NULL on failure. The page struct, or NULL on failure. The src and dst fields will be initialized depending on the direction of the substream. If the substream is a playback stream the dst fields will be initialized, if it is a capture stream the src fields will be initialized.

If both conditions are met the latter takes priority. This function is deprecated and should not be used by new drivers, as its results may be unreliable.

The function should usually be called from the pcm open callback. So it is not available to your pcm driver implementation. This function will request a DMA channel using the passed filter function and data. 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. Allocates a memory object for a new control instance. The instance has elements as many as the given number count. Each element has given access permissions access. Each element is locked when file is given.

The pointer of the newly generated instance, or NULL on failure. Assigns also an unique numid used for fast search. Replaces the given control. If the control exists, it is destroyed first. Removes the control from the card and then releases the instance.

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. The pointer of the instance if found, or NULL if not. This is a function that can be used as info callback for a standard boolean control with a single mono channel. This is a function that can be used as info callback for a standard boolean control with stereo two channels.

Sets all required fields in info to their appropriate values. Writes a value on the given register. This will invoke the write callback directly after the register check. Reads a value from the given register. This will invoke the read callback directly after the register check.

Writes a value on the given register and updates the register cache. Creates an AC97 bus component. The ops table must include valid callbacks at least read and write. The other callbacks, wait and reset, are not mandatory. The clock is set to Creates an Codec97 component. The codec is then initialized by the standard procedure. The quirk-list must be terminated with a zero-filled entry. Installs the hardware constraint rules to prevent using double rates and more than two channels at the same time.

The optional argument tlv can be used to specify the TLV information for dB scale of the master control. Forcibly call the put callback of each slave and call the hook function to synchronize with the current value of the given vmaster element.

Apply the function func to each slave kctl of the given vmaster kctl. Returns 0 if successful, or a negative error code. All slaves must be the same type returning the same information via info callback. Also, some additional limitations: at most two channels, logarithmic volume control dB level thus no linear volume, master can only attenuate the volume without gain.

Add a virtual slave control to the given master. When the control peeks the hardware values directly and the value can be changed by other means than the put callback of the element, this function should be used to keep the value always up-to-date.

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

Note that the rawmidi instance is returned on the rrawmidi argument, not the mpu instance itself. The pointer of the new instance, or NULL on failure. To make the API simpler, it is assumed that the user will select quality profiles.

Additional options that affect encoding quality and speed can be added at a later stage if needed. Otherwise the behavior is undefined. This function must only be used on components that are known to be platforms. This function must only be used on DAPM contexts that are known to be part of a component e.

This function must only be used on DAPM contexts that are known to be part of a platform e. This function will work correctly if the control has been registered for a component. Since DAI links may not have their unique ID, so name and stream name should also match if being specified. For DAI links previously added by topology, topology should remove them by using the dobj embedded in the link.

An Intel machine driver may be used by many different devices but are difficult for userspace to differentiate, since machine drivers ususally use their own name as the card short name and leave the card long name blank.

Possible card long names may be: DellInc. We only keep number and alphabet characters and a few separator characters in the card long name since UCM in the user space uses the card long names as card configuration directory names and AudoConf cannot support special charactors like SPACE. Convenience function to add a list of controls. First one has a function: After manually loading the modules, the output of lsmod is:. That I can tell — I hate mail-lists, they are the worst to read through.

Instantiated device udacodec at 0x1a Then I try to bind a driver to the device: There was also no support for saving power via changing codec oversampling rates, bias currents, etc.

You can list the available audio sinks with the following command:. By using our site, you acknowledge that you have read and understand our Cookie PolicyPrivacy Policyand our Terms of Service. Sign up using Facebook. It was late and hard to remember my steps, but I was able to at least get the following error somehow:.

You can list the available audio sinks with the following command: There are a lot of other options but I guess these ones are the exactly what you need. There was no standard method to signal zsoc initiated audio events e. The ALSA utilities package alsa-utils also offers user space applications:.

When you are in the omap3beagle. Does this mean I must now make a new device called udacodec at address 0x1a and bind it to a driver? In any case, I have no idea where the I2S stuff is set in the kernel code. Apsa Embedded Yocto version 2. This is fine for a PC, but tends to waste a lot of power on portable devices.

Codec class drivers should be slsa code that can run on any architecture and machine. I posted to alsa-devel and zlsa responded. The interrupt handler looks usually like the following:. The role of destructor is simple: disable the hardware if already activated and release the resources. So far, we have no hardware part, so the disabling code is not written here. For the interrupt, do like this:.

If you need to do this, please note that the destructor may be called even before the initialization of the chip is completed. It would be better to have a flag to skip hardware disabling if the hardware was not initialized yet. That is, it is assured that all other components like PCMs and controls have already been released. So far, so good. If you have no reason to filter the matching devices, you can leave the remaining fields as above.

You can specify any value here, for example, to define specific operations for supported device IDs. Such an example is found in the intel8x0 driver. The probe and remove functions have already been defined in the previous sections. The name field is the name string of this device. The PCM middle layer of ALSA is quite powerful and it is only necessary for each driver to implement the low-level functions to access its hardware.

Each card device can have up to four pcm instances. A pcm instance corresponds to a pcm device file. A pcm instance consists of pcm playback and capture streams, and each pcm stream consists of one or more pcm substreams. Some soundcards support multiple playback functions. For example, emu10k1 has a PCM playback of 32 stereo substreams. In this case, at each open, a free substream is usually automatically chosen and opened. Meanwhile, when only one substream exists and it was already opened, the successful open will either block or error with EAGAIN according to the file open mode.

The PCM middle layer will take care of such work. The example code below does not include any hardware access routines but shows only the skeleton, how to build up the PCM interfaces.

It would be better to create a constructor for pcm, namely,. The first argument is the card pointer to which this pcm is assigned, and the second is the ID string. The third argument index , 0 in the above is the index of this new pcm.

It begins from zero. If you create more than one pcm instances, specify the different numbers in this argument. The fourth and fifth arguments are the number of substreams for playback and capture, respectively.

Here 1 is used for both arguments. When no playback or capture substreams are available, pass 0 to the corresponding argument. All the callbacks are described in the Operators subsection. After setting the operators, you probably will want to pre-allocate the buffer and set up the managed allocation mode. For that, simply call the following:. It will allocate a buffer up to 64kB as default. Buffer management details will be described in the later section Buffer and Memory Management.

When your soundchip supports only half-duplex, specify like this:. The destructor for a pcm instance is not always necessary. The destructor would be necessary if you created special records internally and needed to release them. Here are the contents of this file:. For the operators callbacks of each sound driver, most of these records are supposed to be read-only.

The exceptions are the hardware description hw DMA buffer information and the private data. Note that the runtime instance holds the copy of the descriptor, not the pointer to the existing descriptor.

The info field contains the type and capabilities of this pcm. Here, at least, you have to specify whether the mmap is supported and which interleaved format is supported. If both are supported, you can set both, too. Usually both are set. See Power Management section for details. This will be described in the later section. In the example above, the signed 16bit little-endian format is specified. The pre-defined rate bits are provided only for typical rates. If your chip supports unconventional rates, you need to add the KNOT bit and set up the hardware constraint manually explained later.

This should correspond somehow to rates bits. The period defines the size at which a PCM interrupt is generated. This size strongly depends on the hardware. Generally, the smaller period size will give you more interrupts, that is, more controls.

In the case of capture, this size defines the input latency. On the other hand, the whole buffer size defines the output latency for the playback direction.

This specifies the size of the hardware FIFO, but currently it is neither used in the driver nor in the alsa-lib. So, you can ignore this field. The most frequently referred records in the runtime instance are the PCM configurations. For example, format holds the format type chosen by the application. Please check the type of the field. This field is specified only when the buffer is a linear buffer. You can read them but not write them. However, accessing directly to this value is not recommended.

Usually, this is done in the PCM open callback. The allocated object must be released in the close callback. OK, now let me give details about each pcm callback ops. To choose an appropriate error number, it is advised to check what value other parts of the kernel return when the same kind of request fails. To retrieve the chip record from the given substream instance, you can use the following macro.

You can override the former if you need to assign different data records per PCM substream. Typically, this is done by like this:. You can allocate a private data in this callback, as described in Private Data section. If the hardware configuration needs more constraints, set the hardware constraints here, too. See Constraints for more details. Any private instance for a pcm substream allocated in the open callback will be released here.

This is used for any special call to pcm ioctls. If you need to deal with the unique setup of channel info or reset procedure, you can pass your own callback function here. When you set up the managed buffer allocation mode for the substream, a buffer is already allocated before this callback gets called.

Alternatively, you can call a helper function below for allocating the buffer, too. See the section Buffer Types for more details. Note that this and prepare callbacks may be called multiple times per initialization.

For example, the OSS emulation may call these callbacks at each change via its ioctl. Thus, you need to be careful not to allocate the same buffers many times, which will lead to memory leaks! Calling the helper function above many times is OK. It will release the previous buffer automatically when it was already allocated.

Another note is that this callback is non-atomic schedulable as default, i. This is important, because the trigger callback is atomic non-schedulable. That is, mutexes or any schedule-related functions are not available in trigger callback. Please see the subsection Atomicity for details. This function is always called before the close callback is called. Also, the callback may be called multiple times, too.

Keep track whether the resource was already released. When you have set up the managed buffer allocation mode for the PCM substream, the allocated PCM buffer will be automatically released after this callback gets called.

You can set the format type, sample rate, etc. Note that this callback is now non-atomic. You can use schedule-related functions safely in this callback. The former is the command to pause the pcm, and the latter to restart the pcm again. These commands are issued when the power-management status is changed. See the Power Management section for details. As mentioned, this callback is atomic as default unless nonatomic flag set, and you cannot call functions which may sleep. The trigger callback should be as minimal as possible, just really triggering the DMA.

This callback is optional, and NULL can be passed. Since the IRQ handler might be still pending, we need to wait until the pending task finishes before moving to the next step; otherwise it might lead to a crash due to resource conflicts or access to the freed resources. When the driver frees and re-acquires the IRQ dynamically e. This callback is called when the PCM middle layer inquires the current hardware position on the buffer. Then the pcm middle layer updates the position and calculates the available space, and wakes up the sleeping poll threads, etc.

These callbacks are not mandatory, and can be omitted in most cases. These callbacks are used when the hardware buffer cannot be in the normal memory space.

Some chips have their own buffer on the hardware which is not mappable. In such a case, you have to transfer the data manually from the memory buffer to the hardware buffer. Or, if the buffer is non-contiguous on both physical and virtual memory spaces, these callbacks must be defined, too.

If these two callbacks are defined, copy and set-silence operations are done by them. The detailed will be described in the later section Buffer and Memory Management.

This callback is also not mandatory. Since the recent changes, you need no special callback any longer for the standard SG-buffer or vmalloc-buffer. Hence this callback should be rarely used. This is another optional callback for controlling mmap behavior. Once when defined, PCM core calls this callback when a page is memory-mapped instead of dealing via the standard helper.

If you need special handling due to some architecture or device-specific issues , implement everything here as you like. The rest of pcm stuff is the PCM interrupt handler.

The role of PCM interrupt handler in the sound driver is to update the buffer position and to tell the PCM middle layer when the buffer position goes across the prescribed period size.

This is the most frequently found type: the hardware generates an interrupt at each period boundary. Thus, you need to keep the substream pointer accessible from the chip instance. For example, define substream field in the chip record to hold the current running substream pointer, and set the pointer value at open callback and reset at close callback.

In this case, you need to check the current hardware position and accumulate the processed sample length at each interrupt. Call only once.

And the pcm layer will check the current hardware pointer and update to the latest status. One of the most important and thus difficult to debug problems in kernel programming are race conditions. In the Linux kernel, they are usually avoided via spin-locks, mutexes or semaphores. In general, if a race condition can happen in an interrupt handler, it has to be managed atomically, and you have to use a spinlock to protect the critical session. If the critical section is not in interrupt handler code and if taking a relatively long time to execute is acceptable, you should use mutexes or semaphores instead.

As already seen, some pcm callbacks are atomic and some are not. This means, the latter is called already in a spinlock held by the PCM middle layer. Please take this atomicity into account when you choose a locking scheme in the callbacks.

In the atomic callbacks, you cannot use functions which may call schedule or go to sleep. Semaphores and mutexes can sleep, and hence they cannot be used inside the atomic callbacks e.

To implement some delay in such a callback, please use udelay or mdelay. All three atomic callbacks trigger, pointer, and ack are called with local interrupts disabled.