1<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><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></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 /* -- timer -- */ 77 unsigned int timer_resolution; /* timer resolution */ 78 79 /* -- DMA -- */ 80 unsigned char *dma_area; /* DMA area */ 81 dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */ 82 size_t dma_bytes; /* size of DMA area */ 83 84 struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */ 85 86#if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE) 87 /* -- OSS things -- */ 88 struct snd_pcm_oss_runtime oss; 89#endif 90}; 91 92 </pre></div><p> 93 </p><p> 94 For the operators (callbacks) of each sound driver, most of 95 these records are supposed to be read-only. Only the PCM 96 middle-layer changes / updates them. The exceptions are 97 the hardware description (hw) DMA buffer information and the 98 private data. Besides, if you use the standard buffer allocation 99 method via <code class="function">snd_pcm_lib_malloc_pages()</code>, 100 you don't need to set the DMA buffer information by yourself. 101 </p><p> 102 In the sections below, important records are explained. 103 </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> 104 The hardware descriptor (struct <span class="structname">snd_pcm_hardware</span>) 105 contains the definitions of the fundamental hardware 106 configuration. Above all, you'll need to define this in 107 <a class="link" href="pcm-interface-operators.html#pcm-interface-operators-open-callback" title="open callback"><em class="citetitle"> 108 the open callback</em></a>. 109 Note that the runtime instance holds the copy of the 110 descriptor, not the pointer to the existing descriptor. That 111 is, in the open callback, you can modify the copied descriptor 112 (<code class="constant">runtime->hw</code>) as you need. For example, if the maximum 113 number of channels is 1 only on some chip models, you can 114 still use the same hardware descriptor and change the 115 channels_max later: 116 </p><div class="informalexample"><pre class="programlisting"> 117 118 struct snd_pcm_runtime *runtime = substream->runtime; 119 ... 120 runtime->hw = snd_mychip_playback_hw; /* common definition */ 121 if (chip->model == VERY_OLD_ONE) 122 runtime->hw.channels_max = 1; 123 124 </pre></div><p> 125 </p><p> 126 Typically, you'll have a hardware descriptor as below: 127 </p><div class="informalexample"><pre class="programlisting"> 128 129 static struct snd_pcm_hardware snd_mychip_playback_hw = { 130 .info = (SNDRV_PCM_INFO_MMAP | 131 SNDRV_PCM_INFO_INTERLEAVED | 132 SNDRV_PCM_INFO_BLOCK_TRANSFER | 133 SNDRV_PCM_INFO_MMAP_VALID), 134 .formats = SNDRV_PCM_FMTBIT_S16_LE, 135 .rates = SNDRV_PCM_RATE_8000_48000, 136 .rate_min = 8000, 137 .rate_max = 48000, 138 .channels_min = 2, 139 .channels_max = 2, 140 .buffer_bytes_max = 32768, 141 .period_bytes_min = 4096, 142 .period_bytes_max = 32768, 143 .periods_min = 1, 144 .periods_max = 1024, 145 }; 146 147 </pre></div><p> 148 </p><p> 149 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 150 The <em class="structfield"><code>info</code></em> field contains the type and 151 capabilities of this pcm. The bit flags are defined in 152 <code class="filename"><sound/asound.h></code> as 153 <code class="constant">SNDRV_PCM_INFO_XXX</code>. Here, at least, you 154 have to specify whether the mmap is supported and which 155 interleaved format is supported. 156 When the hardware supports mmap, add the 157 <code class="constant">SNDRV_PCM_INFO_MMAP</code> flag here. When the 158 hardware supports the interleaved or the non-interleaved 159 formats, <code class="constant">SNDRV_PCM_INFO_INTERLEAVED</code> or 160 <code class="constant">SNDRV_PCM_INFO_NONINTERLEAVED</code> flag must 161 be set, respectively. If both are supported, you can set both, 162 too. 163 </p><p> 164 In the above example, <code class="constant">MMAP_VALID</code> and 165 <code class="constant">BLOCK_TRANSFER</code> are specified for the OSS mmap 166 mode. Usually both are set. Of course, 167 <code class="constant">MMAP_VALID</code> is set only if the mmap is 168 really supported. 169 </p><p> 170 The other possible flags are 171 <code class="constant">SNDRV_PCM_INFO_PAUSE</code> and 172 <code class="constant">SNDRV_PCM_INFO_RESUME</code>. The 173 <code class="constant">PAUSE</code> bit means that the pcm supports the 174 <span class="quote">“<span class="quote">pause</span>”</span> operation, while the 175 <code class="constant">RESUME</code> bit means that the pcm supports 176 the full <span class="quote">“<span class="quote">suspend/resume</span>”</span> operation. 177 If the <code class="constant">PAUSE</code> flag is set, 178 the <em class="structfield"><code>trigger</code></em> callback below 179 must handle the corresponding (pause push/release) commands. 180 The suspend/resume trigger commands can be defined even without 181 the <code class="constant">RESUME</code> flag. See <a class="link" href="power-management.html" title="Chapter 13. Power Management"><em class="citetitle"> 182 Power Management</em></a> section for details. 183 </p><p> 184 When the PCM substreams can be synchronized (typically, 185 synchronized start/stop of a playback and a capture streams), 186 you can give <code class="constant">SNDRV_PCM_INFO_SYNC_START</code>, 187 too. In this case, you'll need to check the linked-list of 188 PCM substreams in the trigger callback. This will be 189 described in the later section. 190 </p></li><li class="listitem"><p> 191 <em class="structfield"><code>formats</code></em> field contains the bit-flags 192 of supported formats (<code class="constant">SNDRV_PCM_FMTBIT_XXX</code>). 193 If the hardware supports more than one format, give all or'ed 194 bits. In the example above, the signed 16bit little-endian 195 format is specified. 196 </p></li><li class="listitem"><p> 197 <em class="structfield"><code>rates</code></em> field contains the bit-flags of 198 supported rates (<code class="constant">SNDRV_PCM_RATE_XXX</code>). 199 When the chip supports continuous rates, pass 200 <code class="constant">CONTINUOUS</code> bit additionally. 201 The pre-defined rate bits are provided only for typical 202 rates. If your chip supports unconventional rates, you need to add 203 the <code class="constant">KNOT</code> bit and set up the hardware 204 constraint manually (explained later). 205 </p></li><li class="listitem"><p> 206 <em class="structfield"><code>rate_min</code></em> and 207 <em class="structfield"><code>rate_max</code></em> define the minimum and 208 maximum sample rate. This should correspond somehow to 209 <em class="structfield"><code>rates</code></em> bits. 210 </p></li><li class="listitem"><p> 211 <em class="structfield"><code>channel_min</code></em> and 212 <em class="structfield"><code>channel_max</code></em> 213 define, as you might already expected, the minimum and maximum 214 number of channels. 215 </p></li><li class="listitem"><p> 216 <em class="structfield"><code>buffer_bytes_max</code></em> defines the 217 maximum buffer size in bytes. There is no 218 <em class="structfield"><code>buffer_bytes_min</code></em> field, since 219 it can be calculated from the minimum period size and the 220 minimum number of periods. 221 Meanwhile, <em class="structfield"><code>period_bytes_min</code></em> and 222 define the minimum and maximum size of the period in bytes. 223 <em class="structfield"><code>periods_max</code></em> and 224 <em class="structfield"><code>periods_min</code></em> define the maximum and 225 minimum number of periods in the buffer. 226 </p><p> 227 The <span class="quote">“<span class="quote">period</span>”</span> is a term that corresponds to 228 a fragment in the OSS world. The period defines the size at 229 which a PCM interrupt is generated. This size strongly 230 depends on the hardware. 231 Generally, the smaller period size will give you more 232 interrupts, that is, more controls. 233 In the case of capture, this size defines the input latency. 234 On the other hand, the whole buffer size defines the 235 output latency for the playback direction. 236 </p></li><li class="listitem"><p> 237 There is also a field <em class="structfield"><code>fifo_size</code></em>. 238 This specifies the size of the hardware FIFO, but currently it 239 is neither used in the driver nor in the alsa-lib. So, you 240 can ignore this field. 241 </p></li></ul></div><p> 242 </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> 243 Ok, let's go back again to the PCM runtime records. 244 The most frequently referred records in the runtime instance are 245 the PCM configurations. 246 The PCM configurations are stored in the runtime instance 247 after the application sends <span class="type">hw_params</span> data via 248 alsa-lib. There are many fields copied from hw_params and 249 sw_params structs. For example, 250 <em class="structfield"><code>format</code></em> holds the format type 251 chosen by the application. This field contains the enum value 252 <code class="constant">SNDRV_PCM_FORMAT_XXX</code>. 253 </p><p> 254 One thing to be noted is that the configured buffer and period 255 sizes are stored in <span class="quote">“<span class="quote">frames</span>”</span> in the runtime. 256 In the ALSA world, 1 frame = channels * samples-size. 257 For conversion between frames and bytes, you can use the 258 <code class="function">frames_to_bytes()</code> and 259 <code class="function">bytes_to_frames()</code> helper functions. 260 </p><div class="informalexample"><pre class="programlisting"> 261 262 period_bytes = frames_to_bytes(runtime, runtime->period_size); 263 264 </pre></div><p> 265 </p><p> 266 Also, many software parameters (sw_params) are 267 stored in frames, too. Please check the type of the field. 268 <span class="type">snd_pcm_uframes_t</span> is for the frames as unsigned 269 integer while <span class="type">snd_pcm_sframes_t</span> is for the frames 270 as signed integer. 271 </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> 272 The DMA buffer is defined by the following four fields, 273 <em class="structfield"><code>dma_area</code></em>, 274 <em class="structfield"><code>dma_addr</code></em>, 275 <em class="structfield"><code>dma_bytes</code></em> and 276 <em class="structfield"><code>dma_private</code></em>. 277 The <em class="structfield"><code>dma_area</code></em> holds the buffer 278 pointer (the logical address). You can call 279 <code class="function">memcpy</code> from/to 280 this pointer. Meanwhile, <em class="structfield"><code>dma_addr</code></em> 281 holds the physical address of the buffer. This field is 282 specified only when the buffer is a linear buffer. 283 <em class="structfield"><code>dma_bytes</code></em> holds the size of buffer 284 in bytes. <em class="structfield"><code>dma_private</code></em> is used for 285 the ALSA DMA allocator. 286 </p><p> 287 If you use a standard ALSA function, 288 <code class="function">snd_pcm_lib_malloc_pages()</code>, for 289 allocating the buffer, these fields are set by the ALSA middle 290 layer, and you should <span class="emphasis"><em>not</em></span> change them by 291 yourself. You can read them but not write them. 292 On the other hand, if you want to allocate the buffer by 293 yourself, you'll need to manage it in hw_params callback. 294 At least, <em class="structfield"><code>dma_bytes</code></em> is mandatory. 295 <em class="structfield"><code>dma_area</code></em> is necessary when the 296 buffer is mmapped. If your driver doesn't support mmap, this 297 field is not necessary. <em class="structfield"><code>dma_addr</code></em> 298 is also optional. You can use 299 <em class="structfield"><code>dma_private</code></em> as you like, too. 300 </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> 301 The running status can be referred via <code class="constant">runtime->status</code>. 302 This is the pointer to the struct <span class="structname">snd_pcm_mmap_status</span> 303 record. For example, you can get the current DMA hardware 304 pointer via <code class="constant">runtime->status->hw_ptr</code>. 305 </p><p> 306 The DMA application pointer can be referred via 307 <code class="constant">runtime->control</code>, which points to the 308 struct <span class="structname">snd_pcm_mmap_control</span> record. 309 However, accessing directly to this value is not recommended. 310 </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> 311 You can allocate a record for the substream and store it in 312 <code class="constant">runtime->private_data</code>. Usually, this 313 is done in 314 <a class="link" href="pcm-interface-operators.html#pcm-interface-operators-open-callback" title="open callback"><em class="citetitle"> 315 the open callback</em></a>. 316 Don't mix this with <code class="constant">pcm->private_data</code>. 317 The <code class="constant">pcm->private_data</code> usually points to the 318 chip instance assigned statically at the creation of PCM, while the 319 <code class="constant">runtime->private_data</code> points to a dynamic 320 data structure created at the PCM open callback. 321 322 </p><div class="informalexample"><pre class="programlisting"> 323 324 static int snd_xxx_open(struct snd_pcm_substream *substream) 325 { 326 struct my_pcm_data *data; 327 .... 328 data = kmalloc(sizeof(*data), GFP_KERNEL); 329 substream->runtime->private_data = data; 330 .... 331 } 332 333 </pre></div><p> 334 </p><p> 335 The allocated object must be released in 336 <a class="link" href="pcm-interface-operators.html#pcm-interface-operators-open-callback" title="open callback"><em class="citetitle"> 337 the close callback</em></a>. 338 </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> 339