Modul MCAL IWDG

Podporované rodiny STM32: H5
Nepodporované: G4, H7, L4, U5

Tento repozitár poskytuje ovládač MCAL (Microcontroller Abstraction Layer) pre nezávislý watchdog (IWDG) používaný v mikrokontroléroch STM32.
Ponúka jednoduché a bezpečné rozhranie na spustenie, konfiguráciu a obnovovanie watchdogu bez nutnosti riešiť prescalery, reload hodnoty alebo príznaky aktualizácie registrov.

Každá rodina STM32 je podporovaná v dedikovanej vetve tohto repozitára:

• STM32G4
• STM32U5
• STM32L4
• STM32H5
• a ďalšie podľa potreby.

---

📘 Prehľad

Ovládač IWDG MCAL abstrahuje nezávislý watchdog STM32 do rozhrania založeného na čase.
Používateľ konfiguruje watchdog v milisekundách, zvyšok urobí modul:

• Výpočet prescaleru (4 - 1024) a reload hodnoty z požadovaného timeoutu a frekvencie LSI
• Voliteľné okno (window) - obnovenie je povolené iba v poslednej časti timeoutu
• Voliteľné prerušenie early wakeup - používateľský callback sa zavolá skôr, než watchdog resetuje MCU
• Automatické obnovovanie z Iwdg_Task() alebo manuálne obnovenie cez Iwdg_Set_Refresh()
• Zistenie stavu watchdogu a dosiahnutého timeoutu

Prístup na zápis do registrov (kľúčový register), príznaky aktualizácie registrov a overenie spätným čítaním každého konfiguračného zápisu rieši modul interne.

✅ Používateľ nemusí zahŕňať ani používať žiadne ďalšie moduly, ako sú ovládače RCC alebo NVIC.
Frekvencia LSI sa číta z modulu RCC a prerušenie early wakeup sa konfiguruje interne cez modul NVIC.

⚠️ Po spustení sa watchdog nedá zastaviť (hardvérové obmedzenie). Zastaví ho iba reset systému, pokiaľ nie je v option bytes zvolený hardvérový režim watchdogu. Iwdg_Deinit() iba vypne prerušenie a automatické obnovovanie - aplikácia musí watchdog ďalej obnovovať.

---

🧩 Architektúra

Architektúra sleduje štandardné vrstvenie MCAL používané vo všetkých repozitároch STM32 MCAL:

┌────────────────────────────┐
│        Application         │
└────────────┬───────────────┘
             │
┌────────────▼───────────────┐
│           HAL              │
│(Hardware Abstraction Layer)│
└────────────┬───────────────┘
┌────────────▼───────────────┐
│       MCAL - Iwdg          │
│       ├── Iwdg_Port.h      │  
│       ├── Iwdg_Types.h     │  
│       └── Iwdg.c/.h        │  
└────────────┬───────────────┘
             │
┌────────────▼───────────────┐
│           RAL              │
│(Register Abstraction Layer)│
└────────────────────────────┘

---

🧠 Pokyny k použitiu

Používateľ má pracovať výlučne s nasledujúcimi dvoma verejnými hlavičkami:

Súbor	Účel
Iwdg_Port.h	Obsahuje všetky funkcie verejného API (inicializácia, obnovenie, zistenie stavu a timeoutu, predvolená konfigurácia)
Iwdg_Types.h	Obsahuje definície typov používané v API (konfiguračná štruktúra, typ času, typ callbacku, stavy požiadaviek)

Všetko ostatné — tabuľky prescalerov, pomocné funkcie, obslužná rutina prerušenia — je interné a nesmie sa k tomu pristupovať priamo.

Verejné API

Funkcia	Popis
Iwdg_Get_ModuleVersion()	Vráti SW verziu modulu
Iwdg_Init( config )	Vypočíta konfiguráciu, spustí a nakonfiguruje watchdog
Iwdg_Deinit()	Vypne prerušenie early wakeup a automatické obnovovanie (watchdog beží ďalej)
Iwdg_Task()	Automaticky obnovuje watchdog (iba ak sa nepoužíva okno)
Iwdg_Get_DefaultConfig( config )	Vyplní predvolenú konfiguráciu: timeout 1 s, bez okna, bez prerušenia early wakeup
Iwdg_Get_State( state )	Vráti IWDG_FUNCTION_ACTIVE, ak watchdog beží
Iwdg_Get_Timeout( timeout )	Vráti dosiahnutý timeout v ms vypočítaný z registrov
Iwdg_Set_Refresh()	Obnoví (reloaduje) čítač watchdogu

Konfigurácia

