FULL-C: general functions

Tato stránka popisuje programovací jazyk FULL-C, který je dostupný na vybraných zařízeních SDS. 
Některá zařízení používají SDS-C, pro který máme návody jinde na této WiKi.

Nezařazené funkce FULL-C

Zde je seznam různých funkcí, které FULL-C poskytuje a které nejsou blíže popsány na specifické tématické stránce: 

         void SDS_reset_program(unsigned int key);
         void SDS_set_wdg(unsigned int newTimeOut);
         void SDS_kick_wdg(unsigned int key);

         void SDS_heap_stats(unsigned int *currentAllocatedBytes, 
unsigned int *totalFreeBytes, unsigned int *biggestFreeBlockAvailable);


Účel

Vždy se má předpokládat, že v programu, který chcete spustit a provozovat, je nějaká (skrytá) chyba. I když je program napsán "dokonalým" způsobem, nikdy nemůžete mít jistotu, že tomu tak skutečně je. Toto je základní princip tzv. SAFETY vývoje, kdy automaticky VŽDY očekáváme že v programu může být chyba (respektive víme, že nejsme dokonalí, a dokonalosti se můžeme vždy jen přiblížit, ale z principu ji nelze dosáhnout). Dále je potřeba očekávat i vnější vlivy, kdy dojde k ovlivnění nebo dokonce snad i změně programu, neočekávaným a nechtěným vnějším vlivem. Ať je to uživatelům zásah, měřená fyzikální veličina mimo očekávaný rozsah, útok hackera a nebo snad kosmická částice která změní bit v paměti - úplný seznam nelze nikdy vytvořit.

Toto vše však má řadu řešení, které byly dlouho zkoumány a připravovány. Jako vhodný základ je vývoj programů podle safety normy 61508, tedy minimálně si z ní vzít ty kritické požadavky.

SDS nabízí funkci speciálního hlídače vašeho FC programu - tedy FC WATCHDOG. Tato funkce se musí aktivovat ve vašem FC programu, a následně se musí FC program periodicky hlásit, že stále správně funguje. Pokud se nepřihlásí v nastaveném čase, dojde ze strany SDS k zastavení a novému spuštění programu. Toto vše může váš FC program sledovat přes vybrané systémové indexy, a také konfigurovat přes určené FC funkce.

Samozřejmě FC-Watchdog je jen jedním z mnoha prvků, které je potřeba využít, aby váš systém byl celkově odolný a vydržel chybu-vzdorně pracovat.

Další prvky jsou:

  • úvodní analýza programu a způsob psaní kódu programu
  • detailně sepsané požadavky na všech úrovních, a jejich provázání na kód a test
  • sledování využití paměti
  • úvodní diagnostika
  • průběžná diagnostika
  • telemetrie (logování, informace předávané uživateli, historie, záchyt chybových stavů tak aby šla chyba plně identifikovat)
  • statická a dynamická analýza kódu programu
  • SiL a HiL testování
  • Unit Testy
  • schopnost programu pracovat v režimu snížené kapacity systému (např. při poškozené části systému)
  • odolnost programu a jeho vnitřních prvků a funkcí (především proti integer a buffer overflow)
  • zabezpečená komunikační rozhraní (safety a security)
  • zabezpečená datová úložiště (safety a security)

Většina těchto prvků je "na vás", tedy SDS poskytuje prostor a možnosti k jejich realizaci.


SDS_reset_program(): okamžité nové spuštění FC programu

Zavoláním této funkce, se správně vyplněným parametrem key, dojde k okamžitému znovu-spuštění aktuálního FULL-C programu. Tedy prakticky totéž, jako by došlo k resetu zařízení (ale to se nestane, SDS pokračuje v práci a nic se s ním při zavolání této funkce nestane; dojde pouze a jenom k ukončení a okamžitému novému spuštění nahraného FC programu).

Podmínkou je předání hodnoty key jako čísla 1. 

 // 
 SDS_reset_program(1);  // reset programu se provede jen a pouze, pokud je parametr == 1
 
 // nebo takto:
 
 unsigned int k;
 k = 1234;
 SDS_reset_program(k); // protoze "k" neni 1, program bude pokracovat (nestane se restart programu)
 
 k = 1;
 SDS_reset_program(k); // a ted uz se program spusti odznova, protoze klic je 1


SDS_set_wdg(): spuštění dohledu správněhu běhu FC programu

Funkce nastaví a okamžitě spustí Watchdog pro FULL-C program - cílem je hlídat "nezaseknutí" vašeho FULL-C programu.

Stanovíte si, jak často se váš FULL-C program musí "hlásit" že je v pořádku (nezaseknutý), a pokud se váš program do té doby neohlásí (např. zůstane "zaseknutý" v nějaké smyčce), tak SDS okamžitě provede jeho ukončení a následně spustí FC program znovu.

Tato funkce tedy spustí odpočet, a pokud se tento dopočítá (z vámi nastavenou hodnotu) na nulu, dojde k popsanému restartu FC programu.

