/*!
@defgroup clock_manager_YTM32B1Mx Clock Manager YTM32B1Mx
@brief Device-specific clock implementation for the YTM32B1Mx series.
@ingroup clock_manager

@details
This sub-module implements the Clock Manager for the YTM32B1Mx device family.
It configures the SCU (System Clock Unit), IPC (Inter-Peripheral Crossbar)
peripheral clock gates, and CMU (Clock Monitor Unit) using the hardware
register accessors provided by scu_hw_access.h, ipc_hw_access.h,
cmu_hw_access.h, and cfmu_hw_access.h.

@section clock_b1mx_sources Clock Sources

The YTM32B1Mx family provides the following clock sources:

| Clock Source | Typical Frequency | Description                                |
|--------------|-------------------|--------------------------------------------|
| FIRC         | 48 MHz            | Fast Internal RC oscillator (always-on capable). |
| SIRC         | 8 MHz             | Slow Internal RC oscillator (low-power fallback). |
| FXOSC        | 4 – 40 MHz        | Fast External Crystal / Clock oscillator.  |
| SXOSC        | 32.768 kHz        | Slow External Crystal (if FEATURE_SCU_SUPPORT_SXOSC). |
| PLL          | Configurable      | Phase-Locked Loop (if FEATURE_SCU_SUPPORT_PLL). Fout = Fref × Ndiv / (2 × Npre). |
| LPO          | 128 kHz           | Low Power Oscillator (if FEATURE_SCU_SUPPORT_LPO). |

@section clock_b1mx_tree Clock Distribution Tree

@verbatim
              ┌─────────┐
              │  FXOSC   │──┐
              └─────────┘  │    ┌─────────┐
              ┌─────────┐  ├───►│   PLL   │
              │  FIRC    │──┘    └────┬────┘
              └─────────┘            │
              ┌─────────┐            │
              │  SIRC    │            │
              └─────────┘            │
                   │                  │
                   ▼                  ▼
              ┌──────────────────────────────┐
              │   System Clock MUX (SCU)     │
              │  (FIRC / PLL / FXOSC / SIRC) │
              └──────────┬───────────────────┘
                         │
                    ┌────┴────┐
                    │ SYS DIV │  ÷1..÷16
                    └────┬────┘
                         │
                    Core Clock (CORE_CLK)
                         │
                    ┌────┴────┐
                    │ FB DIV  │  ÷1..÷16
                    └────┬────┘
                         │
                   Fast Bus Clock (FAST_BUS_CLK)
                         │
                    ┌────┴────┐
                    │ SB DIV  │  ÷1..÷16
                    └────┬────┘
                         │
                   Slow Bus Clock (SLOW_BUS_CLK)

              ┌─────────────────────────────────┐
              │  IPC Peripheral Clock Control   │
              │  Per-peripheral: gate + src + div│
              │  Sources: FIRC/SIRC/FXOSC/PLL/  │
              │           SXOSC/LPO/FAST_BUS    │
              └─────────────────────────────────┘
@endverbatim

@section clock_b1mx_config Configuration Structures

The top-level configuration is clock_user_config_t (alias for
clock_manager_user_config_t), which combines three sub-configurations:

| Field         | Type             | Description                                    |
|---------------|------------------|------------------------------------------------|
| ipcConfig     | ipc_config_t     | Peripheral clock gate / source / divider array.|
| scuConfigPtr  | scu_config_t*    | System clock, oscillator, PLL, divider config. |
| cmuConfigPtr  | cmu_config_t*    | CMU channel monitoring config (NULL = defaults).|

@section clock_b1mx_usage Usage Example

@subsection clock_b1mx_usage_basic Basic Initialization with FIRC

@code{.c}
/* Peripheral clocks */
const peripheral_clock_config_t periClocks[] = {
    { .clkName = IPC_SPI0_CLOCK,  .clkGate = true,
      .clkSrc = CLK_SRC_FIRC, .divider = DIV_BY_1 },
    { .clkName = IPC_UART0_CLOCK, .clkGate = true,
      .clkSrc = CLK_SRC_FIRC, .divider = DIV_BY_1 },
};

