Sub-devices
[Device driver]

Detailed Description

Common to read/write opened device.

Modules

group PCM fragments

PCM fragment definitions.

Data Structures

struct liso_subdev_t

Sub-Device info. More...

Sub-device status bits.

#define LISO_DEVICE_USED   0

0:device-used 1:device-free

#define LISO_DEVICE_IDLE   1

0:device-ready 1:device-idle

#define LISO_DEVICE_DEAD   2

0:device-ok 1:device-dead

#define LISO_DEVICE_SLEEP   3

0:device-awake 1:device-asleep

#define LISO_DEVICE_ALERT   4

0:No Alert 1:Alert (really awaited)

#define LISO_DEVICE_USED_MSK   (1<<LISO_DEVICE_USED)

Useful bit mask combinaisons.

#define LISO_DEVICE_IDLE_MSK   (1<<LISO_DEVICE_IDLE)

0:device-used 1:device-free

#define LISO_DEVICE_DEAD_MSK   (1<<LISO_DEVICE_DEAD)

0:device-used 1:device-free

#define LISO_DEVICE_UD_MSK   (LISO_DEVICE_USED_MSK|LISO_DEVICE_DEAD_MSK)

0:device-used 1:device-free

#define LISO_DEVICE_UID_MSK   (LISO_DEVICE_IDLE_MSK|LISO_DEVICE_UD_MSK)

0:device-used 1:device-free

Setup functions

void liso_subdev_preinit (liso_subdev_t *const sd, liso_t *const lisodsp, int chn)

Pre-init sub-device.

int liso_subdev_init (liso_subdev_t *const sd)

Init sub-device.

int liso_subdev_set_format (liso_subdev_t *const sd)

Commit requested format.

void liso_subdev_set_cur_frag (liso_subdev_t *const sd)

Copy current format information for the next frag to process.

Status functions.

const char * liso_subdev_status (const liso_subdev_t *const sd)

Get device status description string.

void liso_subdev_asleep (liso_subdev_t *const sd)

Make sub-device sleep.

void liso_subdev_wakeup_partner (liso_subdev_t *const sd)

Wake up partner sub-device(s).

int liso_subdev_has_sleepy_partner (liso_subdev_t *const sd)

Test for partner to wake up.

int liso_subdev_is_reader (const liso_subdev_t *const sd)

Test if sub-device is a reader.

int liso_subdev_is_writer (const liso_subdev_t *const sd)

Test if sub-device is a writer.

int liso_subdev_is_active (const liso_subdev_t *const sd)

Test if sub-device is active.

int liso_subdev_is_valid (const liso_subdev_t *const sd)

Test if sub-device is valid.

Locking functions

int liso_subdev_lock (liso_subdev_t *sd)

Lock sub-device.

int liso_subdev_trylock (liso_subdev_t *sd)

Try lock sub-device.

int liso_subdev_xlock (liso_subdev_t *sd, const int nonblock)

Extended lock of sub-device.

void liso_subdev_unlock (liso_subdev_t *sd)

Unlock sub-device.

Filesystem functions

int liso_writer_open (struct inode *inode, struct file *filp)

Open file operation for writer sub-devices.

int liso_reader_open (struct inode *inode, struct file *filp)

Open file operation for reader sub-devices.

int liso_subdev_release (struct inode *inode, struct file *filp)

Release sub-device.

int liso_subdev_ioctl (struct inode *inode, struct file *filp, unsigned int cmd, unsigned long arg)

ioctl file operation for sub-devices.

unsigned int liso_subdevice_poll (struct file *filp, poll_table *wait)

Poll file operation for sub-devices.

Synchronize functions

int liso_subdev_wait_idx (liso_subdev_t *const sd, const int idx)

Wait until reader reach a given idx.

int liso_subdev_synchronize (liso_subdev_t *const sd, const int lock)

Synchromize writer device with the reader.

void liso_writer_synchronize (liso_subdev_t *const writer)

Synchronize a writer device.

void liso_reader_synchronize (liso_subdev_t *const reader)

Synchronize a reader device.

int liso_writer_flush (liso_subdev_t *const writer)

Flush writer buffer.

Function Documentation

void liso_subdev_preinit ( liso_subdev_t *const sd,

liso_t *const lisodsp,

int chn

)

Pre-init sub-device.
Must be call once before using sub-device. The function assumed that the liso_subdev_t memory have been previously zeroed.

Parameters:

sd pointer to sub-device

lisodsp pointer to lisodsp device the sub-device is attached to

chn channel number (-1:reader 0-N:writer)

int liso_subdev_init ( liso_subdev_t *const sd )

Init sub-device.
Performs most initializations needed at device open time such as setting default format, resetting counters, allocating memory ... ...

Parameters:

sd pointer to sub-device

