Tracepoints for state of PCM buffer¶

This category includes four tracepoints;hwptr,applptr,xrun andhw_ptr_error.

Tracepoints for processing of PCM hardware parameters¶

This category includes two tracepoints;hw_mask_param andhw_interval_param.

In a design of ALSA PCM core, data transmission is abstracted as PCM substream.Applications manage PCM substream to maintain data transmission for PCM frames.Before starting the data transmission, applications need to configure PCMsubstream. In this procedure, PCM hardware parameters are decided byinteraction between applications and ALSA PCM core. Once decided, runtime ofthe PCM substream keeps the parameters.

The parameters are described instructsnd_pcm_hw_params. Thisstructure includes several types of parameters. Applications set preferablevalue to these parameters, then execute ioctl(2) with SNDRV_PCM_IOCTL_HW_REFINEor SNDRV_PCM_IOCTL_HW_PARAMS. The former is used just for refining availableset of parameters. The latter is used for an actual decision of the parameters.

Thestructsnd_pcm_hw_params structure has below members:

flags

Configurable. ALSA PCM core and some drivers handle this flag to selectconvenient parameters or change their behaviour.

masks

Configurable. This type of parameter is described instructsnd_mask and represent mask values. As of PCM protocolv2.0.13, three types are defined.

• SNDRV_PCM_HW_PARAM_ACCESS

• SNDRV_PCM_HW_PARAM_FORMAT

• SNDRV_PCM_HW_PARAM_SUBFORMAT

intervals

Configurable. This type of parameter is described instructsnd_interval and represent values with a range. As ofPCM protocol v2.0.13, twelve types are defined.

• SNDRV_PCM_HW_PARAM_SAMPLE_BITS

• SNDRV_PCM_HW_PARAM_FRAME_BITS

• SNDRV_PCM_HW_PARAM_CHANNELS

• SNDRV_PCM_HW_PARAM_RATE

• SNDRV_PCM_HW_PARAM_PERIOD_TIME

• SNDRV_PCM_HW_PARAM_PERIOD_SIZE

• SNDRV_PCM_HW_PARAM_PERIOD_BYTES

• SNDRV_PCM_HW_PARAM_PERIODS

• SNDRV_PCM_HW_PARAM_BUFFER_TIME

• SNDRV_PCM_HW_PARAM_BUFFER_SIZE

• SNDRV_PCM_HW_PARAM_BUFFER_BYTES

• SNDRV_PCM_HW_PARAM_TICK_TIME

rmask

Configurable. This is evaluated at ioctl(2) withSNDRV_PCM_IOCTL_HW_REFINE only. Applications can select whichmask/interval parameter can be changed by ALSA PCM core. ForSNDRV_PCM_IOCTL_HW_PARAMS, this mask is ignored and all of parametersare going to be changed.

cmask

Read-only. After returning from ioctl(2), buffer in user space forstructsnd_pcm_hw_params includes result of each operation.This mask represents which mask/interval parameter is actually changed.

info

Read-only. This represents hardware/driver capabilities as bit flagswith SNDRV_PCM_INFO_XXX. Typically, applications execute ioctl(2) withSNDRV_PCM_IOCTL_HW_REFINE to retrieve this flag, then decide candidatesof parameters and execute ioctl(2) with SNDRV_PCM_IOCTL_HW_PARAMS toconfigure PCM substream.

msbits

Read-only. This value represents available bit width in MSB side ofa PCM sample. When a parameter of SNDRV_PCM_HW_PARAM_SAMPLE_BITS wasdecided as a fixed number, this value is also calculated according toit. Else, zero. But this behaviour depends on implementations in driverside.

rate_num

Read-only. This value represents numerator of sampling rate in fractionnotation. Basically, when a parameter of SNDRV_PCM_HW_PARAM_RATE wasdecided as a single value, this value is also calculated according toit. Else, zero. But this behaviour depends on implementations in driverside.

rate_den

Read-only. This value represents denominator of sampling rate infraction notation. Basically, when a parameter ofSNDRV_PCM_HW_PARAM_RATE was decided as a single value, this value isalso calculated according to it. Else, zero. But this behaviour dependson implementations in driver side.

fifo_size

Read-only. This value represents the size of FIFO in serial soundinterface of hardware. Basically, each driver can assigns a propervalue to this parameter but some drivers intentionally set zero witha care of hardware design or data transmission protocol.

ALSA PCM core handles buffer ofstructsnd_pcm_hw_params whenapplications execute ioctl(2) with SNDRV_PCM_HW_REFINE or SNDRV_PCM_HW_PARAMS.Parameters in the buffer are changed according tostructsnd_pcm_hardware and rules of constraints in the runtime. Thestructure describes capabilities of handled hardware. The rules describesdependencies on which a parameter is decided according to several parameters.A rule has a callback function, and drivers can register arbitrary functionsto compute the target parameter. ALSA PCM core registers some rules to theruntime as a default.

Each driver can join in the interaction as long as it prepared for two stuffsin a callback ofstructsnd_pcm_ops.open.

1. In the callback, drivers are expected to change a member ofstructsnd_pcm_hardware type in the runtime, according tocapacities of corresponding hardware.

2. In the same callback, drivers are also expected to register additional rulesof constraints into the runtime when several parameters have dependenciesdue to hardware design.

The driver can refers to result of the interaction in a callback ofstructsnd_pcm_ops.hw_params, however it should not change thecontent.

Tracepoints in this category are designed to trace changes of themask/interval parameters. When ALSA PCM core changes them,hw_mask_param orhw_interval_param event is probed according to type of the changed parameter.

ALSA PCM core also has a pretty print format for each of the tracepoints. Belowis an example forhw_mask_param.

hw_mask_param: pcmC0D0p 001/023 FORMAT 00000000000000000000001000000044 00000000000000000000001000000044

Below is an example forhw_interval_param.

hw_interval_param: pcmC0D0p 000/023 BUFFER_SIZE 0 0 [0 4294967295] 0 1 [0 4294967295]

The first three fields are common. They represent name of ALSA PCM characterdevice, rules of constraint and name of the changed parameter, in order. Thefield for rules of constraint consists of two sub-fields; index of applied ruleand total number of rules added to the runtime. As an exception, the index 000means that the parameter is changed by ALSA PCM core, regardless of the rules.

The rest of field represent state of the parameter before/after changing. Thesefields are different according to type of the parameter. For parameters of masktype, the fields represent hexadecimal dump of content of the parameter. Forparameters of interval type, the fields represent values of each member ofempty,integer,openmin,min,max,openmax instructsnd_interval in this order.