/*
 * Copyright 2020-2026 Yuntu Microelectronics Co., Ltd.
 * All rights reserved.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 *
 * @file dac_music.h
 * @brief Simple music player driving the ACMP internal 8-bit DAC.
 *
 * The YTM32B1MD2 has no stand-alone DAC peripheral; instead the analog
 * comparator (ACMP0) embeds an 8-bit DAC whose output can be routed to the
 * external pin PTC8 ("DAC0_OUT") through the DAC OUTEN bit. By rewriting the
 * DAC value register fast enough we synthesise audio waveforms (direct digital
 * synthesis) and play a melody on that pin.
 */

#ifndef DAC_MUSIC_H
#define DAC_MUSIC_H

#include <stdint.h>

#if defined(__cplusplus)
extern "C" {
#endif

/*******************************************************************************
 * Musical note frequencies (Hz, equal temperament, A4 = 440Hz)
 ******************************************************************************/
#define NOTE_REST 0U   /*!< Silence */
#define NOTE_C4   262U
#define NOTE_D4   294U
#define NOTE_E4   330U
#define NOTE_F4   349U
#define NOTE_G4   392U
#define NOTE_A4   440U
#define NOTE_B4   494U
#define NOTE_C5   523U
#define NOTE_D5   587U
#define NOTE_E5   659U
#define NOTE_F5   698U
#define NOTE_G5   784U

/*******************************************************************************
 * API
 ******************************************************************************/

/*!
 * @brief Initialise the DAC music player.
 *
 * Caches the core clock, starts the DWT cycle counter used for timing and makes
 * sure the ACMP DAC is enabled and routed to the DAC0_OUT pin (PTC8).
 * Call once after the board (clock/pin/ACMP) has been initialised.
 */
void DAC_MUSIC_Init(void);

/*!
 * @brief Output a single tone on the DAC.
 *
 * @param[in] freqHz     Tone frequency in Hz (use NOTE_REST/0 for silence).
 * @param[in] durationMs Tone duration in milliseconds.
 */
void DAC_MUSIC_PlayTone(uint32_t freqHz, uint32_t durationMs);

/*!
 * @brief Hold the DAC at mid-scale (silence) for the given time.
 *
 * @param[in] durationMs Rest duration in milliseconds.
 */
void DAC_MUSIC_Rest(uint32_t durationMs);

/*!
 * @brief Play the built-in demo melody ("Twinkle Twinkle Little Star") once.
 */
void DAC_MUSIC_PlayDemo(void);

#if defined(__cplusplus)
}
#endif

#endif /* DAC_MUSIC_H */

/*******************************************************************************
 * EOF
 ******************************************************************************/