Parametr newTimeOut nastavuje cílovou hodnotu odpočtu, a je uveden v sekundách. Příklad: SDS_set_wdg(10) spustí hlídání FC programu a pokud do 10 sekund není zavolána funkce SDS_kick_wdg, tak dojde k znovu-spuštění FC programu.

Jakmile je jednou hlídač spuštěn, nelze jej deaktivovat - to se stane pouze při fyzickém restartu zařízení SDS, při nahrání nového FC programu, nebo při jeho novém spuštění. Při každém spuštění FC programu (nezávisle na důvodu, jestli to bylo nahráním nového programu, nebo jeho restartem), tak je hlídač vypnut - a FC program jej musí nastavit a spustit zavoláním funkce SDS_set_wdg().

FC program si může zjistit, že jeho aktuální spuštění bylo vyvoláno právě z tohoto důvodu (zaseknutí) a podle toho se "zařídit" (např. poslat zprávu, přejít do nouzového režimu, atd. podle toho jak si to sami vymyslíte pro svou aplikaci).


SDS_kick_wdg(): průběžná aktualizace dohledu běhu FC programu

Funkce se volá opakovaně a musí se vždy stihnout zavolat (od svého posledního zavolání) v rámci nastaveného intervalu (viz funkce SDS_set_wdg).

Zavolání SDS_kick_wdg dojde k nastavení odpočtu hlídače běhu FC programu, a odpočet tedy začne znovu klesat (může klesat až do nuly, kdy dojde k restartu programu - není-li odpočet včas znovu nastaven nahoru).

Pokud tedy včas nezavoláte tuto funkci, dojde k restartování FC programu. Toto je záměr, kdy se vám např. program zasekne, tak s tím je potřeba něco udělat - a tento hlídač se o to postará.

Je na vás, správně rozmístit volání SDS_kick_wdg do vašeho FC programu - není to jednoduché, a může se stát, že přehlédnete místo, kam to ještě bylo potřeba vložit. Důsledné testování vašeho FC programu je tedy na místě !

Parametr key při volání SDS_kick_wdg() musí mít přesně stejnou číselnou hodnotu, jakou jste předali v parametru newTimeOut při prvním volání funkce SDS_set_wdg(). Pokud zavoláte funkci SDS_kick_wdg() s jinou hodnotou, je to jako by jste tuto funkci nezavolali - a hlídací odpočet dále pokračuje k nule.

Příklad obsluhy FC-watchdogu

