test-case: latency-metrics: introduce latency tests

Introduce latency tests using `JACK` Audio Connection Kit:
run `jackd` audio service, connect ports with loopback
and run `jack_iodelay` to collect latency measurements,
detect xrun-s, calculate and save statistics into a json
report file.
Optionally, run in 'trial' mode repeating measurements with
gradually reduced buffers to find the smallest latency possible.

Signed-off-by: Dmitrii Golovanov <dmitrii.golovanov@intel.com>

Author: golowanow

case-lib/jack_iodelay_metrics.awk

@@ -0,0 +1,30 @@
+#!/usr/bin/gawk -f
+
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2025 Intel Corporation. All rights reserved.
+
+# Process `jack_iodelay` output to extract latency measurements,
+# and calculate some general statistics: min, max, avg, stddev.
+# The resulting output is a json dictionary.
+
+@include "lib.awk"
+
+/^[ ]*[0-9.]+ frames[ ]+[0-9.]+ ms total roundtrip latency/ {
+  sum_frames+=$1
+  sum_ms+=$3
+  latency_frames[NR]=$1
+  latency_ms[NR]=$3
+}
+
+END {
+  if (length(latency_frames) !=0 && length(latency_ms) != 0) {
+    printf("\"metric_name\":\"roundtrip latency\", ")
+    printf("\"probes\":%d, ", length(latency_frames))
+    printf("\"avg_frames\":%0.3f, ", (length(latency_frames) ? sum(latency_frames) / length(latency_frames) : 0))
+    printf("\"min_frames\":%0.3f, \"max_frames\":%0.3f, ", min(latency_frames), max(latency_frames))
+    printf("\"avg_ms\":%0.3f, ", (length(latency_ms) ? sum(latency_ms) / length(latency_ms) : 0))
+    printf("\"min_ms\":%0.3f, \"max_ms\":%0.3f, ", min(latency_ms), max(latency_ms))
+    printf("\"stdev_frames\":%0.6f, \"stdev_ms\":%0.6f", stddev(latency_frames), stddev(latency_ms))
+    fflush()
+  }
+}

case-lib/jackd_events.awk

@@ -0,0 +1,15 @@
+#!/usr/bin/gawk -f
+
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2025 Intel Corporation. All rights reserved.
+
+# Process `jackd` output to count XRun's.
+
+/JackEngine::XRun: client = jack_delay/ {
+  xrun_cnt+=1
+}
+
+END {
+  printf("\"xruns\":%d", xrun_cnt)
+  fflush()
+}

case-lib/lib.awk

@@ -0,0 +1,55 @@
+#!/usr/bin/gawk -f
+
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2025 Intel Corporation. All rights reserved.
+
+# A library of functions to re-use in AWK scripts.
+
+function min(in_array,  min_value,idx)
+{
+  min_value = "N/A"
+  if (! isarray(in_array) || length(in_array) == 0) return min_value
+  for(idx in in_array) {
+    if (min_value == "N/A" || in_array[idx] < min_value) {
+        min_value = in_array[idx]
+    }
+  }
+  return min_value
+}
+
+function max(in_array,  max_value,idx)
+{
+  max_value = "N/A"
+  if (! isarray(in_array) || length(in_array) == 0) return max_value
+  for(idx in in_array) {
+    if (max_value == "N/A" || in_array[idx] > max_value) {
+        max_value = in_array[idx]
+    }
+  }
+  return max_value
+}
+
+function sum(in_array,  sum_items,idx)
+{
+  if (! isarray(in_array) || length(in_array) == 0) return 0
+  sum_items=0
+  for(idx in in_array) {
+    sum_items += in_array[idx]
+  }
+  return sum_items
+}
+
+function stddev(in_array, sum_items,cnt_items,idx,avg,dev)
+{
+  if (! isarray(in_array) || length(in_array) == 0) return -1
+  sum_items=0
+  cnt_items=0
+  for(idx in in_array) {
+    sum_items += in_array[idx]
+    cnt_items += 1
+  }
+  avg = sum_items / cnt_items
+  dev = 0
+  for(idx in in_array) dev += (in_array[idx] - avg)^2
+  return sqrt(dev/(cnt_items - 1))
+}

case-lib/opt.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # SPDX-License-Identifier: BSD-3-Clause
-# Copyright(c) 2021 Intel Corporation. All rights reserved.
+# Copyright(c) 2021-2025 Intel Corporation. All rights reserved.
 
 # These four arrays are used to define script options, and they should
 # be indexed by a character [a-zA-Z], which is the option short name.
@@ -26,6 +26,17 @@ add_common_options()
     OPT_DESC['h']='show help information'
 }
 
+# Convert options to a json dictionary.
+options2json()
+{
+  local items_=()
+  for idx_ in "${!OPT_NAME[@]}" ; do
+    items_+=("\"${OPT_NAME[$idx_]}\":\"${OPT_VAL[$idx_]}\"")
+  done
+  # NOTE: use [*] to join array elements into a string, so IFS is applied.
+  echo "$(IFS=',' ; printf "%s" "${items_[*]}")"
+}
+
 # validate command line options, override default option value,
 # and dump help
 func_opt_parse_option()

env-check.sh

@@ -81,11 +81,18 @@ main "$@"
 
 out_str="" check_res=0
 printf "Checking for some OS packages:\t\t"
+func_check_pkg gawk
 func_check_pkg expect
 func_check_pkg aplay
 func_check_pkg sox
 func_check_pkg tinycap
 func_check_pkg tinyplay
+# JACK Audio Connection Kit
+func_check_pkg jackd
+func_check_pkg jack_iodelay
+func_check_pkg jack_lsp
+func_check_pkg jack_connect
+#
 func_check_pkg python3
 # jq is command-line json parser
 func_check_pkg jq