/* System clock: FIRC @ 48 MHz, no external oscillator */
const scu_config_t scuConfig = {
    .fircEnable = true,
    .sysClkSrc  = SCU_SYSTEM_CLOCK_SRC_FIRC,
    .sysDiv     = 0U,  /* /1 → Core = 48 MHz */
    .fastBusDiv = 0U,  /* /1 → Fast bus = 48 MHz */
    .slowBusDiv = 1U,  /* /2 → Slow bus = 24 MHz */
    .flashDiv   = 1U,
    .fxoscConfig    = { .enable = false },
    .clockOutConfig = { .enable = false },
};

const clock_user_config_t clockConfig = {
    .scuConfigPtr = &scuConfig,
    .cmuConfigPtr = NULL,
    .ipcConfig = { .count = 2U, .peripheralClocks = periClocks },
};

CLOCK_DRV_Init(&clockConfig);
@endcode

@subsection clock_b1mx_usage_pll Initialization with PLL (80 MHz from 8 MHz FXOSC)

@code{.c}
const scu_config_t scuConfigPll = {
    .fircEnable = true,
    .sysClkSrc  = SCU_SYSTEM_CLOCK_SRC_PLL,
    .fxoscConfig = {
        .enable        = true,
        .bypassMode    = false,
        .gainSelection = 4U,
        .frequency     = 8000000U,
    },
    .pllConfig = {
        .enable        = true,
        .pllRefClock   = SCU_PLL_REF_FXOSC_CLK,
        .pllRefClkDiv  = 1U,     /* Npre = 1 */
        .pllFeedBackDiv = 20U,   /* Ndiv = 20, Fout = 8M * 20 / (2*1) = 80 MHz */
    },
    .sysDiv     = 0U,  /* Core = 80 MHz */
    .fastBusDiv = 0U,  /* Fast bus = 80 MHz */
    .slowBusDiv = 1U,  /* Slow bus = 40 MHz */
    .flashDiv   = 2U,
    .clockOutConfig = { .enable = false },
};
@endcode

@subsection clock_b1mx_usage_switch Runtime Configuration Switching

@code{.c}
const clock_user_config_t *g_clockConfigs[] = {
    &clockConfig_RUN,       /* Index 0: 80 MHz PLL */
    &clockConfig_LOW_POWER, /* Index 1: 8 MHz SIRC */
};

CLOCK_SYS_Init(g_clockConfigs, 2U, NULL, 0U);

/* Start in RUN mode */
CLOCK_SYS_UpdateConfiguration(0U, CLOCK_MANAGER_POLICY_FORCIBLE);

/* Switch to low-power mode */
CLOCK_SYS_UpdateConfiguration(1U, CLOCK_MANAGER_POLICY_AGREEMENT);
@endcode

@section clock_b1mx_notes Notes

@warning The driver switches to SIRC as a safe intermediate clock before
reconfiguring oscillators and PLL. If SIRC switch times out,
STATUS_SCU_CLK_SWITCH_TIMEOUT is returned.

@warning When PLL lock fails, the system remains on SIRC. Check the return
value of CLOCK_DRV_Init() and handle STATUS_SCU_PLL_LOCK_TIMEOUT appropriately.

@note The CMU is enabled by default with ±25% tolerance thresholds unless
`CMU_DEFAULT_OFF` is defined. For safety-critical applications, provide
explicit cmu_config_t with validated thresholds.

@note Current implementation assumes valid clock configurations are applied
in a valid sequence. Do not reinitialize the clock that is currently used
as the system clock source without switching away first.

@section clock_b1mx_integration Integration Guide

@subsection clock_b1mx_integration_files Compilation Units
@verbatim
${SDK_PATH}/platform/drivers/src/clock/YTM32B1Mx/clock_YTM32B1Mx.c
@endverbatim

@subsection clock_b1mx_integration_include Include Paths
@verbatim
${SDK_PATH}/platform/drivers/inc/
${SDK_PATH}/platform/drivers/src/clock/
${SDK_PATH}/platform/drivers/src/clock/YTM32B1Mx/
@endverbatim

@subsection clock_b1mx_integration_symbols Compile Symbols
No special symbols are required. Device-specific feature macros
(FEATURE_SCU_*, FEATURE_IPC_*) are defined in the device features header.

@subsection clock_b1mx_integration_deps Dependencies
- @ref interrupt_manager — Required for global interrupt disable/enable
  during clock transitions.

*/
