Linux Sound Documentation The kernel development community Jul 14, 2020 CONTENTS i ii CHAPTER ONE ALSA KERNEL API DOCUMENTATION 1.1 The ALSA Driver API 1.1.1 Management of Cards and Devices Card Management 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 mod- ule * 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 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 1 Linux Sound Documentation 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 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 im- mediately, 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 auto- matically. That is, you don’t have to release the devices by yourself. 2 Chapter 1. ALSA Kernel API Documentation Linux Sound Documentation 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 This function sets the card identification and checks for name collisions. int snd_card_add_dev_attr(struct snd_card * card, const struct at- tribute_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 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 This function adds the component id string to the supported list. The compo- nent 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 1.1. The ALSA Driver API 3 Linux Sound Documentation struct file * file file pointer 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 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 Waits until the power-state is changed. Return Zero if successful, or a negative error code. Device Components 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. 4 Chapter 1. ALSA Kernel API Documentation Linux Sound Documentation 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_device_get_state(struct snd_card * card, void * device_data) Get the current state of the given device Parameters 1.1. The ALSA Driver API 5 Linux Sound Documentation struct snd_card * card the card instance void * device_data the data pointer to release Description Returns the current state of the given device object. For the valid device, either SNDRV_DEV_BUILD, SNDRV_DEV_REGISTERED or SNDRV_DEV_DISCONNECTED is returned. Or for a non-existing device, -1 is returned as an error. Module requests and Device File Entries 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 re- quest_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 associ- ated 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