1 /* Copyright (c) 2014 The Chromium OS Authors. All rights reserved.
2  * Use of this source code is governed by a BSD-style license that can be
3  * found in the LICENSE file.
4  *
5  * The dev_stream structure is used for mapping streams to a device.  In
6  * addition to the rstream, other mixing information is stored here.
7  */
8 
9 #ifndef DEV_STREAM_H_
10 #define DEV_STREAM_H_
11 
12 #include <stdint.h>
13 #include <sys/time.h>
14 
15 #include "cras_types.h"
16 #include "cras_rstream.h"
17 
18 struct cras_audio_area;
19 struct cras_fmt_conv;
20 struct cras_iodev;
21 
22 /*
23  * Linked list of streams of audio from/to a client.
24  * Args:
25  *    dev_id - Index of the hw device.
26  *    stream - The rstream attached to a device.
27  *    conv - Sample rate or format converter.
28  *    conv_buffer - The buffer for converter if needed.
29  *    conv_buffer_size_frames - Size of conv_buffer in frames.
30  *    dev_rate - Sampling rate of device. This is set when dev_stream is
31  *               created.
32  */
33 struct dev_stream {
34 	unsigned int dev_id;
35 	struct cras_rstream *stream;
36 	struct cras_fmt_conv *conv;
37 	struct byte_buffer *conv_buffer;
38 	struct cras_audio_area *conv_area;
39 	unsigned int conv_buffer_size_frames;
40 	size_t dev_rate;
41 	struct dev_stream *prev, *next;
42 };
43 
44 struct dev_stream *dev_stream_create(struct cras_rstream *stream,
45 				     unsigned int dev_id,
46 				     const struct cras_audio_format *dev_fmt,
47 				     void *dev_ptr, struct timespec *cb_ts);
48 void dev_stream_destroy(struct dev_stream *dev_stream);
49 
50 /*
51  * Update the estimated sample rate of the device. For multiple active
52  * devices case, the linear resampler will be configured by the estimated
53  * rate ration of the master device and the current active device the
54  * rstream attaches to.
55  *
56  * Args:
57  *    dev_stream - The structure holding the stream.
58  *    dev_rate - The sample rate device is using.
59  *    dev_rate_ratio - The ratio of estimated rate and used rate.
60  *    master_rate_ratio - The ratio of estimated rate and used rate of
61  *        master device.
62  *    coarse_rate_adjust - The flag to indicate the direction device
63  *        sample rate should adjust to.
64  */
65 void dev_stream_set_dev_rate(struct dev_stream *dev_stream,
66 			     unsigned int dev_rate,
67 			     double dev_rate_ratio,
68 			     double master_rate_ratio,
69 			     int coarse_rate_adjust);
70 
71 /*
72  * Renders count frames from shm into dst.  Updates count if anything is
73  * written. If it's muted and the only stream zero memory.
74  * Args:
75  *    dev_stream - The struct holding the stream to mix.
76  *    format - The format of the audio device.
77  *    dst - The destination buffer for mixing.
78  *    num_to_write - The number of frames written.
79  */
80 int dev_stream_mix(struct dev_stream *dev_stream,
81 		   const struct cras_audio_format *fmt,
82 		   uint8_t *dst,
83 		   unsigned int num_to_write);
84 
85 /*
86  * Reads froms from the source into the dev_stream.
87  * Args:
88  *    dev_stream - The struct holding the stream to mix to.
89  *    area - The area to copy audio from.
90  *    area_offset - The offset at which to start reading from area.
91  *    software_gain_scaler - The software gain scaler.
92  */
93 unsigned int dev_stream_capture(struct dev_stream *dev_stream,
94 			const struct cras_audio_area *area,
95 			unsigned int area_offset,
96 			float software_gain_scaler);
97 
98 /* Returns the number of iodevs this stream has attached to. */
99 int dev_stream_attached_devs(const struct dev_stream *dev_stream);
100 
101 /* Updates the number of queued frames in dev_stream. */
102 void dev_stream_update_frames(const struct dev_stream *dev_stream);
103 
104 /*
105  * Returns the number of playback frames queued in shared memory.  This is a
106  * post-format-conversion number.  If the stream is 24k with 10 frames queued
107  * and the device is playing at 48k, 20 will be returned.
108  */
109 int dev_stream_playback_frames(const struct dev_stream *dev_stream);
110 
111 /*
112  * Returns the number of frames free to be written to in a capture stream.  This
113  * number is also post format conversion, similar to playback_frames above.
114  */
115 unsigned int dev_stream_capture_avail(const struct dev_stream *dev_stream);
116 
117 /*
118  * Returns the callback threshold, if necesary converted from a stream frame
119  * count to a device frame count.
120  */
121 unsigned int dev_stream_cb_threshold(const struct dev_stream *dev_stream);
122 
123 /*
124  * If enough samples have been captured, post them to the client.
125  * TODO(dgreid) - see if this function can be eliminated.
126  */
127 int dev_stream_capture_update_rstream(struct dev_stream *dev_stream);
128 
129 /* Updates the read buffer pointers for the stream. */
130 int dev_stream_playback_update_rstream(struct dev_stream *dev_stream);
131 
132 /* Fill ts with the time the playback sample will be played. */
133 void cras_set_playback_timestamp(size_t frame_rate,
134 				 size_t frames,
135 				 struct cras_timespec *ts);
136 
137 /* Fill ts with the time the capture sample was recorded. */
138 void cras_set_capture_timestamp(size_t frame_rate,
139 				size_t frames,
140 				struct cras_timespec *ts);
141 
142 /* Fill shm ts with the time the playback sample will be played or the capture
143  * sample was captured depending on the direction of the stream.
144  * Args:
145  *    delay_frames - The delay reproted by the device, in frames at the device's
146  *      sample rate.
147  */
148 void dev_stream_set_delay(const struct dev_stream *dev_stream,
149 			  unsigned int delay_frames);
150 
151 /* Returns if it's okay to request playback samples for this stream. */
152 int dev_stream_can_fetch(struct dev_stream *dev_stream);
153 
154 /* Ask the client for cb_threshold samples of audio to play. */
155 int dev_stream_request_playback_samples(struct dev_stream *dev_stream,
156 					const struct timespec *now);
157 
158 /*
159  * Gets the wake up time for a dev_stream.
160  * For an input stream, it considers both needed samples and proper time
161  * interval between each callbacks.
162  * Args:
163  *   dev_stream[in]: The dev_stream to check wake up time.
164  *   curr_level[in]: The current level of device.
165  *   wake_time_out[out]: A timespec for wake up time.
166  * Returns:
167  *   0 on success; negative error code on failure.
168  */
169 int dev_stream_wake_time(struct dev_stream *dev_stream,
170 			 unsigned int curr_level,
171 			 struct timespec *level_tstamp,
172 			 struct timespec *wake_time_out);
173 
174 /*
175  * Returns a non-negative fd if the fd is expecting a message and should be
176  * added to the list of descriptors to poll.
177  */
178 int dev_stream_poll_stream_fd(const struct dev_stream *dev_stream);
179 
180 static inline const struct timespec *
181 dev_stream_next_cb_ts(struct dev_stream *dev_stream)
182 {
183 	if (dev_stream->stream->flags & USE_DEV_TIMING)
184 		return NULL;
185 
186 	return &dev_stream->stream->next_cb_ts;
187 }
188 
189 static inline const struct timespec *
190 dev_stream_sleep_interval_ts(struct dev_stream *dev_stream)
191 {
192 	return &dev_stream->stream->sleep_interval_ts;
193 }
194 
195 #endif /* DEV_STREAM_H_ */
196