1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Runtime Pointer - The Chest of PCM Information</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="Writing an ALSA Driver"><link rel="up" href="pcm-interface.html" title="Chapter 5. PCM Interface"><link rel="prev" href="pcm-interface-destructor.html" title="... And the Destructor?"><link rel="next" href="pcm-interface-operators.html" title="Operators"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Runtime Pointer - The Chest of PCM Information</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="pcm-interface-destructor.html">Prev</a> </td><th width="60%" align="center">Chapter 5. PCM Interface</th><td width="20%" align="right"> <a accesskey="n" href="pcm-interface-operators.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="pcm-interface-runtime"></a>Runtime Pointer - The Chest of PCM Information</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="pcm-interface-runtime.html#pcm-interface-runtime-hw">Hardware Description</a></span></dt><dt><span class="section"><a href="pcm-interface-runtime.html#pcm-interface-runtime-config">PCM Configurations</a></span></dt><dt><span class="section"><a href="pcm-interface-runtime.html#pcm-interface-runtime-dma">DMA Buffer Information</a></span></dt><dt><span class="section"><a href="pcm-interface-runtime.html#pcm-interface-runtime-status">Running Status</a></span></dt><dt><span class="section"><a href="pcm-interface-runtime.html#pcm-interface-runtime-private">Private Data</a></span></dt><dt><span class="section"><a href="pcm-interface-runtime.html#pcm-interface-runtime-intr">Interrupt Callbacks</a></span></dt></dl></div><p> 2 When the PCM substream is opened, a PCM runtime instance is 3 allocated and assigned to the substream. This pointer is 4 accessible via <code class="constant">substream->runtime</code>. 5 This runtime pointer holds most information you need 6 to control the PCM: the copy of hw_params and sw_params configurations, the buffer 7 pointers, mmap records, spinlocks, etc. 8 </p><p> 9 The definition of runtime instance is found in 10 <code class="filename"><sound/pcm.h></code>. Here are 11 the contents of this file: 12 </p><div class="informalexample"><pre class="programlisting"> 13 14struct _snd_pcm_runtime { 15 /* -- Status -- */ 16 struct snd_pcm_substream *trigger_master; 17 snd_timestamp_t trigger_tstamp; /* trigger timestamp */ 18 int overrange; 19 snd_pcm_uframes_t avail_max; 20 snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */ 21 snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/ 22 23 /* -- HW params -- */ 24 snd_pcm_access_t access; /* access mode */ 25 snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */ 26 snd_pcm_subformat_t subformat; /* subformat */ 27 unsigned int rate; /* rate in Hz */ 28 unsigned int channels; /* channels */ 29 snd_pcm_uframes_t period_size; /* period size */ 30 unsigned int periods; /* periods */ 31 snd_pcm_uframes_t buffer_size; /* buffer size */ 32 unsigned int tick_time; /* tick time */ 33 snd_pcm_uframes_t min_align; /* Min alignment for the format */ 34 size_t byte_align; 35 unsigned int frame_bits; 36 unsigned int sample_bits; 37 unsigned int info; 38 unsigned int rate_num; 39 unsigned int rate_den; 40 41 /* -- SW params -- */ 42 struct timespec tstamp_mode; /* mmap timestamp is updated */ 43 unsigned int period_step; 44 unsigned int sleep_min; /* min ticks to sleep */ 45 snd_pcm_uframes_t start_threshold; 46 snd_pcm_uframes_t stop_threshold; 47 snd_pcm_uframes_t silence_threshold; /* Silence filling happens when 48 noise is nearest than this */ 49 snd_pcm_uframes_t silence_size; /* Silence filling size */ 50 snd_pcm_uframes_t boundary; /* pointers wrap point */ 51 52 snd_pcm_uframes_t silenced_start; 53 snd_pcm_uframes_t silenced_size; 54 55 snd_pcm_sync_id_t sync; /* hardware synchronization ID */ 56 57 /* -- mmap -- */ 58 volatile struct snd_pcm_mmap_status *status; 59 volatile struct snd_pcm_mmap_control *control; 60 atomic_t mmap_count; 61 62 /* -- locking / scheduling -- */ 63 spinlock_t lock; 64 wait_queue_head_t sleep; 65 struct timer_list tick_timer; 66 struct fasync_struct *fasync; 67 68 /* -- private section -- */ 69 void *private_data; 70 void (*private_free)(struct snd_pcm_runtime *runtime); 71 72 /* -- hardware description -- */ 73 struct snd_pcm_hardware hw; 74 struct snd_pcm_hw_constraints hw_constraints; 75 76 /* -- interrupt callbacks -- */ 77 void (*transfer_ack_begin)(struct snd_pcm_substream *substream); 78 void (*transfer_ack_end)(struct snd_pcm_substream *substream); 79 80 /* -- timer -- */ 81 unsigned int timer_resolution; /* timer resolution */ 82 83 /* -- DMA -- */ 84 unsigned char *dma_area; /* DMA area */ 85 dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */ 86 size_t dma_bytes; /* size of DMA area */ 87 88 struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */ 89 90#if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE) 91 /* -- OSS things -- */ 92 struct snd_pcm_oss_runtime oss; 93#endif 94}; 95 96 </pre></div><p> 97 </p><p> 98 For the operators (callbacks) of each sound driver, most of 99 these records are supposed to be read-only. Only the PCM 100 middle-layer changes / updates them. The exceptions are 101 the hardware description (hw), interrupt callbacks 102 (transfer_ack_xxx), DMA buffer information, and the private 103 data. Besides, if you use the standard buffer allocation 104 method via <code class="function">snd_pcm_lib_malloc_pages()</code>, 105 you don't need to set the DMA buffer information by yourself. 106 </p><p> 107 In the sections below, important records are explained. 108 </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="pcm-interface-runtime-hw"></a>Hardware Description</h3></div></div></div><p> 109 The hardware descriptor (struct <span class="structname">snd_pcm_hardware</span>) 110 contains the definitions of the fundamental hardware 111 configuration. Above all, you'll need to define this in 112 <a class="link" href="pcm-interface-operators.html#pcm-interface-operators-open-callback" title="open callback"><em class="citetitle"> 113 the open callback</em></a>. 114 Note that the runtime instance holds the copy of the 115 descriptor, not the pointer to the existing descriptor. That 116 is, in the open callback, you can modify the copied descriptor 117 (<code class="constant">runtime->hw</code>) as you need. For example, if the maximum 118 number of channels is 1 only on some chip models, you can 119 still use the same hardware descriptor and change the 120 channels_max later: 121 </p><div class="informalexample"><pre class="programlisting"> 122 123 struct snd_pcm_runtime *runtime = substream->runtime; 124 ... 125 runtime->hw = snd_mychip_playback_hw; /* common definition */ 126 if (chip->model == VERY_OLD_ONE) 127 runtime->hw.channels_max = 1; 128 129 </pre></div><p> 130 </p><p> 131 Typically, you'll have a hardware descriptor as below: 132 </p><div class="informalexample"><pre class="programlisting"> 133 134 static struct snd_pcm_hardware snd_mychip_playback_hw = { 135 .info = (SNDRV_PCM_INFO_MMAP | 136 SNDRV_PCM_INFO_INTERLEAVED | 137 SNDRV_PCM_INFO_BLOCK_TRANSFER | 138 SNDRV_PCM_INFO_MMAP_VALID), 139 .formats = SNDRV_PCM_FMTBIT_S16_LE, 140 .rates = SNDRV_PCM_RATE_8000_48000, 141 .rate_min = 8000, 142 .rate_max = 48000, 143 .channels_min = 2, 144 .channels_max = 2, 145 .buffer_bytes_max = 32768, 146 .period_bytes_min = 4096, 147 .period_bytes_max = 32768, 148 .periods_min = 1, 149 .periods_max = 1024, 150 }; 151 152 </pre></div><p> 153 </p><p> 154 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 155 The <em class="structfield"><code>info</code></em> field contains the type and 156 capabilities of this pcm. The bit flags are defined in 157 <code class="filename"><sound/asound.h></code> as 158 <code class="constant">SNDRV_PCM_INFO_XXX</code>. Here, at least, you 159 have to specify whether the mmap is supported and which 160 interleaved format is supported. 161 When the hardware supports mmap, add the 162 <code class="constant">SNDRV_PCM_INFO_MMAP</code> flag here. When the 163 hardware supports the interleaved or the non-interleaved 164 formats, <code class="constant">SNDRV_PCM_INFO_INTERLEAVED</code> or 165 <code class="constant">SNDRV_PCM_INFO_NONINTERLEAVED</code> flag must 166 be set, respectively. If both are supported, you can set both, 167 too. 168 </p><p> 169 In the above example, <code class="constant">MMAP_VALID</code> and 170 <code class="constant">BLOCK_TRANSFER</code> are specified for the OSS mmap 171 mode. Usually both are set. Of course, 172 <code class="constant">MMAP_VALID</code> is set only if the mmap is 173 really supported. 174 </p><p> 175 The other possible flags are 176 <code class="constant">SNDRV_PCM_INFO_PAUSE</code> and 177 <code class="constant">SNDRV_PCM_INFO_RESUME</code>. The 178 <code class="constant">PAUSE</code> bit means that the pcm supports the 179 <span class="quote">“<span class="quote">pause</span>”</span> operation, while the 180 <code class="constant">RESUME</code> bit means that the pcm supports 181 the full <span class="quote">“<span class="quote">suspend/resume</span>”</span> operation. 182 If the <code class="constant">PAUSE</code> flag is set, 183 the <em class="structfield"><code>trigger</code></em> callback below 184 must handle the corresponding (pause push/release) commands. 185 The suspend/resume trigger commands can be defined even without 186 the <code class="constant">RESUME</code> flag. See <a class="link" href="power-management.html" title="Chapter 13. Power Management"><em class="citetitle"> 187 Power Management</em></a> section for details. 188 </p><p> 189 When the PCM substreams can be synchronized (typically, 190 synchronized start/stop of a playback and a capture streams), 191 you can give <code class="constant">SNDRV_PCM_INFO_SYNC_START</code>, 192 too. In this case, you'll need to check the linked-list of 193 PCM substreams in the trigger callback. This will be 194 described in the later section. 195 </p></li><li class="listitem"><p> 196 <em class="structfield"><code>formats</code></em> field contains the bit-flags 197 of supported formats (<code class="constant">SNDRV_PCM_FMTBIT_XXX</code>). 198 If the hardware supports more than one format, give all or'ed 199 bits. In the example above, the signed 16bit little-endian 200 format is specified. 201 </p></li><li class="listitem"><p> 202 <em class="structfield"><code>rates</code></em> field contains the bit-flags of 203 supported rates (<code class="constant">SNDRV_PCM_RATE_XXX</code>). 204 When the chip supports continuous rates, pass 205 <code class="constant">CONTINUOUS</code> bit additionally. 206 The pre-defined rate bits are provided only for typical 207 rates. If your chip supports unconventional rates, you need to add 208 the <code class="constant">KNOT</code> bit and set up the hardware 209 constraint manually (explained later). 210 </p></li><li class="listitem"><p> 211 <em class="structfield"><code>rate_min</code></em> and 212 <em class="structfield"><code>rate_max</code></em> define the minimum and 213 maximum sample rate. This should correspond somehow to 214 <em class="structfield"><code>rates</code></em> bits. 215 </p></li><li class="listitem"><p> 216 <em class="structfield"><code>channel_min</code></em> and 217 <em class="structfield"><code>channel_max</code></em> 218 define, as you might already expected, the minimum and maximum 219 number of channels. 220 </p></li><li class="listitem"><p> 221 <em class="structfield"><code>buffer_bytes_max</code></em> defines the 222 maximum buffer size in bytes. There is no 223 <em class="structfield"><code>buffer_bytes_min</code></em> field, since 224 it can be calculated from the minimum period size and the 225 minimum number of periods. 226 Meanwhile, <em class="structfield"><code>period_bytes_min</code></em> and 227 define the minimum and maximum size of the period in bytes. 228 <em class="structfield"><code>periods_max</code></em> and 229 <em class="structfield"><code>periods_min</code></em> define the maximum and 230 minimum number of periods in the buffer. 231 </p><p> 232 The <span class="quote">“<span class="quote">period</span>”</span> is a term that corresponds to 233 a fragment in the OSS world. The period defines the size at 234 which a PCM interrupt is generated. This size strongly 235 depends on the hardware. 236 Generally, the smaller period size will give you more 237 interrupts, that is, more controls. 238 In the case of capture, this size defines the input latency. 239 On the other hand, the whole buffer size defines the 240 output latency for the playback direction. 241 </p></li><li class="listitem"><p> 242 There is also a field <em class="structfield"><code>fifo_size</code></em>. 243 This specifies the size of the hardware FIFO, but currently it 244 is neither used in the driver nor in the alsa-lib. So, you 245 can ignore this field. 246 </p></li></ul></div><p> 247 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="pcm-interface-runtime-config"></a>PCM Configurations</h3></div></div></div><p> 248 Ok, let's go back again to the PCM runtime records. 249 The most frequently referred records in the runtime instance are 250 the PCM configurations. 251 The PCM configurations are stored in the runtime instance 252 after the application sends <span class="type">hw_params</span> data via 253 alsa-lib. There are many fields copied from hw_params and 254 sw_params structs. For example, 255 <em class="structfield"><code>format</code></em> holds the format type 256 chosen by the application. This field contains the enum value 257 <code class="constant">SNDRV_PCM_FORMAT_XXX</code>. 258 </p><p> 259 One thing to be noted is that the configured buffer and period 260 sizes are stored in <span class="quote">“<span class="quote">frames</span>”</span> in the runtime. 261 In the ALSA world, 1 frame = channels * samples-size. 262 For conversion between frames and bytes, you can use the 263 <code class="function">frames_to_bytes()</code> and 264 <code class="function">bytes_to_frames()</code> helper functions. 265 </p><div class="informalexample"><pre class="programlisting"> 266 267 period_bytes = frames_to_bytes(runtime, runtime->period_size); 268 269 </pre></div><p> 270 </p><p> 271 Also, many software parameters (sw_params) are 272 stored in frames, too. Please check the type of the field. 273 <span class="type">snd_pcm_uframes_t</span> is for the frames as unsigned 274 integer while <span class="type">snd_pcm_sframes_t</span> is for the frames 275 as signed integer. 276 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="pcm-interface-runtime-dma"></a>DMA Buffer Information</h3></div></div></div><p> 277 The DMA buffer is defined by the following four fields, 278 <em class="structfield"><code>dma_area</code></em>, 279 <em class="structfield"><code>dma_addr</code></em>, 280 <em class="structfield"><code>dma_bytes</code></em> and 281 <em class="structfield"><code>dma_private</code></em>. 282 The <em class="structfield"><code>dma_area</code></em> holds the buffer 283 pointer (the logical address). You can call 284 <code class="function">memcpy</code> from/to 285 this pointer. Meanwhile, <em class="structfield"><code>dma_addr</code></em> 286 holds the physical address of the buffer. This field is 287 specified only when the buffer is a linear buffer. 288 <em class="structfield"><code>dma_bytes</code></em> holds the size of buffer 289 in bytes. <em class="structfield"><code>dma_private</code></em> is used for 290 the ALSA DMA allocator. 291 </p><p> 292 If you use a standard ALSA function, 293 <code class="function">snd_pcm_lib_malloc_pages()</code>, for 294 allocating the buffer, these fields are set by the ALSA middle 295 layer, and you should <span class="emphasis"><em>not</em></span> change them by 296 yourself. You can read them but not write them. 297 On the other hand, if you want to allocate the buffer by 298 yourself, you'll need to manage it in hw_params callback. 299 At least, <em class="structfield"><code>dma_bytes</code></em> is mandatory. 300 <em class="structfield"><code>dma_area</code></em> is necessary when the 301 buffer is mmapped. If your driver doesn't support mmap, this 302 field is not necessary. <em class="structfield"><code>dma_addr</code></em> 303 is also optional. You can use 304 <em class="structfield"><code>dma_private</code></em> as you like, too. 305 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="pcm-interface-runtime-status"></a>Running Status</h3></div></div></div><p> 306 The running status can be referred via <code class="constant">runtime->status</code>. 307 This is the pointer to the struct <span class="structname">snd_pcm_mmap_status</span> 308 record. For example, you can get the current DMA hardware 309 pointer via <code class="constant">runtime->status->hw_ptr</code>. 310 </p><p> 311 The DMA application pointer can be referred via 312 <code class="constant">runtime->control</code>, which points to the 313 struct <span class="structname">snd_pcm_mmap_control</span> record. 314 However, accessing directly to this value is not recommended. 315 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="pcm-interface-runtime-private"></a>Private Data</h3></div></div></div><p> 316 You can allocate a record for the substream and store it in 317 <code class="constant">runtime->private_data</code>. Usually, this 318 is done in 319 <a class="link" href="pcm-interface-operators.html#pcm-interface-operators-open-callback" title="open callback"><em class="citetitle"> 320 the open callback</em></a>. 321 Don't mix this with <code class="constant">pcm->private_data</code>. 322 The <code class="constant">pcm->private_data</code> usually points to the 323 chip instance assigned statically at the creation of PCM, while the 324 <code class="constant">runtime->private_data</code> points to a dynamic 325 data structure created at the PCM open callback. 326 327 </p><div class="informalexample"><pre class="programlisting"> 328 329 static int snd_xxx_open(struct snd_pcm_substream *substream) 330 { 331 struct my_pcm_data *data; 332 .... 333 data = kmalloc(sizeof(*data), GFP_KERNEL); 334 substream->runtime->private_data = data; 335 .... 336 } 337 338 </pre></div><p> 339 </p><p> 340 The allocated object must be released in 341 <a class="link" href="pcm-interface-operators.html#pcm-interface-operators-open-callback" title="open callback"><em class="citetitle"> 342 the close callback</em></a>. 343 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="pcm-interface-runtime-intr"></a>Interrupt Callbacks</h3></div></div></div><p> 344 The field <em class="structfield"><code>transfer_ack_begin</code></em> and 345 <em class="structfield"><code>transfer_ack_end</code></em> are called at 346 the beginning and at the end of 347 <code class="function">snd_pcm_period_elapsed()</code>, respectively. 348 </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pcm-interface-destructor.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pcm-interface.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pcm-interface-operators.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">... And the Destructor? </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Operators</td></tr></table></div></body></html> 349