Returns:
error-code

Return values:

-ENOMEM Memory allocation failure

Warning:
The liso_subdev_t::channel value must be valid since it is used for liso_frag_t::bit setup and more important for memory allocation.

int liso_subdev_set_format ( liso_subdev_t *const sd )

Commit requested format.
Update liso_subdev_t::fmt structure with the info currently stored in the liso_subdev_t::req_fmt structure. The fmt.ok is setted and all fields in the liso_subdev_t::req_fmt structure are filled with special ``no change'' values.
The liso_subdev_t::frags siz field is modified as well to match the new sampling rate.

Note:
The new format may differ from the requested one.

Parameters:

sd pointer to sub-device

Returns:
error-code

Return values:

0 Never failed

Warning:
This function do not lock the device and should be call between liso_subdev_lock() and liso_subdev_unlock().

void liso_subdev_set_cur_frag ( liso_subdev_t *const sd ) [inline, static]

Copy current format information for the next frag to process.

Parameters:

sd pointer to sub-device

const char* liso_subdev_status ( const liso_subdev_t *const sd )

Get device status description string.
The returned string is a 3 chars long string composed with the characters 'D','I','U' respectively DEAD,IDLE,USED status bit. An uppercase value means ON and a lower case means OFF.

Parameters:

sd pointer to sub-device

Returns:
4 character long status string (always a valid string)

void liso_subdev_asleep ( liso_subdev_t *const sd ) [inline, static]

Make sub-device sleep.

Parameters:

sd pointer to sub-device

interruptible_sleep_on(sd->sleepyq);

void liso_subdev_wakeup_partner ( liso_subdev_t *const sd ) [inline, static]

Wake up partner sub-device(s).

Parameters:

sd pointer to sub-device

wake_up_interruptible(sd->wakeupq);

int liso_subdev_has_sleepy_partner ( liso_subdev_t *const sd ) [inline, static]

Test for partner to wake up.

Parameters:

sd pointer to sub-device

Return values:

0 no partner to wake-up

1 partner to wake-up

return waitqueue_active(sd->wakeupq);

int liso_subdev_is_reader ( const liso_subdev_t *const sd ) [inline, static]

Test if sub-device is a reader.

Parameters:

sd pointer to sub-device

Return values:

0 sub-device not a reader (so it is a writer)

1 sub-device is a reader

return (sd->channel == LISO_RD_CHANNEL);

int liso_subdev_is_writer ( const liso_subdev_t *const sd ) [inline, static]

Test if sub-device is a writer.

Parameters:

sd pointer to sub-device

Return values:

0 sub-device not a writer (so it is a reader)

1 sub-device is a writer

return !liso_subdev_is_reader(sd);

int liso_subdev_is_active ( const liso_subdev_t *const sd ) [inline, static]

Test if sub-device is active.

Parameters:

sd pointer to sub-device

Returns:
boolean

Return values:

1 device is ACTIVE and not DEAD and not IDLE

0 device is not ACTIVE or DEAD or IDLE

return (sd->status & LISO_DEVICE_UID_MSK) == LISO_DEVICE_USED_MSK;

int liso_subdev_is_valid ( const liso_subdev_t *const sd ) [inline, static]

Test if sub-device is valid.

Parameters:

sd pointer to sub-device

Returns:
boolean

Return values:

1 device is ACTIVE and not DEAD

0 device is not ACTIVE or DEAD

return (sd->status & LISO_DEVICE_UD_MSK) == LISO_DEVICE_USED_MSK;

int liso_subdev_lock ( liso_subdev_t * sd ) [inline, static]

Lock sub-device.

Parameters:

sd pointer to sub-device

Returns:
error-code

Return values:

0 success

!0 failed (problably interrupted by a signal or something)

return down_interruptible(&sd->lock);

int liso_subdev_trylock ( liso_subdev_t * sd ) [inline, static]

Try lock sub-device.

Parameters:

sd pointer to sub-device

Returns:
error-code

Return values:

0 lock success

!0 lock failed (problably already locked)

return down_trylock(&sd->lock);

int liso_subdev_xlock ( liso_subdev_t * sd,

const int nonblock

) [inline, static]

Extended lock of sub-device.
The extended lock functions call either liso_subdev_lock() or liso_subdev_trylock() function repectively for block and non-block mode and returns appropriate error-code if it fails (respectively -ERESTARTSYS and -EAGAIN).

Parameters:

sd pointer to sub-device

nonblock block mode (0:block other:non-block)

Returns:
error-code

Return values:

0 lock-success

-EAGAIN lock-failed in non-block mode

-ERESTARTSYS lock-failed in block mode

return !nonblock ? (!liso_subdev_lock(sd) ? 0 : -ERESTARTSYS) : (!liso_subdev_trylock(sd) ? 0 : -EAGAIN);