void main(void)
{
  // start programu
  SDS_set_wdg(16);   // nastav watchdog na 16 sekund
 
  // . . .
 
  for (;;)
  {

    // . . .

    if (vse_je_ok)
    {
      SDS_kick_wdg(16); // znovunastavení hlídače, od teď máme zase až 16 sekund . . .
    }

    // . . .

  }

SDS_heap_stats(): zjištění stavu dynamické paměti

Celý FULL-C program, včetně všech proměnných, je umístěn v jednom 64kB nebo 128kB nebo 512kB bloku paměti RAM (viz stránka s popisem detailu využití paměti RAM v SDS). Všechna paměť, kterou program z těchto celkových kB RAM nevyužije, je k dispozici programu pomocí funkce malloc().

Některé další funkce (zejména funkce pro práci se sítí, jako je například snmp_send_trap() ), vyžadují chvilkově část této volné paměti pro svou činnost. Pokud tato paměť není k dispozici (buď je do zařízení nahrán tak velký program, že ji vyčerpá už při svém úvodním spuštění) (nebo program použil malloc() natolik, že volný heap vyčerpal), tak se tyto FULL-C funkce nepovede provést (bude vrácen příslušný chybový kód = nedostatek paměti).

Pro aktuální zjištění situace (tj. kolik je volné paměti a jaký největší blok paměti (v kuse) lze alokovat), je zde k dispozici funkce SDS_heap_stats().


SDS_heap_stats(): příklad

Příklad vypíše stav paměti heap, potom alokuje 2kB paměti, a potom znovu vypíše stav, potom alokovanou paměť uvolní a naposledy vypíše stav. Sledujte text který tento program napíše do konzole. 

void main(void)
{
 unsigned int currentAllocatedBytes, totalFreeBytes, biggestFreeBlockAvailable;
 void * ptr;

 printf("START\n");

 SDS_heap_stats(&currentAllocatedBytes, &totalFreeBytes, &biggestFreeBlockAvailable);
 printf("currentAllocatedBytes: %uB, totalFreeBytes: %uB, biggestFreeBlockAvailable:%uB \n\n",
        currentAllocatedBytes, totalFreeBytes, biggestFreeBlockAvailable);

 printf("ALLOC 2048 BYTES\n");
 ptr = malloc(2048);

 SDS_heap_stats(&currentAllocatedBytes, &totalFreeBytes, &biggestFreeBlockAvailable);
 printf("currentAllocatedBytes: %uB, totalFreeBytes: %uB, biggestFreeBlockAvailable:%uB \n\n",
        currentAllocatedBytes, totalFreeBytes, biggestFreeBlockAvailable);

 printf("FREE PTR\n");
 free(ptr); ptr = 0;

 SDS_heap_stats(&currentAllocatedBytes, &totalFreeBytes, &biggestFreeBlockAvailable);
 printf("currentAllocatedBytes: %uB, totalFreeBytes: %uB, biggestFreeBlockAvailable:%uB \n\n",
        currentAllocatedBytes, totalFreeBytes, biggestFreeBlockAvailable);

}


Důležité systémové indexy

  • 40: SoC power-up or reset reason (64/128 = read only LSB: 8 bits) (512 = read all 32 bits)

Využijte pro analýzu jakým způsobem bylo SDS zapnuto - jestli se jedná o normální zapnutí (Power On Reset) nebo o (re)start firmware z důvodu nečekané chyby (např. watchdog)

  • 86: FC: actual state (running, uploading, failed etc.) of the FULL-C program (0, 1, 2, 4, 8, 16, 32, 64)

Využijte pro vzdálené sledování stavu programu (je-li spuštěn a běží, nebo je-li pozastaven či vůbec neběží).

  • 87: FC: unique identifier of the actually uploaded FULL-C program

Každý FC program má svůj odpovídající unikátní 32bit identifikátor, pomocí kterého lze jednotlivé programy od sebe rozpoznat. Tento identifikátor je hashem celého programového kódu, a tím je zaručena jeho vysoká unikátnost (která nebude dokonalá, ale pro tento primární účel, vhodná a použitelná je).

  • 132: FC: UTC time value, of the last FC-WDG restart of this (same) program (zeroed when a new program is uploaded)

Informace - časová známka UTC, kdy došlo k poslednímu restartu tohoto FC programu, z důvodu aktivace FC-Watchdogu. Pokud k restartu nedošlo, je zde nula. Pokud UTC čas nebyl v době restartu k dispozici, je zde neplatný údaj. Tento údaj je vždy vynulován, pokud dojde k nahrání jiného programu do SDS.

  • 133: FC: UpTime value, of the last FC-WDG restart of this (same) program (zeroed when a new program is uploaded)

Informace - hodnota UpTime, kdy došlo k poslednímu restartu tohoto FC programu, z důvodu aktivace FC-Watchdogu. Pokud k restartu nedošlo, je zde nula. Tento údaj je vždy vynulován, pokud dojde k nahrání jiného programu do SDS.

  • 134: FC: archived text of the last FC error

Došlo-li k chybě, která způsobila pád nebo restart vašeho FC programu, je tato chyba archivována a je k dispozici zde - můžete ji tak sami zobrazit ve svém programu, nebo poslat dále v rámci logování. Tento údaj je nulován (prázdný text) jakmile je nahrán nový program do SDS.

  • 135: FC: number of FC-WDF restarts of this (same) program (zeroed when a new program is uploaded)

Každý FC-Watchdog restart, pro aktuální nahraný FC program, způsobí zvýšení tohoto počítadla. Jakmile je nahrán nový FC program do SDS, je počítadlo vynulováno.

  • 136: FC: total count of all FC program starts, since the SDS boot

Počítadlo úplně všech spuštění (libovolných) FC programů, od zapnutí SDS (respektive tedy: od posledního bootu SDS). Počítadlo se nuluje jen restartem SDS.

  • 137: read an actual SDS CPU cycle counter (number of executed instructions since power-up/reboot), continuously wraps around, (1 step = approx. 2 nsec)

Vysokorychlostní automatický čítač, svázaný s vykonáváním CPU instrukcí v hlavním SoC chipu. Vhodné pro sledování rychlosti programu, pro logování atd.

  • 183: SDS FW date stamp (or just 0x00000000 for a very old firmware)

Důležitý údaj, určuje datum nainstalované verze firmware v SDS. Díky tomuto údaji máte informaci o možnostech, které dané SDS s daným firmware poskytuje, a které ne (pokud je tam nainstalován starý firmware). Váš program může tento údaj zkontrolovat, a pokud zjistí že je v SDS nainstalován starý firmware (se kterým váš FC program není kompatibilní, nebo mu tam chybí nějaká funkce která je až v novější verzi firmware), může se tomu přizpůsobit, a nebo informovat uživatele a vynutit si aktualizace firmware v SDS.

  • 184: FC: information about how this actual running program was started (0 = none) (1 = normal) (2 = fc-wdg or manual restart) (4 = freshly loaded)

Informace, jakým způsobem byl aktuální běžící FC program spuštěn.

  • 185: FC: actual FULL-C WatchDog (decreasing) timeout counter value, v msec

Zde lze kontrolovat aktuální stav odpočtu čítače FC-Watchdogu. Pokud se počítadlo dostane na nulu, tedy nedojde-li včas k refreshi počítadla vhodným zavoláním funkce, je FC-Watchdog aktivován a dojde k restartu FC programu.

Citováno z „https://wiki.merenienergie.cz/subdom/wiki/index.php?title=FULL-C:_general_functions&oldid=794“