Update of /cvsroot/alsa/alsa-kernel/core
In directory sc8-pr-cvs1:/tmp/cvs-serv10822/core
Modified Files:
control.c device.c hwdep.c info.c init.c isadma.c memory.c
pcm.c pcm_lib.c pcm_memory.c pcm_misc.c pcm_native.c
pcm_sgbuf.c rawmidi.c sound.c
Log Message:
[PATCH: kerneldoc-comments.dif]
- added/corrected kernel-doc style comments.
Index: control.c
===================================================================
RCS file: /cvsroot/alsa/alsa-kernel/core/control.c,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -r1.25 -r1.26
--- control.c 7 Jan 2003 10:25:26 -0000 1.25
+++ control.c 7 Jan 2003 12:27:45 -0000 1.26
@@ -169,6 +169,15 @@
read_unlock(&card->ctl_files_rwlock);
}
+/**
+ * snd_ctl_new - create a control instance from the template
+ * @control: the control template
+ *
+ * Allocates a new snd_kcontrol_t instance and copies the given template
+ * to the new instance.
+ *
+ * Returns the pointer of the new instance, or NULL on failure.
+ */
snd_kcontrol_t *snd_ctl_new(snd_kcontrol_t * control)
{
snd_kcontrol_t *kctl;
@@ -181,6 +190,17 @@
return kctl;
}
+/**
+ * snd_ctl_new1 - create a control instance from the template
+ * @ncontrol: the initialization record
+ * @private_data: the private data to set
+ *
+ * Allocates a new snd_kcontrol_t instance and initialize from the given
+ * template. When the access field of ncontrol is 0, it's assumed as
+ * READWRITE access.
+ *
+ * Returns the pointer of the newly generated instance, or NULL on failure.
+ */
snd_kcontrol_t *snd_ctl_new1(snd_kcontrol_new_t * ncontrol, void *private_data)
{
snd_kcontrol_t kctl;
@@ -203,6 +223,14 @@
return snd_ctl_new(&kctl);
}
+/**
+ * snd_ctl_free_one - release the control instance
+ * @kcontrol: the control instance
+ *
+ * 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.
+ */
void snd_ctl_free_one(snd_kcontrol_t * kcontrol)
{
if (kcontrol) {
@@ -212,6 +240,16 @@
}
}
+/**
+ * snd_ctl_add - add the control instance to the card
+ * @card: the card instance
+ * @kcontrol: the control instance to add
+ *
+ * Adds the control instance created via snd_ctl_new() or
+ * snd_ctl_new1() to the given card.
+ *
+ * Returns zero if successful, or a negative error code on failure.
+ */
int snd_ctl_add(snd_card_t * card, snd_kcontrol_t * kcontrol)
{
snd_runtime_check(card != NULL && kcontrol != NULL, return -EINVAL);
@@ -227,6 +265,16 @@
return 0;
}
+/**
+ * snd_ctl_remove - remove the control from the card and release it
+ * @card: the card instance
+ * @kcontrol: the control instance to remove
+ *
+ * Removes the control from the card and then releases the instance.
+ * You don't need to call snd_ctl_free_one().
+ *
+ * Returns 0 if successful, or a negative error code on failure.
+ */
int snd_ctl_remove(snd_card_t * card, snd_kcontrol_t * kcontrol)
{
snd_runtime_check(card != NULL && kcontrol != NULL, return -EINVAL);
@@ -239,6 +287,16 @@
return 0;
}
+/**
+ * snd_ctl_remove_id - remove the control of the given id and release it
+ * @card: the card instance
+ * @id: the control id to remove
+ *
+ * Finds the control instance with the given id, removes it from the
+ * card list and releases it.
+ *
+ * Returns 0 if successful, or a negative error code on failure.
+ */
int snd_ctl_remove_id(snd_card_t * card, snd_ctl_elem_id_t *id)
{
snd_kcontrol_t *kctl;
@@ -251,6 +309,17 @@
static snd_kcontrol_t *_ctl_find_id(snd_card_t * card, snd_ctl_elem_id_t *id); /* w/o
lock */
+/**
+ * snd_ctl_rename_id - replace the id of a control on the card
+ * @card: the card instance
+ * @src_id: the old id
+ * @dst_id: the new id
+ *
+ * Finds the control with the old id from the card, and replaces the
+ * id with the new one.
+ *
+ * Returns zero if successful, or a negative error code on failure.
+ */
int snd_ctl_rename_id(snd_card_t * card, snd_ctl_elem_id_t *src_id, snd_ctl_elem_id_t
*dst_id)
{
snd_kcontrol_t *kctl;
@@ -306,7 +375,15 @@
return NULL;
}
-/* exported: with read lock */
+/**
+ * snd_ctl_find_id - find the control instance with the given id
+ * @card: the card instance
+ * @id: the id to search
+ *
+ * Finds the control instance with the given id from the card.
+ *
+ * Returns the pointer of the instance if found, or NULL if not.
+ */
snd_kcontrol_t *snd_ctl_find_id(snd_card_t * card, snd_ctl_elem_id_t *id)
{
snd_kcontrol_t *kctl;
@@ -316,7 +393,15 @@
return kctl;
}
-/* exported: with read lock */
+/**
+ * snd_ctl_find_numid - find the control instance with the given number-id
+ * @card: the card instance
+ * @numid: the number-id to search
+ *
+ * Finds the control instance with the given number-id from the card.
+ *
+ * Returns the pointer of the instance if found, or NULL if not.
+ */
snd_kcontrol_t *snd_ctl_find_numid(snd_card_t * card, unsigned int numid)
{
snd_kcontrol_t *kctl;
@@ -729,6 +814,10 @@
return mask;
}
+/*
+ * register the device-specific control-ioctls.
+ * called from each device manager like pcm.c, hwdep.c, etc.
+ */
int snd_ctl_register_ioctl(snd_kctl_ioctl_func_t fcn)
{
snd_kctl_ioctl_t *pn;
@@ -744,6 +833,9 @@
return 0;
}
+/*
+ * de-register the device-specific control-ioctls.
+ */
int snd_ctl_unregister_ioctl(snd_kctl_ioctl_func_t fcn)
{
struct list_head *list;
@@ -799,6 +891,10 @@
.f_ops = &snd_ctl_f_ops,
};
+/*
+ * registration of the control device:
+ * called from init.c
+ */
int snd_ctl_register(snd_card_t *card)
{
int err, cardnum;
@@ -814,6 +910,10 @@
return 0;
}
+/*
+ * disconnection of the control device:
+ * called from init.c
+ */
int snd_ctl_disconnect(snd_card_t *card)
{
struct list_head *flist;
@@ -829,6 +929,10 @@
return 0;
}
+/*
+ * de-registration of the control device:
+ * called from init.c
+ */
int snd_ctl_unregister(snd_card_t *card)
{
int err, cardnum;
Index: device.c
===================================================================
RCS file: /cvsroot/alsa/alsa-kernel/core/device.c,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- device.c 29 Nov 2002 21:22:24 -0000 1.12
+++ device.c 7 Jan 2003 12:27:45 -0000 1.13
@@ -25,6 +25,22 @@
#include <linux/errno.h>
#include <sound/core.h>
+/**
+ * snd_device_new - create an ALSA device component
+ * @card: the card instance
+ * @type: the device type, SNDRV_DEV_TYPE_XXX
+ * @device_data: the data pointer of this device
+ * @ops: the operator table
+ *
+ * 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.
+ *
+ * Returns zero if successful, or a negative error code on failure.
+ */
int snd_device_new(snd_card_t *card, snd_device_type_t type,
void *device_data, snd_device_ops_t *ops)
{
@@ -43,6 +59,18 @@
return 0;
}
+/**
+ * snd_device_free - release the device from the card
+ * @card: the card instance
+ * @device_data: the data pointer to release
+ *
+ * Removes the device from the list on the card and invokes the
+ * callback, dev_unregister or dev_free, corresponding to the state.
+ * Then release the device.
+ *
+ * Returns zero if successful, or a negative error code on failure or if the
+ * device not found.
+ */
int snd_device_free(snd_card_t *card, void *device_data)
{
struct list_head *list;
@@ -73,6 +101,19 @@
return -ENXIO;
}
+/**
+ * snd_device_free - disconnect the device
+ * @card: the card instance
+ * @device_data: the data pointer to disconnect
+ *
+ * Turns the device into the disconnection state, invoking
+ * dev_disconnect callback, if the device was already registered.
+ *
+ * Usually called from snd_card_disconnect().
+ *
+ * Returns zero if successful, or a negative error code on failure or if the
+ * device not found.
+ */
int snd_device_disconnect(snd_card_t *card, void *device_data)
{
struct list_head *list;
@@ -95,6 +136,19 @@
return -ENXIO;
}
+/**
+ * snd_device_register - register the device
+ * @card: the card instance
+ * @device_data: the data pointer to register
+ *
+ * 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
+ * invokation of snd_card_register().
+ *
+ * Returns zero if successful, or a negative error code on failure or if the
+ * device not found.
+ */
int snd_device_register(snd_card_t *card, void *device_data)
{
struct list_head *list;
@@ -118,6 +172,10 @@
return -ENXIO;
}
+/*
+ * register all the devices on the card.
+ * called from init.c
+ */
int snd_device_register_all(snd_card_t *card)
{
struct list_head *list;
@@ -136,6 +194,10 @@
return 0;
}
+/*
+ * disconnect all the devices on the card.
+ * called from init.c
+ */
int snd_device_disconnect_all(snd_card_t *card)
{
snd_device_t *dev;
@@ -151,6 +213,10 @@
return err;
}
+/*
+ * release all the devices on the card.
+ * called from init.c
+ */
int snd_device_free_all(snd_card_t *card, snd_device_cmd_t cmd)
{
snd_device_t *dev;
Index: hwdep.c
===================================================================
RCS file: /cvsroot/alsa/alsa-kernel/core/hwdep.c,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- hwdep.c 14 Oct 2002 09:42:34 -0000 1.13
+++ hwdep.c 7 Jan 2003 12:27:45 -0000 1.14
@@ -256,6 +256,19 @@
.f_ops = &snd_hwdep_f_ops,
};
+/**
+ * snd_hwdep_new - create a new hwdep instance
+ * @card: the card instance
+ * @id: the id string
+ * @device: the device index (zero-based)
+ * @rhwdep: the pointer to store the new hwdep instance
+ *
+ * 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.
+ *
+ * Returns zero if successful, or a negative error code on failure.
+ */
int snd_hwdep_new(snd_card_t * card, char *id, int device, snd_hwdep_t ** rhwdep)
{
snd_hwdep_t *hwdep;
Index: info.c
===================================================================
RCS file: /cvsroot/alsa/alsa-kernel/core/info.c,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -r1.28 -r1.29
--- info.c 7 Jan 2003 10:36:28 -0000 1.28
+++ info.c 7 Jan 2003 12:27:45 -0000 1.29
@@ -83,10 +83,16 @@
static int snd_info_version_init(void);
static int snd_info_version_done(void);
-/*
+/**
+ * snd_iprintf - printf on the procfs buffer
+ * @buffer: the procfs buffer
+ * @fmt: the printf format
+ *
+ * Outputs the string on the procfs buffer just like printf().
+ *
+ * Returns the size of output string.
*/
-
int snd_iprintf(snd_info_buffer_t * buffer, char *fmt,...)
{
va_list args;
@@ -591,6 +597,17 @@
.follow_link = snd_info_card_followlink,
};
+/**
+ * snd_create_proc_entry - create a procfs entry
+ * @name: the name of the proc file
+ * @mode: the file permission bits, S_Ixxx
+ * @parent: the parent proc-directory entry
+ *
+ * Creates a new proc file entry with the given name and permission
+ * on the given directory.
+ *
+ * Returns the pointer of new instance or NULL on failure.
+ */
struct proc_dir_entry *snd_create_proc_entry(const char *name, mode_t mode,
struct proc_dir_entry *parent)
{
@@ -682,6 +699,10 @@
*/
+/*
+ * create a card proc file
+ * called from init.c
+ */
int snd_info_card_create(snd_card_t * card)
{
char str[8];
@@ -701,6 +722,10 @@
return 0;
}
+/*
+ * register the card proc file
+ * called from init.c
+ */
int snd_info_card_register(snd_card_t * card)
{
char *s;
@@ -728,6 +753,10 @@
return 0;
}
+/*
+ * de-register the card proc file
+ * called from init.c
+ */
int snd_info_card_free(snd_card_t * card)
{
void *data;
@@ -747,10 +776,17 @@
return 0;
}
-/*
+/**
+ * snd_info_get_line - read one line from the procfs buffer
+ * @buffer: the procfs buffer
+ * @line: the buffer to store
+ * @len: the max. buffer size - 1
+ *
+ * Reads one line from the buffer and stores the string.
+ *
+ * Returns zero if successful, or 1 if error or EOF.
*/
-
int snd_info_get_line(snd_info_buffer_t * buffer, char *line, int len)
{
int c = -1;
@@ -781,6 +817,18 @@
return 0;
}
+/**
+ * snd_info_get_line - parse a string token
+ * @dest: the buffer to store the string token
+ * @src: the original string
+ * @len: the max. length of token - 1
+ *
+ * Parses the original string and copy a token to the given
+ * string buffer.
+ *
+ * Returns the updated pointer of the original string so that
+ * it can be used for the next call.
+ */
char *snd_info_get_str(char *dest, char *src, int len)
{
int c;
@@ -805,6 +853,18 @@
return src;
}
+/**
+ * snd_info_create_entry - create an info entry
+ * @name: the proc file name
+ *
+ * Creates an info entry with the given file name and initializes as
+ * the default state.
+ *
+ * Usually called from other functions such as
+ * snd_info_create_card_entry().
+ *
+ * Returns the pointer of the new instance, or NULL on failure.
+ */
static snd_info_entry_t *snd_info_create_entry(const char *name)
{
snd_info_entry_t *entry;
@@ -822,6 +882,16 @@
return entry;
}
+/**
+ * snd_info_create_module_entry - create an info entry for the given module
+ * @module: the module pointer
+ * @name: the file name
+ * @parent: the parent directory
+ *
+ * Creates a new info entry and assigns it to the given module.
+ *
+ * Returns the pointer of the new instance, or NULL on failure.
+ */
snd_info_entry_t *snd_info_create_module_entry(struct module * module,
const char *name,
snd_info_entry_t *parent)
@@ -834,6 +904,16 @@
return entry;
}
+/**
+ * snd_info_create_card_entry - create an info entry for the given card
+ * @card: the card instance
+ * @name: the file name
+ * @parent: the parent directory
+ *
+ * Creates a new info entry and assigns it to the given card.
+ *
+ * Returns the pointer of the new instance, or NULL on failure.
+ */
snd_info_entry_t *snd_info_create_card_entry(snd_card_t * card,
const char *name,
snd_info_entry_t * parent)
@@ -866,6 +946,26 @@
return snd_info_unregister(entry);
}
+/**
+ * snd_card_proc_new - create an info entry for the given card
+ * @card: the card instance
+ * @name: the file name
+ * @entryp: the pointer to store the new info entry
+ *
+ * Creates a new info entry and assigns it to the given card.
+ * Unlike snd_info_create_card_entry(), this function registers the
+ * info entry as an ALSA device component, so that it can be
+ * unregistered/released without explicit call.
+ * Also, you don't have to register this entry via snd_info_register(),
+ * since this will be registered by snd_card_register() automatically.
+ *
+ * The parent is assumed as card->proc_root.
+ *
+ * For releasing this entry, use snd_device_free() instead of
+ * snd_info_free_entry().
+ *
+ * Returns zero if successful, or a negative error code on failure.
+ */
int snd_card_proc_new(snd_card_t *card, const char *name,
snd_info_entry_t **entryp)
{
@@ -890,6 +990,12 @@
return 0;
}
+/**
+ * snd_info_free_entry - release the info entry
+ * @entry: the info entry
+ *
+ * Releases the info entry. Don't call this after registered.
+ */
void snd_info_free_entry(snd_info_entry_t * entry)
{
if (entry == NULL)
@@ -935,6 +1041,9 @@
}
#endif /* LINUX_2_2 */
+/*
+ * create a procfs device file
+ */
snd_info_entry_t *snd_info_create_device(const char *name, unsigned int number,
unsigned int mode)
{
unsigned short _major = number >> 16;
@@ -983,6 +1092,9 @@
return entry;
}
+/*
+ * release a procfs device file
+ */
void snd_info_free_device(snd_info_entry_t * entry)
{
snd_runtime_check(entry, return);
@@ -994,6 +1106,14 @@
snd_info_free_entry(entry);
}
+/**
+ * snd_info_register - register the info entry
+ * @entry: the info entry
+ *
+ * Registers the proc info entry.
+ *
+ * Returns zero if successful, or a negative error code on failure.
+ */
int snd_info_register(snd_info_entry_t * entry)
{
struct proc_dir_entry *root, *p = NULL;
@@ -1023,6 +1143,14 @@
return 0;
}
+/**
+ * snd_info_unregister - de-register the info entry
+ * @entry: the info entry
+ *
+ * De-registers the info entry and releases the instance.
+ *
+ * Returns zero if successful, or a negative error code on failure.
+ */
int snd_info_unregister(snd_info_entry_t * entry)
{
struct proc_dir_entry *root;
Index: init.c
===================================================================
RCS file: /cvsroot/alsa/alsa-kernel/core/init.c,v
retrieving revision 1.29
retrieving revision 1.30
diff -u -r1.29 -r1.30
--- init.c 7 Jan 2003 10:37:47 -0000 1.29
+++ init.c 7 Jan 2003 12:27:45 -0000 1.30
@@ -51,14 +51,16 @@
}
/**
- * snd_card_new: create and initialize a soundcard structure
+ * snd_card_new - create and initialize a soundcard structure
* @idx: card index (address) [0 ... (SNDRV_CARDS-1)]
* @xid: card identification (ASCII string)
* @module: top level module for locking
* @extra_size: allocate this extra size after the main soundcard structure
*
+ * Creates and initializes a soundcard structure.
+ *
* Returns kmallocated snd_card_t structure. Creates the ALSA control interface
- * (which is blocked until #snd_card_register function is called).
+ * (which is blocked until snd_card_register function is called).
*/
snd_card_t *snd_card_new(int idx, const char *xid,
struct module *module, int extra_size)
@@ -136,10 +138,12 @@
}
/**
- * snd_card_disconnect: disconnect all APIs from the file-operations (user space)
+ * snd_card_disconnect - disconnect all APIs from the file-operations (user space)
* @card: soundcard structure
*
- * Returns - zero, otherwise a negative error code.
+ * Disconnects all APIs from the file-operations (user space).
+ *
+ * Returns 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).
@@ -219,14 +223,14 @@
}
/**
- * snd_card_free: frees given soundcard structure
+ * snd_card_free - frees given soundcard structure
* @card: soundcard structure
*
* This function releases the soundcard structure and the all assigned
* devices automatically. That is, you don't have to release the devices
* by yourself.
*
- * Returns - zero. Frees all associated devices and frees the control
+ * Returns zero. Frees all associated devices and frees the control
* interface associated to given soundcard.
*/
int snd_card_free(snd_card_t * card)
@@ -298,16 +302,16 @@
}
/**
- * snd_card_free_in_thread: call snd_card_free() in thread
+ * snd_card_free_in_thread - call snd_card_free() in thread
* @card: soundcard structure
*
- * This function schedules the call of #snd_card_free function in a
+ * This function schedules the call of snd_card_free() function in a
* work queue. When all devices are released (non-busy), the work
- * is woken up and calls #snd_card_free.
+ * is woken up and calls snd_card_free().
*
* When a card can be disconnected at any time by hotplug service,
* this function should be used in disconnect (or detach) callback
- * instead of calling #snd_card_free directly.
+ * instead of calling snd_card_free() directly.
*
* Returns - zero otherwise a negative error code if the start of thread failed.
*/
@@ -383,7 +387,7 @@
}
/**
- * snd_card_register: register the soundcard
+ * snd_card_register - register the soundcard
* @card: soundcard structure
*
* This function registers all the devices assigned to the soundcard.
@@ -391,7 +395,7 @@
* external accesses. Thus, you should call this function at the end
* of the initialization of the card.
*
- * Returns - zero otherwise a negative error code if the registrain failed.
+ * Returns zero otherwise a negative error code if the registrain failed.
*/
int snd_card_register(snd_card_t * card)
{
@@ -508,14 +512,14 @@
}
/**
- * snd_component_add: add a component string
+ * snd_component_add - add a component string
* @card: soundcard structure
* @component: the component id string
*
* This function adds the component id string to the supported list.
* The component can be referred from the alsa-lib.
*
- * Returns - zero otherwise a negative error code.
+ * Returns zero otherwise a negative error code.
*/
int snd_component_add(snd_card_t *card, const char *component)
@@ -539,7 +543,7 @@
}
/**
- * snd_card_file_add: add the file to the file list of the card
+ * snd_card_file_add - add the file to the file list of the card
* @card: soundcard structure
* @file: file pointer
*
@@ -571,15 +575,15 @@
}
/**
- * snd_card_file_remove: remove the file from the file list
+ * snd_card_file_remove - remove the file from the file list
* @card: soundcard structure
* @file: file pointer
*
* This function removes the file formerly added to the card via
- * #snd_card_file_add function.
+ * snd_card_file_add() function.
* If all files are removed and the release of the card is
- * scheduled, it will wake up the the thread to call #snd_card_free
- * (see #snd_card_free_in_thread function).
+ * scheduled, it will wake up the the thread to call snd_card_free()
+ * (see snd_card_free_in_thread() function).
*
* Returns zero or a negative error code.
*/
@@ -614,8 +618,10 @@
#ifdef CONFIG_PM
/**
- * snd_power_wait: wait until the power-state is changed.
+ * snd_power_wait - wait until the power-state is changed.
* @card: soundcard structure
+ *
+ * Waits until the power-state is changed.
*
* Note: the power lock must be active before call.
*/
Index: isadma.c
===================================================================
RCS file: /cvsroot/alsa/alsa-kernel/core/isadma.c,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- isadma.c 9 Sep 2002 17:44:44 -0000 1.8
+++ isadma.c 7 Jan 2003 12:27:45 -0000 1.9
@@ -30,10 +30,15 @@
#include <sound/core.h>
#include <asm/dma.h>
-/*
+/**
+ * snd_dma_program - program an ISA DMA transfer
+ * @dma: the dma number
+ * @addr: the physical address of the buffer
+ * @size: the DMA transfer size
+ * @mode: the DMA transfer mode, DMA_MODE_XXX
*
+ * Programs an ISA DMA transfer for the given buffer.
*/
-
void snd_dma_program(unsigned long dma,
unsigned long addr, unsigned int size,
unsigned short mode)
@@ -51,6 +56,12 @@
release_dma_lock(flags);
}
+/**
+ * snd_dma_disable - stop the ISA DMA transfer
+ * @dma: the dma number
+ *
+ * Stops the ISA DMA transfer.
+ */
void snd_dma_disable(unsigned long dma)
{
unsigned long flags;
@@ -61,6 +72,12 @@
release_dma_lock(flags);
}
+/**
+ * snd_dma_residue - return the residue count of the given DMA
+ * @dma: the dma number
+ *
+ * Returns the residue count of the given DMA transfer.
+ */
unsigned int snd_dma_residue(unsigned long dma)
{
unsigned long flags;
Index: memory.c
===================================================================
RCS file: /cvsroot/alsa/alsa-kernel/core/memory.c,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -r1.22 -r1.23
--- memory.c 14 Oct 2002 16:33:27 -0000 1.22
+++ memory.c 7 Jan 2003 12:27:45 -0000 1.23
@@ -264,7 +264,15 @@
#endif /* CONFIG_SND_DEBUG_MEMORY */
-
+/**
+ * snd_malloc_pages - allocate pages with the given size
+ * @size: the size to allocate in bytes
+ * @dma_flags: the allocation conditions, GFP_XXX
+ *
+ * Allocates the physically contiguous pages with the given size.
+ *
+ * Returns the pointer of the buffer, or NULL if no enoguh memory.
+ */
void *snd_malloc_pages(unsigned long size, unsigned int dma_flags)
{
int pg;
@@ -285,6 +293,19 @@
return res;
}
+/**
+ * snd_malloc_pages_fallback - allocate pages with the given size with fallback
+ * @size: the requested size to allocate in bytes
+ * @dma_flags: the allocation conditions, GFP_XXX
+ * @res_size: the pointer to store the size of buffer actually allocated
+ *
+ * Allocates the physically contiguous pages with the given request
+ * size. 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.
+ *
+ * Returns the pointer of the buffer, or NULL if no enoguh memory.
+ */
void *snd_malloc_pages_fallback(unsigned long size, unsigned int dma_flags, unsigned
long *res_size)
{
void *res;
@@ -301,6 +322,13 @@
return NULL;
}
+/**
+ * snd_free_pages - release the pages
+ * @ptr: the buffer pointer to release
+ * @size: the allocated buffer size
+ *
+ * Releases the buffer allocated via snd_malloc_pages().
+ */
void snd_free_pages(void *ptr, unsigned long size)
{
int pg;
@@ -321,6 +349,16 @@
#if defined(CONFIG_ISA) && ! defined(CONFIG_PCI)
+/**
+ * snd_malloc_isa_pages - allocate pages for ISA bus with the given size
+ * @size: the size to allocate in bytes
+ * @dma_addr: the pointer to store the physical address of the buffer
+ *
+ * Allocates the physically contiguous pages with the given size for
+ * ISA bus.
+ *
+ * Returns the pointer of the buffer, or NULL if no enoguh memory.
+ */
void *snd_malloc_isa_pages(unsigned long size, dma_addr_t *dma_addr)
{
void *dma_area;
@@ -329,6 +367,19 @@
return dma_area;
}
+/**
+ * snd_malloc_isa_pages_fallback - allocate pages with the given size with fallback
+for ISA bus
+ * @size: the requested size to allocate in bytes
+ * @dma_addr: the pointer to store the physical address of the buffer
+ * @res_size: the pointer to store the size of buffer actually allocated
+ *
+ * Allocates the physically contiguous pages with the given request
+ * size for PCI bus. 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.
+ *
+ * Returns the pointer of the buffer, or NULL if no enoguh memory.
+ */
void *snd_malloc_isa_pages_fallback(unsigned long size,
dma_addr_t *dma_addr,
unsigned long *res_size)
@@ -343,6 +394,17 @@
#ifdef CONFIG_PCI
+/**
+ * snd_malloc_pci_pages - allocate pages for PCI bus with the given size
+ * @pci: the pci device pointer
+ * @size: the size to allocate in bytes
+ * @dma_addr: the pointer to store the physical address of the buffer
+ *
+ * Allocates the physically contiguous pages with the given size for
+ * PCI bus.
+ *
+ * Returns the pointer of the buffer, or NULL if no enoguh memory.
+ */
void *snd_malloc_pci_pages(struct pci_dev *pci,
unsigned long size,
dma_addr_t *dma_addr)
@@ -366,6 +428,20 @@
return res;
}
+/**
+ * snd_malloc_pci_pages_fallback - allocate pages with the given size with fallback
+for PCI bus
+ * @pci: pci device pointer
+ * @size: the requested size to allocate in bytes
+ * @dma_addr: the pointer to store the physical address of the buffer
+ * @res_size: the pointer to store the size of buffer actually allocated
+ *
+ * Allocates the physically contiguous pages with the given request
+ * size for PCI bus. 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.
+ *
+ * Returns the pointer of the buffer, or NULL if no enoguh memory.
+ */
void *snd_malloc_pci_pages_fallback(struct pci_dev *pci,
unsigned long size,
dma_addr_t *dma_addr,
@@ -384,6 +460,15 @@
return NULL;
}
+/**
+ * snd_free_pci_pages - release the pages
+ * @pci: pci device pointer
+ * @size: the allocated buffer size
+ * @ptr: the buffer pointer to release
+ * @dma_addr: the physical address of the buffer
+ *
+ * Releases the buffer allocated via snd_malloc_pci_pages().
+ */
void snd_free_pci_pages(struct pci_dev *pci,
unsigned long size,
void *ptr,
@@ -409,6 +494,17 @@
#ifdef CONFIG_SBUS
+/**
+ * snd_malloc_sbus_pages - allocate pages for SBUS with the given size
+ * @sdev: sbus device pointer
+ * @size: the size to allocate in bytes
+ * @dma_addr: the pointer to store the physical address of the buffer
+ *
+ * Allocates the physically contiguous pages with the given size for
+ * SBUS.
+ *
+ * Returns the pointer of the buffer, or NULL if no enoguh memory.
+ */
void *snd_malloc_sbus_pages(struct sbus_dev *sdev,
unsigned long size,
dma_addr_t *dma_addr)
@@ -432,6 +528,20 @@
return res;
}
+/**
+ * snd_malloc_pci_pages_fallback - allocate pages with the given size with fallback
+for SBUS
+ * @sdev: sbus device pointer
+ * @size: the requested size to allocate in bytes
+ * @dma_addr: the pointer to store the physical address of the buffer
+ * @res_size: the pointer to store the size of buffer actually allocated
+ *
+ * Allocates the physically contiguous pages with the given request
+ * size for SBUS. 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.
+ *
+ * Returns the pointer of the buffer, or NULL if no enoguh memory.
+ */
void *snd_malloc_sbus_pages_fallback(struct sbus_dev *sdev,
unsigned long size,
dma_addr_t *dma_addr,
@@ -450,6 +560,15 @@
return NULL;
}
+/**
+ * snd_free_sbus_pages - release the pages
+ * @sdev: sbus device pointer
+ * @size: the allocated buffer size
+ * @ptr: the buffer pointer to release
+ * @dma_addr: the physical address of the buffer
+ *
+ * Releases the buffer allocated via snd_malloc_pci_pages().
+ */
void snd_free_sbus_pages(struct sbus_dev *sdev,
unsigned long size,
void *ptr,
@@ -473,6 +592,15 @@
#endif /* CONFIG_SBUS */
+/**
+ * snd_kcalloc - memory allocation and zero-clear
+ * @size: the size to allocate in bytes
+ * @flags: allocation conditions, GFP_XXX
+ *
+ * Allocates a memory chunk via kmalloc() and initializes it to zero.
+ *
+ * Returns the pointer, or NULL if no enoguh memory.
+ */
void *snd_kcalloc(size_t size, int flags)
{
void *ptr;
@@ -483,6 +611,15 @@
return ptr;
}
+/**
+ * snd_kmalloc_strdup - copy the string
+ * @string: the original string
+ * @flags: allocation conditions, GFP_XXX
+ *
+ * Allocates a memory chunk via kmalloc() and copies the string to it.
+ *
+ * Returns the pointer, or NULL if no enoguh memory.
+ */
char *snd_kmalloc_strdup(const char *string, int flags)
{
size_t len;
@@ -497,6 +634,16 @@
return ptr;
}
+/**
+ * copy_to_user_fromio - copy data from mmio-space to user-space
+ * @dst: the destination pointer on user-space
+ * @src: the source pointer on mmio
+ * @count: the data size to copy in bytes
+ *
+ * Copies the data from mmio-space to user-space.
+ *
+ * Returns zero if successful, or non-zero on failure.
+ */
int copy_to_user_fromio(void *dst, unsigned long src, size_t count)
{
#if defined(__i386__) || defined(CONFIG_SPARC32)
@@ -518,6 +665,16 @@
#endif
}
+/**
+ * copy_from_user_toio - copy data from user-space to mmio-space
+ * @dst: the destination pointer on mmio-space
+ * @src: the source pointer on user-space
+ * @count: the data size to copy in bytes
+ *
+ * Copies the data from user-space to mmio-space.
+ *
+ * Returns zero if successful, or non-zero on failure.
+ */
int copy_from_user_toio(unsigned long dst, const void *src, size_t count)
{
#if defined(__i386__) || defined(CONFIG_SPARC32)
Index: pcm.c
===================================================================
RCS file: /cvsroot/alsa/alsa-kernel/core/pcm.c,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -r1.22 -r1.23
--- pcm.c 7 Jan 2003 10:58:51 -0000 1.22
+++ pcm.c 7 Jan 2003 12:27:45 -0000 1.23
@@ -542,6 +542,19 @@
return 0;
}
+/**
+ * snd_pcm_new_stream - create a new PCM stream
+ * @pcm: the pcm instance
+ * @stream: the stream direction, SNDRV_PCM_STREAM_XXX
+ * @substream_count: the number of substreams
+ *
+ * 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().
+ *
+ * Returns zero if successful, or a negative error code on failure.
+ */
int snd_pcm_new_stream(snd_pcm_t *pcm, int stream, int substream_count)
{
int idx, err;
@@ -590,6 +603,22 @@
return 0;
}
+/**
+ * snd_pcm_new - create a new PCM instance
+ * @card: the card instance
+ * @id: the id string
+ * @device: the device index (zero based)
+ * @playback_count: the number of substreams for playback
+ * @capture_count: the number of substreams for capture
+ * @rpcm: the pointer to store the new pcm instance
+ *
+ * Creates a new PCM instance.
+ *
+ * The pcm operators have to be set afterwards to the new instance
+ * via snd_pcm_set_ops().
+ *
+ * Returns zero if successful, or a negative error code on failure.
+ */
int snd_pcm_new(snd_card_t * card, char *id, int device,
int playback_count, int capture_count,
snd_pcm_t ** rpcm)
Index: pcm_lib.c
===================================================================
RCS file: /cvsroot/alsa/alsa-kernel/core/pcm_lib.c,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -r1.24 -r1.25
--- pcm_lib.c 8 Dec 2002 18:15:38 -0000 1.24
+++ pcm_lib.c 7 Jan 2003 12:27:45 -0000 1.25
@@ -214,10 +214,14 @@
return 0;
}
-/*
- * Operations
+/**
+ * snd_pcm_set_ops - set the PCM operators
+ * @pcm: the pcm instance
+ * @direction: stream direction, SNDRV_PCM_STREAM_XXX
+ * @ops: the operator table
+ *
+ * Sets the given PCM operators to the pcm instance.
*/
-
void snd_pcm_set_ops(snd_pcm_t *pcm, int direction, snd_pcm_ops_t *ops)
{
snd_pcm_str_t *stream = &pcm->streams[direction];
@@ -227,10 +231,13 @@
substream->ops = ops;
}
-/*
- * Sync
+
+/**
+ * snd_pcm_sync - set the PCM sync id
+ * @substream: the pcm substream
+ *
+ * Sets the PCM sync identifier for the card.
*/
-
void snd_pcm_set_sync(snd_pcm_substream_t * substream)
{
snd_pcm_runtime_t *runtime = substream->runtime;
@@ -354,7 +361,17 @@
return changed;
}
-/* r <- v */
+/**
+ * snd_interval_refine - refine the interval value of configurator
+ * @i: the interval value to refine
+ * @v: the interval value to refer to
+ *
+ * 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.
+ *
+ * Returns non-zero if the value is changed, zero if not changed.
+ */
int snd_interval_refine(snd_interval_t *i, const snd_interval_t *v)
{
int changed = 0;
@@ -445,6 +462,13 @@
c->integer = (a->integer && b->integer);
}
+/**
+ * snd_interval_div - refine the interval value with division
+ *
+ * c = a / b
+ *
+ * Returns non-zero if the value is changed, zero if not changed.
+ */
void snd_interval_div(const snd_interval_t *a, const snd_interval_t *b,
snd_interval_t *c)
{
unsigned int r;
@@ -469,7 +493,13 @@
c->integer = 0;
}
-/* a * b / k */
+/**
+ * snd_interval_muldivk - refine the interval value
+ *
+ * c = a * b / k
+ *
+ * Returns non-zero if the value is changed, zero if not changed.
+ */
void snd_interval_muldivk(const snd_interval_t *a, const snd_interval_t *b,
unsigned int k, snd_interval_t *c)
{
@@ -490,7 +520,13 @@
c->integer = 0;
}
-/* a * k / b */
+/**
+ * snd_interval_mulkdiv - refine the interval value
+ *
+ * c = a * k / b
+ *
+ * Returns non-zero if the value is changed, zero if not changed.
+ */
void snd_interval_mulkdiv(const snd_interval_t *a, unsigned int k,
const snd_interval_t *b, snd_interval_t *c)
{
@@ -520,6 +556,11 @@
/* ---- */
+/**
+ * snd_interval_ratnum - refine the interval value
+ *
+ * Returns non-zero if the value is changed, zero if not changed.
+ */
int snd_interval_ratnum(snd_interval_t *i,
unsigned int rats_count, ratnum_t *rats,
unsigned int *nump, unsigned int *denp)
@@ -612,6 +653,11 @@
return err;
}
+/**
+ * snd_interval_ratden - refine the interval value
+ *
+ * Returns non-zero if the value is changed, zero if not changed.
+ */
int snd_interval_ratden(snd_interval_t *i,
unsigned int rats_count, ratden_t *rats,
unsigned int *nump, unsigned int *denp)
@@ -698,6 +744,19 @@
return err;
}
+/**
+ * snd_interval_list - refine the interval value from the list
+ * @i: the interval value to refine
+ * @count: the number of elements in the list
+ * @list: the value list
+ * @mask: the bit-mask to evaluate
+ *
+ * Refines the interval value from the list.
+ * When mask is non-zero, only the elements corresponding to bit 1 are
+ * evaluated.
+ *
+ * Returns non-zero if the value is changed, zero if not changed.
+ */
int snd_interval_list(snd_interval_t *i, unsigned int count, unsigned int *list,
unsigned int mask)
{
unsigned int k;
@@ -762,6 +821,17 @@
/* Info constraints helpers */
+/**
+ * snd_pcm_hw_rule_add - add the hw-constraint rule
+ * @runtime: the pcm runtime instance
+ * @cond: condition bits
+ * @var: the variable to evaluate
+ * @func: the evaluation function
+ * @private: the private data pointer passed to function
+ * @dep: the dependent variables
+ *
+ * Returns zero if successful, or a negative error code on failure.
+ */
int snd_pcm_hw_rule_add(snd_pcm_runtime_t *runtime, unsigned int cond,
int var,
snd_pcm_hw_rule_func_t func, void *private,
@@ -808,6 +878,9 @@
return 0;
}
+/**
+ * snd_pcm_hw_constraint_mask
+ */
int snd_pcm_hw_constraint_mask(snd_pcm_runtime_t *runtime, snd_pcm_hw_param_t var,
u_int32_t mask)
{
@@ -820,6 +893,9 @@
return 0;
}
+/**
+ * snd_pcm_hw_constraint_mask64
+ */
int snd_pcm_hw_constraint_mask64(snd_pcm_runtime_t *runtime, snd_pcm_hw_param_t var,
u_int64_t mask)
{
@@ -833,12 +909,18 @@
return 0;
}
+/**
+ * snd_pcm_hw_constraint_integer
+ */
int snd_pcm_hw_constraint_integer(snd_pcm_runtime_t *runtime, snd_pcm_hw_param_t var)
{
snd_pcm_hw_constraints_t *constrs = &runtime->hw_constraints;
return snd_interval_setinteger(constrs_interval(constrs, var));
}
+/**
+ * snd_pcm_hw_constraint_minmax
+ */
int snd_pcm_hw_constraint_minmax(snd_pcm_runtime_t *runtime, snd_pcm_hw_param_t var,
unsigned int min, unsigned int max)
{
@@ -859,6 +941,9 @@
}
+/**
+ * snd_pcm_hw_constraint_list
+ */
int snd_pcm_hw_constraint_list(snd_pcm_runtime_t *runtime,
unsigned int cond,
snd_pcm_hw_param_t var,
@@ -884,6 +969,9 @@
return err;
}
+/**
+ * snd_pcm_hw_constraint_ratnums
+ */
int snd_pcm_hw_constraint_ratnums(snd_pcm_runtime_t *runtime,
unsigned int cond,
snd_pcm_hw_param_t var,
@@ -908,6 +996,9 @@
return err;
}
+/**
+ * snd_pcm_hw_constraint_ratdens
+ */
int snd_pcm_hw_constraint_ratdens(snd_pcm_runtime_t *runtime,
unsigned int cond,
snd_pcm_hw_param_t var,
@@ -930,6 +1021,9 @@
return 0;
}
+/**
+ * snd_pcm_hw_constraint_msbits
+ */
int snd_pcm_hw_constraint_msbits(snd_pcm_runtime_t *runtime,
unsigned int cond,
unsigned int width,
@@ -949,6 +1043,9 @@
return snd_interval_step(hw_param_interval(params, rule->var), 0, step);
}
+/**
+ * snd_pcm_hw_constraint_step
+ */
int snd_pcm_hw_constraint_step(snd_pcm_runtime_t *runtime,
unsigned int cond,
snd_pcm_hw_param_t var,
@@ -971,6 +1068,9 @@
sizeof(pow2_sizes)/sizeof(int), pow2_sizes, 0);
}
+/**
+ * snd_pcm_hw_constraint_pow2
+ */
int snd_pcm_hw_constraint_pow2(snd_pcm_runtime_t *runtime,
unsigned int cond,
snd_pcm_hw_param_t var)
@@ -1004,6 +1104,9 @@
snd_BUG();
}
+/**
+ * snd_pcm_hw_param_any
+ */
int snd_pcm_hw_param_any(snd_pcm_t *pcm, snd_pcm_hw_params_t *params,
snd_pcm_hw_param_t var)
{
@@ -1022,16 +1125,23 @@
params->info = ~0U;
}
-/* Fill PARAMS with full configuration space boundaries */
+/**
+ * snd_pcm_hw_params_any
+ *
+ * Fill PARAMS with full configuration space boundaries
+ */
int snd_pcm_hw_params_any(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
{
_snd_pcm_hw_params_any(params);
return snd_pcm_hw_refine(pcm, params);
}
-/* Return the value for field PAR if it's fixed in configuration space
- defined by PARAMS. Return -EINVAL otherwise
-*/
+/**
+ * snd_pcm_hw_param_value
+ *
+ * Return the value for field PAR if it's fixed in configuration space
+ * defined by PARAMS. Return -EINVAL otherwise
+ */
int snd_pcm_hw_param_value(const snd_pcm_hw_params_t *params,
snd_pcm_hw_param_t var, int *dir)
{
@@ -1055,7 +1165,11 @@
return -EINVAL;
}
-/* Return the minimum value for field PAR. */
+/**
+ * snd_pcm_hw_param_value_min
+ *
+ * Return the minimum value for field PAR.
+ */
unsigned int snd_pcm_hw_param_value_min(const snd_pcm_hw_params_t *params,
snd_pcm_hw_param_t var, int *dir)
{
@@ -1074,7 +1188,11 @@
return -EINVAL;
}
-/* Return the maximum value for field PAR. */
+/**
+ * snd_pcm_hw_param_value_max
+ *
+ * Return the maximum value for field PAR.
+ */
unsigned int snd_pcm_hw_param_value_max(const snd_pcm_hw_params_t *params,
snd_pcm_hw_param_t var, int *dir)
{
@@ -1122,10 +1240,13 @@
return changed;
}
-/* Inside configuration space defined by PARAMS remove from PAR all
- non integer values. Reduce configuration space accordingly.
- Return -EINVAL if the configuration space is empty
-*/
+/**
+ * snd_pcm_hw_param_setinteger
+ *
+ * Inside configuration space defined by PARAMS remove from PAR all
+ * non integer values. Reduce configuration space accordingly.
+ * Return -EINVAL if the configuration space is empty
+ */
int snd_pcm_hw_param_setinteger(snd_pcm_t *pcm,
snd_pcm_hw_params_t *params,
snd_pcm_hw_param_t var)
@@ -1161,10 +1282,13 @@
}
-/* Inside configuration space defined by PARAMS remove from PAR all
- values > minimum. Reduce configuration space accordingly.
- Return the minimum.
-*/
+/**
+ * snd_pcm_hw_param_first
+ *
+ * Inside configuration space defined by PARAMS remove from PAR all
+ * values > minimum. Reduce configuration space accordingly.
+ * Return the minimum.
+ */
int snd_pcm_hw_param_first(snd_pcm_t *pcm,
snd_pcm_hw_params_t *params,
snd_pcm_hw_param_t var, int *dir)
@@ -1199,10 +1323,13 @@
}
-/* Inside configuration space defined by PARAMS remove from PAR all
- values < maximum. Reduce configuration space accordingly.
- Return the maximum.
-*/
+/**
+ * snd_pcm_hw_param_last
+ *
+ * Inside configuration space defined by PARAMS remove from PAR all
+ * values < maximum. Reduce configuration space accordingly.
+ * Return the maximum.
+ */
int snd_pcm_hw_param_last(snd_pcm_t *pcm,
snd_pcm_hw_params_t *params,
snd_pcm_hw_param_t var, int *dir)
@@ -1247,10 +1374,13 @@
return changed;
}
-/* Inside configuration space defined by PARAMS remove from PAR all
- values < VAL. Reduce configuration space accordingly.
- Return new minimum or -EINVAL if the configuration space is empty
-*/
+/**
+ * snd_pcm_hw_param_min
+ *
+ * Inside configuration space defined by PARAMS remove from PAR all
+ * values < VAL. Reduce configuration space accordingly.
+ * Return new minimum or -EINVAL if the configuration space is empty
+ */
int snd_pcm_hw_param_min(snd_pcm_t *pcm, snd_pcm_hw_params_t *params,
snd_pcm_hw_param_t var, unsigned int val, int *dir)
{
@@ -1297,10 +1427,13 @@
return changed;
}
-/* Inside configuration space defined by PARAMS remove from PAR all
- values >= VAL + 1. Reduce configuration space accordingly.
- Return new maximum or -EINVAL if the configuration space is empty
-*/
+/**
+ * snd_pcm_hw_param_max
+ *
+ * Inside configuration space defined by PARAMS remove from PAR all
+ * values >= VAL + 1. Reduce configuration space accordingly.
+ * Return new maximum or -EINVAL if the configuration space is empty
+ */
int snd_pcm_hw_param_max(snd_pcm_t *pcm, snd_pcm_hw_params_t *params,
snd_pcm_hw_param_t var, unsigned int val, int *dir)
{
@@ -1364,10 +1497,13 @@
return changed;
}
-/* Inside configuration space defined by PARAMS remove from PAR all
- values != VAL. Reduce configuration space accordingly.
- Return VAL or -EINVAL if the configuration space is empty
-*/
+/**
+ * snd_pcm_hw_param_set
+ *
+ * Inside configuration space defined by PARAMS remove from PAR all
+ * values != VAL. Reduce configuration space accordingly.
+ * Return VAL or -EINVAL if the configuration space is empty
+ */
int snd_pcm_hw_param_set(snd_pcm_t *pcm, snd_pcm_hw_params_t *params,
snd_pcm_hw_param_t var, unsigned int val, int dir)
{
@@ -1395,13 +1531,16 @@
return changed;
}
-/* Inside configuration space defined by PARAMS remove from PAR all values
- not contained in MASK. Reduce configuration space accordingly.
- This function can be called only for SNDRV_PCM_HW_PARAM_ACCESS,
- SNDRV_PCM_HW_PARAM_FORMAT, SNDRV_PCM_HW_PARAM_SUBFORMAT.
- Return 0 on success or -EINVAL
- if the configuration space is empty
-*/
+/**
+ * snd_pcm_hw_param_mask
+ *
+ * Inside configuration space defined by PARAMS remove from PAR all values
+ * not contained in MASK. Reduce configuration space accordingly.
+ * This function can be called only for SNDRV_PCM_HW_PARAM_ACCESS,
+ * SNDRV_PCM_HW_PARAM_FORMAT, SNDRV_PCM_HW_PARAM_SUBFORMAT.
+ * Return 0 on success or -EINVAL
+ * if the configuration space is empty
+ */
int snd_pcm_hw_param_mask(snd_pcm_t *pcm, snd_pcm_hw_params_t *params,
snd_pcm_hw_param_t var, const snd_mask_t *val)
{
@@ -1464,12 +1603,15 @@
return boundary_lt(dmin, dmindir, dmax, dmaxdir);
}
-/* Inside configuration space defined by PARAMS set PAR to the available value
- nearest to VAL. Reduce configuration space accordingly.
- This function cannot be called for SNDRV_PCM_HW_PARAM_ACCESS,
- SNDRV_PCM_HW_PARAM_FORMAT, SNDRV_PCM_HW_PARAM_SUBFORMAT.
- Return the value found.
- */
+/**
+ * snd_pcm_hw_param_near
+ *
+ * Inside configuration space defined by PARAMS set PAR to the available value
+ * nearest to VAL. Reduce configuration space accordingly.
+ * This function cannot be called for SNDRV_PCM_HW_PARAM_ACCESS,
+ * SNDRV_PCM_HW_PARAM_FORMAT, SNDRV_PCM_HW_PARAM_SUBFORMAT.
+ * Return the value found.
+ */
int snd_pcm_hw_param_near(snd_pcm_t *pcm, snd_pcm_hw_params_t *params,
snd_pcm_hw_param_t var, unsigned int best, int *dir)
{
@@ -1537,17 +1679,14 @@
return v;
}
-/* Choose one configuration from configuration space defined by PARAMS
- The configuration choosen is that obtained fixing in this order:
- first access
- first format
- first subformat
- min channels
- min rate
- min period time
- max buffer size
- min tick time
-*/
+/**
+ * snd_pcm_hw_param_choose
+ *
+ * Choose one configuration from configuration space defined by PARAMS
+ * The configuration choosen is that obtained fixing in this order:
+ * first access, first format, first subformat, min channels,
+ * min rate, min period time, max buffer size, min tick time
+ */
int snd_pcm_hw_params_choose(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
{
int err;
@@ -1630,6 +1769,17 @@
return 0;
}
+/**
+ * snd_pcm_lib_ioctl - a generic PCM ioctl callback
+ * @substream: the pcm substream instance
+ * @cmd: ioctl command
+ * @arg: ioctl argument
+ *
+ * Processes the generic ioctl commands for PCM.
+ * Can be passed as the ioctl callback for PCM ops.
+ *
+ * Returns zero if successful, or a negative error code on failure.
+ */
int snd_pcm_lib_ioctl(snd_pcm_substream_t *substream,
unsigned int cmd, void *arg)
{
@@ -1648,30 +1798,70 @@
* Conditions
*/
+/**
+ * snd_pcm_playback_ready - check whether the playback buffer is available
+ * @substream: the pcm substream instance
+ *
+ * Checks whether enough free space is available on the playback buffer.
+ *
+ * Returns non-zero if available, or zero if not.
+ */
int snd_pcm_playback_ready(snd_pcm_substream_t *substream)
{
snd_pcm_runtime_t *runtime = substream->runtime;
return snd_pcm_playback_avail(runtime) >= runtime->control->avail_min;
}
+/**
+ * snd_pcm_capture_ready - check whether the capture buffer is available
+ * @substream: the pcm substream instance
+ *
+ * Checks whether enough capture data is available on the capture buffer.
+ *
+ * Returns non-zero if available, or zero if not.
+ */
int snd_pcm_capture_ready(snd_pcm_substream_t *substream)
{
snd_pcm_runtime_t *runtime = substream->runtime;
return snd_pcm_capture_avail(runtime) >= runtime->control->avail_min;
}
+/**
+ * snd_pcm_playback_data - check whether any data exists on the playback buffer
+ * @substream: the pcm substream instance
+ *
+ * Checks whether any data exists on the playback buffer.
+ *
+ * Returns non-zero if exists, or zero if not.
+ */
int snd_pcm_playback_data(snd_pcm_substream_t *substream)
{
snd_pcm_runtime_t *runtime = substream->runtime;
return snd_pcm_playback_avail(runtime) < runtime->buffer_size;
}
+/**
+ * snd_pcm_playback_empty - check whether the playback buffer is empty
+ * @substream: the pcm substream instance
+ *
+ * Checks whether the playback buffer is empty.
+ *
+ * Returns non-zero if empty, or zero if not.
+ */
int snd_pcm_playback_empty(snd_pcm_substream_t *substream)
{
snd_pcm_runtime_t *runtime = substream->runtime;
return snd_pcm_playback_avail(runtime) >= runtime->buffer_size;
}
+/**
+ * snd_pcm_capture_empty - check whether the capture buffer is empty
+ * @substream: the pcm substream instance
+ *
+ * Checks whether the capture buffer is empty.
+ *
+ * Returns non-zero if empty, or zero if not.
+ */
int snd_pcm_capture_empty(snd_pcm_substream_t *substream)
{
snd_pcm_runtime_t *runtime = substream->runtime;
@@ -1766,6 +1956,17 @@
spin_unlock_irq(&runtime->lock);
}
+/**
+ * snd_pcm_period_elapsed - update the pcm status for the next period
+ * @substream: the pcm substream instance
+ *
+ * This function is called from the interrupt handler when the
+ * PCM has processed the period size. It will update the current
+ * pointer, set up the tick, wake up sleepers, etc.
+ *
+ * Even if more than one periods have elapsed since the last call, you
+ * have to call this only once.
+ */
void snd_pcm_period_elapsed(snd_pcm_substream_t *substream)
{
snd_pcm_runtime_t *runtime;
Index: pcm_memory.c
===================================================================
RCS file: /cvsroot/alsa/alsa-kernel/core/pcm_memory.c,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- pcm_memory.c 7 Jan 2003 10:58:51 -0000 1.14
+++ pcm_memory.c 7 Jan 2003 12:27:45 -0000 1.15
@@ -144,8 +144,12 @@
}
/**
- * snd_pcm_lib_preallocate_free - release the preallocated buffer
- * of the specified substream.
+ * snd_pcm_lib_preallocate_free - release the preallocated buffer of the specified
+substream.
+ * @substream: the pcm substream instance
+ *
+ * Releases the pre-allocated buffer of the given substream.
+ *
+ * Returns zero if successful, or a negative error code on failure.
*/
int snd_pcm_lib_preallocate_free(snd_pcm_substream_t *substream)
{
@@ -158,8 +162,12 @@
}
/**
- * snd_pcm_lib_preallocate_free_for_all - release the preallocated
- * buffers of the whole substreams on the specified pcm.
+ * snd_pcm_lib_preallocate_free_for_all - release all pre-allocated buffers on the pcm
+ * @pcm: the pcm instance
+ *
+ * Releases all the pre-allocated buffers on the given pcm.
+ *
+ * Returns zero if successful, or a negative error code on failure.
*/
int snd_pcm_lib_preallocate_free_for_all(snd_pcm_t *pcm)
{
@@ -268,8 +276,16 @@
return 0;
}
-/*
- * pre-allocation for the continuous memory type
+/**
+ * snd_pcm_lib_preallocate_pages - pre-allocation for the continuous memory type
+ * @substream: the pcm substream instance
+ * @size: the requested pre-allocation size in bytes
+ * @max: the max. allowed pre-allocation size
+ * @flags: allocation condition, GFP_XXX
+ *
+ * Do pre-allocation for the continuous memory type.
+ *
+ * Returns zero if successful, or a negative error code on failure.
*/
int snd_pcm_lib_preallocate_pages(snd_pcm_substream_t *substream,
size_t size, size_t max,
@@ -280,6 +296,18 @@
return snd_pcm_lib_preallocate_pages1(substream, size, max);
}
+/**
+ * snd_pcm_lib_preallocate_pages_for_all - pre-allocation for continous memory type
+(all substreams)
+ * @pcm: pcm to assign the buffer
+ * @size: the requested pre-allocation size in bytes
+ * @max: max. buffer size acceptable for the changes via proc file
+ * @flags: allocation condition, GFP_XXX
+ *
+ * Do pre-allocation to all substreams of the given pcm for the
+ * continuous memory type.
+ *
+ * Returns zero if successful, or a negative error code on failure.
+ */
int snd_pcm_lib_preallocate_pages_for_all(snd_pcm_t *pcm,
size_t size, size_t max,
unsigned int flags)
@@ -297,10 +325,13 @@
#ifdef CONFIG_ISA
/**
* snd_pcm_lib_preallocate_isa_pages - pre-allocation for the ISA bus
- *
* @substream: substream to assign the buffer
- * @size: the buffer size to be allocated
+ * @size: the requested pre-allocation size in bytes
* @max: max. buffer size acceptable for the changes via proc file
+ *
+ * Do pre-allocation for the ISA bus.
+ *
+ * Returns zero if successful, or a negative error code on failure.
*/
int snd_pcm_lib_preallocate_isa_pages(snd_pcm_substream_t *substream,
size_t size, size_t max)
@@ -310,13 +341,17 @@
return snd_pcm_lib_preallocate_pages1(substream, size, max);
}
-/**
- * snd_pcm_lib_preallocate_isa_pages_for_all - pre-allocation
- * for the ISA bus (all substreams)
+/*
+ * FIXME: the function name is too long for docbook!
*
+ * snd_pcm_lib_preallocate_isa_pages_for_all - pre-allocation for the ISA bus (all
+substreams)
* @pcm: pcm to assign the buffer
- * @size: the buffer size to be allocated
* @max: max. buffer size acceptable for the changes via proc file
+ *
+ * Do pre-allocation to all substreams of the given pcm for the
+ * ISA bus.
+ *
+ * Returns zero if successful, or a negative error code on failure.
*/
int snd_pcm_lib_preallocate_isa_pages_for_all(snd_pcm_t *pcm,
size_t size, size_t max)
@@ -333,11 +368,15 @@
#endif /* CONFIG_ISA */
/**
- * snd_pcm_lib_malloc_pages - allocate the DMA buffer on the BUS type
- * given by snd_pcm_lib_preallocate_xxx_pages().
- *
+ * snd_pcm_lib_malloc_pages - allocate the DMA buffer
* @substream: the substream to allocate the DMA buffer to
* @size: the requested buffer size in bytes
+ *
+ * Allocates the DMA buffer on the BUS type given by
+ * snd_pcm_lib_preallocate_xxx_pages().
+ *
+ * Returns 1 if the buffer is changed, 0 if not changed, or a negative
+ * code on failure.
*/
int snd_pcm_lib_malloc_pages(snd_pcm_substream_t *substream, size_t size)
{
@@ -372,10 +411,12 @@
}
/**
- * snd_pcm_lib_free_pages - release the allocated DMA buffer of
- * the specified substream
- *
+ * snd_pcm_lib_free_pages - release the allocated DMA buffer.
* @substream: the substream to release the DMA buffer
+ *
+ * Releases the DMA buffer allocated via snd_pcm_lib_malloc_pages().
+ *
+ * Returns zero if successful, or a negative error code on failure.
*/
int snd_pcm_lib_free_pages(snd_pcm_substream_t *substream)
{
@@ -401,8 +442,12 @@
*
* @pci: pci device
* @substream: substream to assign the buffer
- * @size: the buffer size to be allocated in bytes
+ * @size: the requested pre-allocation size in bytes
* @max: max. buffer size acceptable for the changes via proc file
+ *
+ * Do pre-allocation for the PCI bus.
+ *
+ * Returns zero if successful, or a negative error code on failure.
*/
int snd_pcm_lib_preallocate_pci_pages(struct pci_dev *pci,
snd_pcm_substream_t *substream,
@@ -413,14 +458,19 @@
return snd_pcm_lib_preallocate_pages1(substream, size, max);
}
-/**
- * snd_pcm_lib_preallocate_pci_pages_for_all - pre-allocation
- * for the PCI bus (all substreams)
+/*
+ * FIXME: the function name is too long for docbook!
*
+ * snd_pcm_lib_preallocate_pci_pages_for_all - pre-allocation for the PCI bus (all
+substreams)
* @pci: pci device
* @pcm: pcm to assign the buffer
- * @size: the buffer size to be allocated
+ * @size: the requested pre-allocation size in bytes
* @max: max. buffer size acceptable for the changes via proc file
+ *
+ * Do pre-allocation to all substreams of the given pcm for the
+ * PCI bus.
+ *
+ * Returns zero if successful, or a negative error code on failure.
*/
int snd_pcm_lib_preallocate_pci_pages_for_all(struct pci_dev *pci,
snd_pcm_t *pcm,
@@ -444,8 +494,11 @@
*
* @sbus: SBUS device
* @substream: substream to assign the buffer
- * @size: the buffer size to be allocated
* @max: max. buffer size acceptable for the changes via proc file
+ *
+ * Do pre-allocation for the SBUS.
+ *
+ * Returns zero if successful, or a negative error code on failure.
*/
int snd_pcm_lib_preallocate_sbus_pages(struct sbus_dev *sdev,
snd_pcm_substream_t *substream,
@@ -456,14 +509,19 @@
return snd_pcm_lib_preallocate_pages1(substream, size, max);
}
-/**
- * snd_pcm_lib_preallocate_pci_pages_for_all - pre-allocation
- * for the SBUS bus (all substreams)
+/*
+ * FIXME: the function name is too long for docbook!
*
+ * snd_pcm_lib_preallocate_sbus_pages_for_all - pre-allocation for the SBUS bus (all
+substreams)
* @sbus: SBUS device
* @pcm: pcm to assign the buffer
- * @size: the buffer size to be allocated
+ * @size: the requested pre-allocation size in bytes
* @max: max. buffer size acceptable for the changes via proc file
+ *
+ * Do pre-allocation to all substreams of the given pcm for the
+ * SUBS.
+ *
+ * Returns zero if successful, or a negative error code on failure.
*/
int snd_pcm_lib_preallocate_sbus_pages_for_all(struct sbus_dev *sdev,
snd_pcm_t *pcm,
Index: pcm_misc.c
===================================================================
RCS file: /cvsroot/alsa/alsa-kernel/core/pcm_misc.c,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- pcm_misc.c 18 Dec 2002 12:01:53 -0000 1.8
+++ pcm_misc.c 7 Jan 2003 12:27:46 -0000 1.9
@@ -30,6 +30,13 @@
#define snd_enum_to_int(v) (v)
#define snd_int_to_enum(v) (v)
+/**
+ * snd_pcm_format_signed - Check the PCM format is signed linear
+ * @format: the format to check
+ *
+ * Returns 1 if the given PCM format is signed linear, 0 if unsigned
+ * linear, and a negative error code for non-linear formats.
+ */
int snd_pcm_format_signed(snd_pcm_format_t format)
{
switch (snd_enum_to_int(format)) {
@@ -66,6 +73,13 @@
}
}
+/**
+ * snd_pcm_format_unsigned - Check the PCM format is unsigned linear
+ * @format: the format to check
+ *
+ * Returns 1 if the given PCM format is unsigned linear, 0 if signed
+ * linear, and a negative error code for non-linear formats.
+ */
int snd_pcm_format_unsigned(snd_pcm_format_t format)
{
int val;
@@ -76,11 +90,24 @@
return !val;
}
+/**
+ * snd_pcm_format_linear - Check the PCM format is linear
+ * @format: the format to check
+ *
+ * Returns 1 if the given PCM format is linear, 0 if not.
+ */
int snd_pcm_format_linear(snd_pcm_format_t format)
{
return snd_pcm_format_signed(format) >= 0;
}
+/**
+ * snd_pcm_format_little_endian - Check the PCM format is little-endian
+ * @format: the format to check
+ *
+ * Returns 1 if the given PCM format is little-endian, 0 if
+ * big-endian, or a negative error code if endian not specified.
+ */
int snd_pcm_format_little_endian(snd_pcm_format_t format)
{
switch (snd_enum_to_int(format)) {
@@ -121,6 +148,13 @@
}
}
+/**
+ * snd_pcm_format_big_endian - Check the PCM format is big-endian
+ * @format: the format to check
+ *
+ * Returns 1 if the given PCM format is big-endian, 0 if
+ * little-endian, or a negative error code if endian not specified.
+ */
int snd_pcm_format_big_endian(snd_pcm_format_t format)
{
int val;
@@ -131,6 +165,13 @@
return !val;
}
+/**
+ * snd_pcm_format_cpu_endian - Check the PCM format is CPU-endian
+ * @format: the format to check
+ *
+ * Returns 1 if the given PCM format is CPU-endian, 0 if
+ * opposite, or a negative error code if endian not specified.
+ */
int snd_pcm_format_cpu_endian(snd_pcm_format_t format)
{
#ifdef SNDRV_LITTLE_ENDIAN
@@ -140,6 +181,13 @@
#endif
}
+/**
+ * snd_pcm_format_width - return the bit-width of the format
+ * @format: the format to check
+ *
+ * Returns the bit-width of the format, or a negative error code
+ * if unknown format.
+ */
int snd_pcm_format_width(snd_pcm_format_t format)
{
switch (snd_enum_to_int(format)) {
@@ -193,6 +241,13 @@
}
}
+/**
+ * snd_pcm_format_physical_width - return the physical bit-width of the format
+ * @format: the format to check
+ *
+ * Returns the physical bit-width of the format, or a negative error code
+ * if unknown format.
+ */
int snd_pcm_format_physical_width(snd_pcm_format_t format)
{
switch (snd_enum_to_int(format)) {
@@ -243,6 +298,13 @@
}
}
+/**
+ * snd_pcm_format_size - return the byte size of samples on the given format
+ * @format: the format to check
+ *
+ * Returns the byte size of the given samples for the format, or a
+ * negative error code if unknown format.
+ */
ssize_t snd_pcm_format_size(snd_pcm_format_t format, size_t samples)
{
switch (snd_enum_to_int(format)) {
@@ -296,6 +358,12 @@
}
}
+/**
+ * snd_pcm_format_silence_64 - return the silent data in 64bit integer
+ * @format: the format to check
+ *
+ * Returns the silent data in 64bit integer for the given format.
+ */
u_int64_t snd_pcm_format_silence_64(snd_pcm_format_t format)
{
switch (snd_enum_to_int(format)) {
@@ -451,6 +519,16 @@
return (u_int8_t)snd_pcm_format_silence_64(format);
}
+/**
+ * snd_pcm_format_set_silence - set the silence data on the buffer
+ * @format: the PCM format
+ * @data: the buffer pointer
+ * @samples: the number of samples to set silence
+ *
+ * Sets the silence data on the buffer for the given samples.
+ *
+ * Returns zero if sucessful, or a negative error code on failure.
+ */
int snd_pcm_format_set_silence(snd_pcm_format_t format, void *data, unsigned int
samples)
{
if (samples == 0)
@@ -544,6 +622,14 @@
SNDRV_PCM_FORMAT_U32_BE
};
+/**
+ * snd_pcm_build_linear_format - return the suitable linear format for the given
+condition
+ * @width: the bit-width
+ * @unsignd: 1 if unsigned, 0 if signed.
+ * @big_endian: 1 if big-endian, 0 if little-endian
+ *
+ * Returns the suitable linear format for the given condition.
+ */
snd_pcm_format_t snd_pcm_build_linear_format(int width, int unsignd, int big_endian)
{
switch (width) {
Index: pcm_native.c
===================================================================
RCS file: /cvsroot/alsa/alsa-kernel/core/pcm_native.c,v
retrieving revision 1.40
retrieving revision 1.41
diff -u -r1.40 -r1.41
--- pcm_native.c 19 Dec 2002 15:59:17 -0000 1.40
+++ pcm_native.c 7 Jan 2003 12:27:46 -0000 1.41
@@ -676,6 +676,9 @@
snd_pcm_tick_prepare(substream);
}
+/**
+ * snd_pcm_sart
+ */
int snd_pcm_start(snd_pcm_substream_t *substream)
{
SND_PCM_ACTION(start, substream, 0);
@@ -705,6 +708,9 @@
wake_up(&runtime->sleep);
}
+/**
+ * snd_pcm_stop
+ */
int snd_pcm_stop(snd_pcm_substream_t *substream, int state)
{
SND_PCM_ACTION(stop, substream, state);
@@ -781,11 +787,17 @@
wake_up(&runtime->sleep);
}
+/**
+ * snd_pcm_suspend
+ */
int snd_pcm_suspend(snd_pcm_substream_t *substream)
{
SND_PCM_ACTION(suspend, substream, 0);
}
+/**
+ * snd_pcm_suspend_all
+ */
int snd_pcm_suspend_all(snd_pcm_t *pcm)
{
snd_pcm_substream_t *substream;
@@ -978,6 +990,9 @@
runtime->status->state = SNDRV_PCM_STATE_PREPARED;
}
+/**
+ * snd_pcm_prepare
+ */
int snd_pcm_prepare(snd_pcm_substream_t *substream)
{
int res;
Index: pcm_sgbuf.c
===================================================================
RCS file: /cvsroot/alsa/alsa-kernel/core/pcm_sgbuf.c,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- pcm_sgbuf.c 16 Dec 2002 12:04:53 -0000 1.7
+++ pcm_sgbuf.c 7 Jan 2003 12:27:46 -0000 1.8
@@ -47,10 +47,19 @@
}
}
-/*
- * initialize the sg buffer
- * assigned to substream->dma_private.
- * initialize the table with the given size.
+/**
+ * snd_pcm_sgbuf_init - initialize the sg buffer
+ * @substream: the pcm substream instance
+ * @pci: pci device pointer
+ * @tblsize: the default table size
+ *
+ * Initializes the SG-buffer instance and assigns it to
+ * substream->dma_private. The SG-table is initialized with the
+ * given size.
+ *
+ * Call this function in the open callback.
+ *
+ * Returns zero if successful, or a negative error code on failure.
*/
int snd_pcm_sgbuf_init(snd_pcm_substream_t *substream, struct pci_dev *pci, int
tblsize)
{
@@ -73,8 +82,15 @@
return 0;
}
-/*
- * release all pages and free the sgbuf instance
+/**
+ * snd_pcm_sgbuf_delete - release all pages and free the sgbuf instance
+ * @substream: the pcm substream instance
+ *
+ * Releaes all pages and free the sgbuf instance.
+ *
+ * Call this function in the close callback.
+ *
+ * Returns zero if successful, or a negative error code on failure.
*/
int snd_pcm_sgbuf_delete(snd_pcm_substream_t *substream)
{
@@ -142,10 +158,19 @@
#define snd_pci_alloc_page(pci, addrp) snd_malloc_pci_pages(pci, PAGE_SIZE, addrp)
#endif
-/*
- * allocate sg buffer table with the given byte size.
- * if the buffer table already exists, try to resize it.
- * call this from hw_params callback.
+/**
+ * snd_pcm_sgbuf_alloc - allocate the pages for the SG buffer
+ * @substream: the pcm substream instance
+ * @size: the requested buffer size in bytes
+ *
+ * Allocates the buffer pages for the given size and updates the
+ * sg buffer table. If the buffer table already exists, try to resize
+ * it.
+ *
+ * Call this function from hw_params callback.
+ *
+ * Returns 1 if the buffer is changed, 0 if not changed, or a negative
+ * code on failure.
*/
int snd_pcm_sgbuf_alloc(snd_pcm_substream_t *substream, size_t size)
{
@@ -192,10 +217,15 @@
return changed;
}
-/*
- * free the sg buffer
- * the table is kept.
- * call this from hw_free callback.
+/**
+ * snd_pcm_sgbuf_free - free the sg buffer
+ * @substream: the pcm substream instance
+ *
+ * Releases the pages. The SG-table itself is still kept.
+ *
+ * Call this function from hw_free callback.
+ *
+ * Returns zero if successful, or a negative error code on failure.
*/
int snd_pcm_sgbuf_free(snd_pcm_substream_t *substream)
{
@@ -221,9 +251,13 @@
return sgbuf->table[idx].buf;
}
-/*
- * get the page struct at the given offset
- * used as the page callback of pcm ops
+/**
+ * snd_pcm_sgbuf_ops_page - get the page struct at the given offset
+ * @substream: the pcm substream instance
+ * @offset: the buffer offset
+ *
+ * Returns the page struct at the given buffer offset.
+ * Used as the page callback of PCM ops.
*/
struct page *snd_pcm_sgbuf_ops_page(snd_pcm_substream_t *substream, unsigned long
offset)
{
@@ -324,7 +358,9 @@
return 0;
}
-/*
+/**
+ * snd_pcm_sgbuf_ops_copy_playback - copy callback for playback pcm ops
+ *
* copy callback for playback pcm ops
*/
int snd_pcm_sgbuf_ops_copy_playback(snd_pcm_substream_t *substream, int channel,
@@ -340,7 +376,9 @@
}
}
-/*
+/**
+ * snd_pcm_sgbuf_ops_copy_capture - copy callback for capture pcm ops
+ *
* copy callback for capture pcm ops
*/
int snd_pcm_sgbuf_ops_copy_capture(snd_pcm_substream_t *substream, int channel,
@@ -356,7 +394,9 @@
}
}
-/*
+/**
+ * snd_pcm_sgbuf_ops_silence - silence callback for pcm ops
+ *
* silence callback for pcm ops
*/
int snd_pcm_sgbuf_ops_silence(snd_pcm_substream_t *substream, int channel,
Index: rawmidi.c
===================================================================
RCS file: /cvsroot/alsa/alsa-kernel/core/rawmidi.c,v
retrieving revision 1.29
retrieving revision 1.30
diff -u -r1.29 -r1.30
--- rawmidi.c 19 Dec 2002 15:59:17 -0000 1.29
+++ rawmidi.c 7 Jan 2003 12:27:46 -0000 1.30
@@ -815,6 +815,16 @@
return -ENOIOCTLCMD;
}
+/**
+ * snd_rawmidi_receive - receive the input data from the device
+ * @substream: the rawmidi substream
+ * @buffer: the buffer pointer
+ * @count: the data size to read
+ *
+ * Reads the data from the internal buffer.
+ *
+ * Returns the size of read data, or a negative error code on failure.
+ */
int snd_rawmidi_receive(snd_rawmidi_substream_t * substream, const unsigned char
*buffer, int count)
{
unsigned long flags;
@@ -959,6 +969,12 @@
return result;
}
+/**
+ * snd_rawmidi_transmit_empty - check whether the output buffer is empty
+ * @substream: the rawmidi substream
+ *
+ * Returns 1 if the internal output buffer is empty, 0 if not.
+ */
int snd_rawmidi_transmit_empty(snd_rawmidi_substream_t * substream)
{
snd_rawmidi_runtime_t *runtime = substream->runtime;
@@ -977,6 +993,20 @@
return result;
}
+/**
+ * snd_rawmidi_transmit_peek - copy data from the internal buffer
+ * @substream: the rawmidi substream
+ * @buffer: the buffer pointer
+ * @count: data size to transfer
+ *
+ * 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.
+ *
+ * Returns the size of copied data, or a negative error code on failure.
+ */
int snd_rawmidi_transmit_peek(snd_rawmidi_substream_t * substream, unsigned char
*buffer, int count)
{
unsigned long flags;
@@ -1014,6 +1044,17 @@
return result;
}
+/**
+ * snd_rawmidi_transmit_ack - acknowledge the transmission
+ * @substream: the rawmidi substream
+ * @count: the tranferred count
+ *
+ * Advances the hardware pointer for the internal output buffer with
+ * the given size and updates the condition.
+ * Call after the transmission is finished.
+ *
+ * Returns the advanced size if successful, or a negative error code on failure.
+ */
int snd_rawmidi_transmit_ack(snd_rawmidi_substream_t * substream, int count)
{
unsigned long flags;
@@ -1041,6 +1082,16 @@
return count;
}
+/**
+ * snd_rawmidi_transmit - copy from the buffer to the device
+ * @substream: the rawmidi substream
+ * @buf: the buffer pointer
+ * @count: the data size to transfer
+ *
+ * Copies data from the buffer to the device and advances the pointer.
+ *
+ * Returns the copied size if successful, or a negative error code on failure.
+ */
int snd_rawmidi_transmit(snd_rawmidi_substream_t * substream, unsigned char *buffer,
int count)
{
count = snd_rawmidi_transmit_peek(substream, buffer, count);
@@ -1304,6 +1355,20 @@
return 0;
}
+/**
+ * snd_rawmidi_new - create a rawmidi instance
+ * @card: the card instance
+ * @id: the id string
+ * @device: the device index
+ * @output_count: the number of output streams
+ * @input_count: the number of input streams
+ * @rrawmidi: the pointer to store the new rawmidi instance
+ *
+ * Creates a new rawmidi instance.
+ * Use snd_rawmidi_set_ops() to set the operators to the new instance.
+ *
+ * Returns zero if successful, or a negative error code on failure.
+ */
int snd_rawmidi_new(snd_card_t * card, char *id, int device,
int output_count, int input_count,
snd_rawmidi_t ** rrawmidi)
@@ -1513,6 +1578,14 @@
return snd_rawmidi_free(rmidi);
}
+/**
+ * snd_rawmidi_set_ops - set the rawmidi operators
+ * @rmidi: the rawmidi instance
+ * @stream: the stream direction, SNDRV_RAWMIDI_STREAM_XXX
+ * @ops: the operator table
+ *
+ * Sets the rawmidi operators for the given stream direction.
+ */
void snd_rawmidi_set_ops(snd_rawmidi_t *rmidi, int stream, snd_rawmidi_ops_t *ops)
{
struct list_head *list;
Index: sound.c
===================================================================
RCS file: /cvsroot/alsa/alsa-kernel/core/sound.c,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -r1.31 -r1.32
--- sound.c 7 Jan 2003 10:36:28 -0000 1.31
+++ sound.c 7 Jan 2003 12:27:46 -0000 1.32
@@ -73,6 +73,13 @@
#ifdef CONFIG_KMOD
+/**
+ * snd_request_card - try to load the card module
+ * @card: the card number
+ *
+ * Tries to load the module "snd-card-X" for the given card number
+ * via KMOD. Returns immediately if already loaded.
+ */
void snd_request_card(int card)
{
char str[32];
@@ -188,6 +195,19 @@
return minor;
}
+/**
+ * snd_register_device - Register the ALSA device file for the card
+ * @type: the device type, SNDRV_DEVICE_TYPE_XXX
+ * @card: the card instance
+ * @dev: the device index
+ * @reg: the snd_minor_t record
+ * @name: the device file name
+ *
+ * Registers an ALSA device file for the given card.
+ * The operators have to be set in reg parameter.
+ *
+ * Retrurns zero if successful, or a negative error code on failure.
+ */
int snd_register_device(int type, snd_card_t * card, int dev, snd_minor_t * reg,
const char *name)
{
int minor = snd_kernel_minor(type, card, dev);
@@ -215,6 +235,17 @@
return 0;
}
+/**
+ * snd_unregister_device - unregister the device on the given card
+ * @type: the device type, SNDRV_DEVICE_TYPE_XXX
+ * @card: the card instance
+ * @dev: the device index
+ *
+ * Unregisters the device file already registered via
+ * snd_register_device().
+ *
+ * Returns zero if sucecessful, or a negative error code on failure
+ */
int snd_unregister_device(int type, snd_card_t * card, int dev)
{
int minor = snd_kernel_minor(type, card, dev);
-------------------------------------------------------
This SF.NET email is sponsored by:
SourceForge Enterprise Edition + IBM + LinuxWorld = Something 2 See!
http://www.vasoftware.com
_______________________________________________
Alsa-cvslog mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/alsa-cvslog