void liso_subdev_unlock ( liso_subdev_t * sd ) [inline, static]

Unlock sub-device.

Parameters:

sd pointer to sub-device

up(&sd->lock);

int liso_writer_open ( struct inode * inode,

struct file * filp

)

Open file operation for writer sub-devices.
Call by the lisodsp device open file operation if open mode is WR_ONLY. It is call after the resource has been reserved. This function alters the file operation and the private data in the file struct pointed by filp.

Parameters:

inode pointer to i-node.

filp pointer to file structure.

Returns:
error-code

int liso_reader_open ( struct inode * inode,

struct file * filp

)

Open file operation for reader sub-devices.
Call by the lisodsp device open file operation if open mode is RD_ONLY. It is call after the resource has been reserved. This function alters the file operation and the private data in the file struct pointed by filp.

Parameters:

inode pointer to i-node.

filp pointer to file structure.

Returns:
error-code

int liso_subdev_release ( struct inode * inode,

struct file * filp

)

Release sub-device.

Parameters:

inode pointer to i-node.

filp pointer to file structure.

Returns:
error-code

int liso_subdev_ioctl ( struct inode * inode,

struct file * filp,

unsigned int cmd,

unsigned long arg

)

ioctl file operation for sub-devices.

Parameters:

inode pointer to i-node.

filp pointer to file structure.

cmd ioctl command number

arg command parameters (usually a pointer).

Returns:
error-code

Return values:

-ENOSYS Command not implemented

-EFAULT Address error (user bad pointer)

-EINVAL Invalid parameter (unkown command or bad command parameter.

-EAGAIN Lock failed, try again

unsigned int liso_subdevice_poll ( struct file * filp,

poll_table * wait

)

Poll file operation for sub-devices.

Parameters:

filp pointer to file structure.

wait pointer to poll table.

Returns:
POLL mask

int liso_subdev_wait_idx ( liso_subdev_t *const sd,

const int idx

)

Wait until reader reach a given idx.
This function waits until the reader reaches (at least) a given idx. The sub-device should not be locked.

Warning:
If the reader sub-device is locked or If the sub-device is the reader itself it may enter an infinite loop if no other process read its file descriptor.

Parameters:

sd sub-device pointer

idx index to wait

Returns:
error-code

Return values:

-EBADR invalid request descriptor (probably closed)

-ERESTARTSYS interrupted system call (signal pending)

int liso_subdev_synchronize ( liso_subdev_t *const sd,

const int lock

)

Synchromize writer device with the reader.
This function will call the liso_reader_synchronize() or liso_writer_synchronize() respectively for a reader or a writer sub-device. If the lock parameter is non zero the function will process between a liso_subdevice_trylock() and liso_subdevice_unlock() calls else the device is assumed to be already locked.

Parameters:

sd sub-device pointer

lock try-lock if non-zero

Returns:
error-code

Return values:

-EBADR invalid request descriptor (probably closed).

-ERESTARTSYS interrupted system call (lock failed or signal pending).

void liso_writer_synchronize ( liso_subdev_t *const writer )

Synchronize a writer device.
Synchronizing a writer device means flushing out all frags older than the current reader device index. The function will set the LISO_DEVICE_IDLE status bit if neccessary and will increment liso_subdev_t::lost_frags accordingly. The device is assumed to be already locked.

Warning:
Device must be locked.

Parameters:

writer writer sub-device pointer

void liso_reader_synchronize ( liso_subdev_t *const reader )

Synchronize a reader device.
Synchronizing reader means to try to mix all writer devices avalaible frags and checks if some frags seems ready for reading (all required writer mixed). As this function is going to free some writer frag it is in charge to wake-up the writers. The device is assumed to be already locked.

Parameters:

reader reader sub-device pointer

Warning:
Device must be locked.

int liso_writer_flush ( liso_subdev_t *const writer )

Flush writer buffer.
Waiting for all writer buffers being read and set idle. It involves both frag buffer and temporary buffer. If the temporary buffer has data but not enougth to complete a frag it is filled with null pcm value.

Warning:
Writer sub-device must be locked. In case of -ERESTARTSYS return code the sub-device will be unlocked on exit in all other cases it will be locked.

Parameters:

writer writer sub-device pointer

Returns:
error-code

Return values:

-EBADR invalid request descriptor (probably closed).

-ERESTARTSYS interrupted system call (lock failed or signal pending).

lisodsp developer documentation
version 0.5.0

Generated on June 2004
by doxygen 1.3.7

Sub-devices [Device driver]

Detailed Description

Modules

Data Structures

Sub-device status bits.

Setup functions

Status functions.

Locking functions

Filesystem functions

Synchronize functions

Function Documentation

Sub-devices
[Device driver]