device/class/pcm.h header reference
[Devices support library module]
The source code of this header can be browsed online.
Description [link]
See also DRIVER_CLASS_PCM.
Purpose [link]
This class provides access to isochronous sample streams taken at a constant sampling rate. This is most usually suited for sound devices, but may be used for other equivalent data streams.
Because this kind of device cannot tolerate software to be late (there is no backpressure mechanism), it uses the request kroutine to indicate requirement for software to refill buffers.
Buffers are allocated by the device, either to general purpose system RAM, or in dedicated memory space. This is up to the driver.
Application may require multiple streams to be handled synchronously by the device. Either all in the same direction or not. Because some hardware will require samples to be interleaved, driver can enforce data sample stride it needs. It is up to the application to adapt the stream format.
Members [link]
Types [link]
- enum dev_pcm_data_direction_e
- enum dev_pcm_data_type_e
- typedef error_t (dev_pcm_request_t)(const struct device_pcm_s *accessor, struct dev_pcm_rq_s *rq)
- struct dev_pcm_rq_s
- struct device_pcm_s
- struct driver_pcm_s
Functions [link]
- void dev_pcm_rq_done(struct dev_pcm_rq_s *rq)
- struct dev_pcm_rq_s * dev_pcm_rq_from_kr(struct kroutine_s *kr)
- struct dev_pcm_rq_s * dev_pcm_rq_head(dev_request_queue_root_t *q)
- void dev_pcm_rq_init(struct dev_pcm_rq_s *rq, kroutine_exec_t *exec)
- void dev_pcm_rq_init_immediate(struct dev_pcm_rq_s *rq, kroutine_exec_t *exec)
- void dev_pcm_rq_init_queue(struct dev_pcm_rq_s *rq, kroutine_exec_t *exec, struct kroutine_queue_s *queue)
- void dev_pcm_rq_init_seq(struct dev_pcm_rq_s *rq, kroutine_exec_t *exec, struct kroutine_sequence_s *seq)
- struct dev_pcm_rq_s * dev_pcm_rq_pop(dev_request_queue_root_t *q)
- void dev_pcm_rq_pushback(dev_request_queue_root_t *q, struct dev_pcm_rq_s *rq)
- void dev_pcm_rq_remove(dev_request_queue_root_t *q, struct dev_pcm_rq_s *rq)
- struct dev_request_s * dev_pcm_rq_s_base(struct dev_pcm_rq_s *x)
- struct dev_pcm_rq_s * dev_pcm_rq_s_cast(struct dev_request_s *x)
- struct device_accessor_s * device_pcm_s_base(struct device_pcm_s *x)
- struct device_pcm_s * device_pcm_s_cast(struct device_accessor_s *x)
Macros [link]
Members detail [link]
#define DEV_PCM_END_FLAG [link]
This macro is declared in device/class/pcm.h source file, line 94.
Flag set on request kroutine when end of streaming occurs.
#define DEV_PCM_REQUEST(n) [link]
This macro is declared in device/class/pcm.h source file, line 145.
See also dev_pcm_request_t.
#define DEV_STATIC_RES_DEV_PCM(path_) [link]
This macro is declared in device/class/pcm.h source file, line 178.
This macro provides a DEV_RES_DEV_PARAM resource entry which specifies a dependency on a PCM device.
Preprocessor condition: defined( CONFIG_DEVICE_PCM )
#define DEV_STATIC_RES_DEV_PCM(path_) [link]
This macro is declared in device/class/pcm.h source file, line 182.
Documentation from alternate declaration:
This macro provides a DEV_RES_DEV_PARAM resource entry which specifies a dependency on a PCM device.
Preprocessor condition: not defined( CONFIG_DEVICE_PCM )
#define DRIVER_PCM_METHODS(prefix) [link]
This macro is declared in device/class/pcm.h source file, line 169.
See also struct driver_pcm_s.
#define __DEVICE_PCM_H__ [link]
This macro is declared in device/class/pcm.h source file, line 51.
enum dev_pcm_data_direction_e [link]
This enum is declared in device/class/pcm.h source file, line 87.
this enum defines the stream direction. Direction name is oriented from device's perspective towards exterior of the chip.
| Identifier | Description |
|---|---|
| DEV_PCM_DIR_INPUT | |
| DEV_PCM_DIR_OUTPUT |
enum dev_pcm_data_type_e [link]
This enum is declared in device/class/pcm.h source file, line 69.
this enum defines the sample format in sample buffers.
| Identifier | Description |
|---|---|
| DEV_PCM_DT_INT8 | |
| DEV_PCM_DT_UINT8 | |
| DEV_PCM_DT_INT16LE | |
| DEV_PCM_DT_UINT16LE | |
| DEV_PCM_DT_INT16BE | |
| DEV_PCM_DT_UINT16BE | |
| DEV_PCM_DT_INT32LE | |
| DEV_PCM_DT_UINT32LE | |
| DEV_PCM_DT_INT32BE | |
| DEV_PCM_DT_UINT32BE |
typedef error_t (dev_pcm_request_t)(const struct device_pcm_s *accessor, struct dev_pcm_rq_s *rq) [link]
This typedef is declared in device/class/pcm.h source file, line 163.
Pcm device class request() function type. This function allocates the buffers for all streams and starts streaming. Request kroutine will be called periodically until request is stopped or an error occurs.
frames_left must be non-zero upon calling.
Parameter list:
- dev: Pointer to device descriptor
- rq: Pointer to request
The return value is 0 if request is scheduled for starting, -ENOTSUP if some parameters are not possible
This declaration involves expansion of the DEV_PCM_REQUEST macro.
void dev_pcm_rq_done(struct dev_pcm_rq_s *rq) [link]
This function is declared in device/class/pcm.h source file, line 143.
This function invokes or schedules execution of the pcm request callback associated to the request. For use in device drivers.
struct dev_pcm_rq_s * dev_pcm_rq_from_kr(struct kroutine_s *kr) [link]
This function is declared in device/class/pcm.h source file, line 143.
This function retrieves a pointer to the request when in the request completion callback routine.
struct dev_pcm_rq_s * dev_pcm_rq_head(dev_request_queue_root_t *q) [link]
This function is declared in device/class/pcm.h source file, line 143.
This function returns the oldest pcm request in the given queue. A NULL pointer is returned if the queue is empty. For use in device drivers.
void dev_pcm_rq_init(struct dev_pcm_rq_s *rq, kroutine_exec_t *exec) [link]
This function is declared in device/class/pcm.h source file, line 143.
This function initializes the given pcm request callback. This must be used before submitting the request to a driver.
This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.
void dev_pcm_rq_init_immediate(struct dev_pcm_rq_s *rq, kroutine_exec_t *exec) [link]
This function is declared in device/class/pcm.h source file, line 143.
This function initializes the given pcm request callback. This must be used before submitting the request to a driver.
void dev_pcm_rq_init_queue(struct dev_pcm_rq_s *rq, kroutine_exec_t *exec, struct kroutine_queue_s *queue) [link]
This function is declared in device/class/pcm.h source file, line 143.
This function initializes the given pcm request callback. This must be used before submitting the request to a driver.
This is available when CONFIG_MUTEK_KROUTINE_QUEUE is defined.
void dev_pcm_rq_init_seq(struct dev_pcm_rq_s *rq, kroutine_exec_t *exec, struct kroutine_sequence_s *seq) [link]
This function is declared in device/class/pcm.h source file, line 143.
This function initializes the given pcm request callback. This must be used before submitting the request to a driver.
This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.
struct dev_pcm_rq_s * dev_pcm_rq_pop(dev_request_queue_root_t *q) [link]
This function is declared in device/class/pcm.h source file, line 143.
This function removes and return the oldest pcm request in the queue. A NULL pointer is returned if the queue is empty. For use in device drivers.
void dev_pcm_rq_pushback(dev_request_queue_root_t *q, struct dev_pcm_rq_s *rq) [link]
This function is declared in device/class/pcm.h source file, line 143.
This function insert a new pcm request at the end of the given queue. For use in device drivers.
void dev_pcm_rq_remove(dev_request_queue_root_t *q, struct dev_pcm_rq_s *rq) [link]
This function is declared in device/class/pcm.h source file, line 143.
This function removes the specified pcm request from the queue. For use in device drivers.
struct dev_pcm_rq_s [link]
This struct is declared in device/class/pcm.h source file, line 117.
this struct is the PCM request structure. Application must fill it with a sample_rate, sample_count, stream_count, and for each stream, sample_type, direction and channel_id.
If it accepts the request, driver will give effective_sample_rate, allocate buffer and fill in stride for each stream.
In order to keep the request scheduled, application must increase or overwrite frames_left in order to set it to a non-zero value. Device decrements the value on each frame, when it reaches 0, request gets stopped.
If request struct kroutine is signalled with DEV_PCM_END_FLAG set in flags (), buffers should not be used any more: they got destroyed, because of an error or because streaming got stopped by the application.
See also kroutine_exec_t.
| Field | Description |
|---|---|
| union <anonymous> { | |
| struct dev_request_s base; | |
| typeof(struct dev_request_s::error) error; | |
| typeof(struct dev_request_s::pvdata) pvdata; | |
| }; | |
| uint8_t offline_buffer_index:1; | |
| uint32_t sample_rate; | |
| uint32_t effective_sample_rate; | |
| size_t stream_count; | |
| size_t sample_count; | |
| atomic_t frames_left; | |
| struct dev_pcm_stream_s { | |
| void * buffer[2]; | |
| uint8_t stride; | |
| enum dev_pcm_data_type_e sample_type:4; | |
| enum dev_pcm_data_direction_e direction:1; | |
| uint8_t channel_id:3; | |
| } stream[0]; |
struct dev_request_s * dev_pcm_rq_s_base(struct dev_pcm_rq_s *x) [link]
This function is declared in device/class/pcm.h source file, line 143.
struct dev_pcm_rq_s * dev_pcm_rq_s_cast(struct dev_request_s *x) [link]
This function is declared in device/class/pcm.h source file, line 143.
struct device_pcm_s [link]
This struct is declared in DRIVER_CLASS_TYPES function like macro expansion, line 18 in device/class/pcm.h source file, line 167.
This struct is the device accessor object type for the pcm device class. This accessor must be initialized by calling the device_get_accessor function.
See also DRIVER_CLASS_PCM, struct device_accessor_s and Device accessor.
| Field | Description |
|---|---|
| union <anonymous> { | |
| struct device_accessor_s base; | |
| struct <anonymous> { | |
| struct device_s * dev; | |
| struct driver_pcm_s * api; | |
| uint_fast8_t number; | |
| }; | |
| }; |
struct device_accessor_s * device_pcm_s_base(struct device_pcm_s *x) [link]
This function is declared in DRIVER_CLASS_TYPES function like macro expansion, line 39 in device/class/pcm.h source file, line 167.
This function casts a pcm device accessor to a generic device accessor
struct device_pcm_s * device_pcm_s_cast(struct device_accessor_s *x) [link]
This function is declared in DRIVER_CLASS_TYPES function like macro expansion, line 32 in device/class/pcm.h source file, line 167.
This function casts a generic device accessor to a pcm device accessor
struct driver_pcm_s [link]
This struct is declared in DRIVER_CLASS_TYPES function like macro expansion, line 5 in device/class/pcm.h source file, line 167.
This struct is the driver API descriptor for the pcm device class.
See also DRIVER_CLASS_PCM and struct driver_class_s.
| Field | Description |
|---|---|
| uint16_t class_; | |
| uint16_t ctx_offset; | |
| dev_pcm_request_t * f_request; |