Položka	Popis
Timeout	Požadovaný timeout v ms. Pri LSI 32 kHz je rozsah približne 1 ms - 131 s.
Window	Dĺžka okna pred timeoutom v ms, v ktorom je obnovenie povolené. IWDG_TIME_UNUSED okno vypne. Musí byť kratšia ako Timeout.
EarlyWakeup	Čas pred timeoutom v ms, kedy sa spustí prerušenie early wakeup. IWDG_TIME_UNUSED prerušenie vypne. Musí byť kratší ako Timeout.
EarlyWakeupIsr	Používateľský callback prerušenia early wakeup, môže byť NULL
IrqPriority	Priorita prerušenia early wakeup (0 - najvyššia)

Neplatnú konfiguráciu (timeout mimo rozsahu, okno alebo early wakeup nie sú kratšie ako timeout) Iwdg_Init() odmietne skôr, než sa zapíše akýkoľvek register.

Poznámky

• Režim okna - obnovenie pred oknom okamžite resetuje MCU (správanie hardvéru), softvér to nemôže nahlásiť. Iwdg_Task() v režime okna watchdog neobnovuje, aplikácia musí volať Iwdg_Set_Refresh() vnútri okna.
• Hardvérový režim watchdogu - ak Iwdg_Get_State() po resete pred Iwdg_Init() vráti IWDG_FUNCTION_ACTIVE, watchdog bol spustený option bytes.
• Príčina resetu - reset od IWDG je možné po štarte zistiť pomocou Rcc_Get_ResetSource( RCC_RESET_SRC_IWDG, &flag ) a vymazať pomocou Rcc_Set_ResetSourceClear() v module RCC.
• Presnosť timeoutu - frekvencia LSI sa mení s teplotou a napätím (pozrite datasheet), skutočný timeout sa preto od vypočítaného zodpovedajúco líši.

---

⚙️ Typický príklad použitia

#include "Iwdg_Port.h"

static void App_WatchdogWarning( void )
{
    // Last chance to store diagnostic data before the watchdog reset
}

int main(void)
{
    iwdg_Config_t       iwdgConfig;
    iwdg_Time_ms_t      achievedTimeout = 0u;
    iwdg_RequestState_t iwdgState       = IWDG_REQUEST_ERROR;

    iwdgState = Iwdg_Get_DefaultConfig( &iwdgConfig );

    iwdgConfig.Timeout        = 500u;   // Reset after 500 ms without refresh
    iwdgConfig.EarlyWakeup    = 50u;    // Callback 50 ms before reset
    iwdgConfig.EarlyWakeupIsr = App_WatchdogWarning;
    iwdgConfig.IrqPriority    = 0u;

    if( IWDG_REQUEST_OK == iwdgState )
    {
        iwdgState = Iwdg_Init( &iwdgConfig );
    }

    if( IWDG_REQUEST_OK == iwdgState )
    {
        iwdgState = Iwdg_Get_Timeout( &achievedTimeout );
    }

    while (1)
    {
        // Refreshes the watchdog automatically (no window configured)
        Iwdg_Task();
    }
}

---

🧾 Stratégia vetvenia

Každá rodina STM32 má vlastnú vetvu:

Vetva	Popis
STM32G4	Ovládač MCAL pre rodinu STM32G4
STM32U5	Ovládač MCAL pre rodinu STM32U5
STM32L4	Ovládač MCAL pre rodinu STM32L4
STM32H5	Ovládač MCAL pre rodinu STM32H5

Tieto vetvy obsahujú definície registrov špecifické pre rodinu, rozsahy prescalerov a väzby RCC/NVIC a pritom zachovávajú spoločné rozhranie.

---

🧩 Závislosti

• Rcc_Lib – Frekvencia hodín LSI (RCC_PERIPH_IWDG)
• Nvic_Lib – Spracovanie prerušenia early wakeup
• RAL (Register Abstraction Layer) – Používa sa interne na prístup k nízkoúrovňovým registrom

Všetky povinné konfigurácie RCC a NVIC sa riešia interne.

---

🧱 Príklad adresárovej štruktúry

Iwdg/
├── Iwdg_Port.h
├── Iwdg_Types.h
├── Iwdg.c
├── Iwdg.h
├── CMakeLists.txt
├── LICENSE.md
└── README.md

---

🛠 Integrácia s CMake

1. Zahrňte Iwdg_Lib do svojej knižnice CMake.
2. Zahrňte Iwdg_Port.h do svojho projektu.
3. Prilinkujte implementačné súbory modulu Iwdg.
4. Nakonfigurujte modul podľa potrieb vášho hardvéru.

---

Licencia

Tento projekt je licencovaný pod licenciou Creative Commons Attribution–NonCommercial 4.0 International (CC BY-NC 4.0).

Toto dielo môžete slobodne používať, upravovať a zdieľať na nekomerčné účely, pokiaľ uvediete primeraný zdroj.

Úplné znenie podmienok nájdete v LICENSE.md alebo na creativecommons.org/licenses/by-nc/4.0.

---

Autori

• Mr.Nobody — embedbits.com

Príspevky sú vítané! Otvorte prosím pull request.

---