qqnxsndhelpers_p.h

// Copyright (C) 2025 The Qt Company Ltd.

// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only

#ifndef QQNXSNDHELPERS_P_H

#define QQNXSNDHELPERS_P_H

//

//  W A R N I N G

//  -------------

//

// This file is not part of the Qt API.  It exists for the convenience

// of other Qt classes.  This header file may change from version to

// version without notice, or even be removed.

//

// We mean it.

//

#include <alsa/asoundlib.h>

#include <QtCore/qbytearray.h>

#include <QtCore/qloggingcategory.h>

#include <QtMultimedia/qaudioformat.h>

#include <QtMultimedia/private/qaudiohelpers_p.h>

#include <chrono>

#include <cstddef>

#include <cstdint>

#include <memory>

#include <optional>

QT_BEGIN_NAMESPACE

namespace QnxSndHelpers {

// snd_pcm_resume retries before falling back to snd_pcm_prepare.

inline constexpr int kSuspendResumeRetryLimit = 5;

// Per-retry delay during suspend/resume recovery (ALSA cookbook idiom).

inline constexpr std::chrono::milliseconds kSuspendResumeRetryDelay{ 100 };

// Number of periods (chunks) per ALSA buffer: buffer = period * chunks. 2 is

// double-buffering, 3 gives a little more slack; overridable via env var.

inline constexpr unsigned kDefaultPeriodCount = 3;

// Acceptable env-var override range for the period count.

inline constexpr unsigned kMinPeriodCount = 2;

inline constexpr unsigned kMaxPeriodCount = 16;

// Default ALSA period size in frames, used unless the caller passes a

// NativePeriodFrames override. ~21 ms at 48 kHz.

inline constexpr snd_pcm_uframes_t kDefaultPeriodFrames = 1024;

// Worker-thread real-time priority band. io-snd runs its own data/helper threads

// at SCHED_RR 24/25 (mixer/irq higher); we stay strictly below 24 so we never

// preempt them (raising into that band REPLY-block-wedges the driver), but above

// the default application priority (10) so a busy app thread cannot preempt the

// audio worker. Overridable within the band via QT_QNXSND_WORKER_PRIO.

inline constexpr int kMinWorkerPriority = 11;

inline constexpr int kMaxWorkerPriority = 23;

inline constexpr int kDefaultWorkerPriority = 20;

// Self-pipe to wake a worker blocked in poll() on a PCM fd: the worker adds

// readFd() to its poll set; another thread calls wake() to return the poll().

// RAII closes both fds. wake()/drain() are const (they touch the pipe, not the

// object's own state).

class WakePipe

public:

    WakePipe() = default;

    ~WakePipe();

    Q_DISABLE_COPY_MOVE(WakePipe)

    bool open();              // create a non-blocking pipe; false on failure

    void close() noexcept;

    void wake() const noexcept;   // write one byte (no-op if a wake is pending)

    void drain() const noexcept;  // discard all pending wake bytes

    void waitForWake() const noexcept; // block until wake() fires, then drain

    int readFd() const noexcept { return m_fds[0]; }

    bool isOpen() const noexcept { return m_fds[0] >= 0; }

private:

    int m_fds[2] = { -1, -1 };

};

// Block until the PCM handle is ready for I/O (POLLOUT for playback / POLLIN for

// capture, as set by snd_pcm_poll_descriptors) or the wake pipe is signalled:

//   Ready - the PCM reported its I/O revent; the caller may write/read a period

//   Woken - the wake pipe fired (re-check stop/suspend); the pipe is drained

//   Error - poll() failed or the PCM reported POLLERR/POLLHUP/POLLNVAL

enum class PollOutcome { Ready, Woken, Error };

PollOutcome pollPcm(snd_pcm_t *handle, const WakePipe &wake);

// RAII guard for the void** array returned by snd_device_name_hint.

struct HintsDeleter

    void operator()(void **h) const noexcept

        if (h)

            snd_device_name_free_hint(h);

};

using HintsGuard = std::unique_ptr<void *, HintsDeleter>;

// Map a QAudioFormat::SampleFormat to the corresponding ALSA PCM format.

// Returns SND_PCM_FORMAT_UNKNOWN for Unknown / NSampleFormats / unhandled.

snd_pcm_format_t mapSampleFormat(QAudioFormat::SampleFormat) noexcept;

// Recover from xrun / suspend states; returns the resulting errno.

int recoverFromXrun(snd_pcm_t *handle, int err);

// Start a prepared PCM. No-op (returns 0) if it already left PREPARED, so a

// caller can prefill-then-start without racing the device's auto-start.

// Returns the snd_pcm_start errno otherwise.

int startPcm(snd_pcm_t *handle);

// Raise the *calling* (worker) thread to SCHED_FIFO at a priority in the

// [kMinWorkerPriority, kMaxWorkerPriority] band, overridable via the

// QT_QNXSND_WORKER_PRIO environment variable. On failure, logs via the supplied

// category and leaves the thread's inherited scheduling unchanged.

void setWorkerRealtimePriority(const QLoggingCategory &category);

// Inputs for openConfiguredPcm: everything that differs between the

// playback and capture paths.

struct PcmOpenConfig

    snd_pcm_stream_t direction;            // SND_PCM_STREAM_PLAYBACK / _CAPTURE

    QByteArray deviceId;

    QAudioFormat format;

    const QLoggingCategory &category;

    const char *streamLabel;               // "Playback" or "Capture", embedded in log strings

    const char *periodCountEnvVar;         // e.g. "QT_QNXSND_OUTPUT_PERIODS"; chunk-count override

    std::optional<uint32_t> periodFrames;  // NativePeriodFrames override; nullopt -> kDefaultPeriodFrames

};

// Outputs from openConfiguredPcm. handle is null on failure (use operator bool).

struct PcmOpenResult

    snd_pcm_t *handle = nullptr;

    snd_pcm_uframes_t periodFrames = 0;

    snd_pcm_uframes_t bufferFrames = 0;

    qsizetype periodBytes = 0;

    // The device's chosen native sample format (may be a 24-bit format that

    // QAudioFormat cannot express). The stream converts between this and the

    // application format via the base-class process()/runAudioCallback helpers.

    QAudioHelperInternal::NativeSampleFormat nativeFormat =

            QAudioHelperInternal::NativeSampleFormat::int16_t;

    explicit operator bool() const noexcept { return handle != nullptr; }

};

// Open a PCM device, configure hw/sw params and prepare it. The stream is left

// PREPARED but NOT started — the worker thread starts it (see startPcm), after

// prefilling the first period on the playback side. Returns a populated

// PcmOpenResult on success; on failure the handle is closed internally and the

// result evaluates to false.

PcmOpenResult openConfiguredPcm(const PcmOpenConfig &config);

} // namespace QnxSndHelpers

QT_END_NAMESPACE

#endif // QQNXSNDHELPERS_P_H