NVRAM Manager (NvM)

Gebruik en aanroepcontext

De functie NvM_Init dient voor het synchroon resetten van alle interne variabelen van de NVRAM Manager [SWS_NvM_00447]. Deze verwacht als overdrachtsparameter ConfigPtr een pointer naar de geselecteerde configuratiedataset en heeft geen retourwaarde [SWS_NvM_00447]. Als API van type 4 maakt deze deel uit van de configuratieklassen 2 en 3 [SWS_NvM_00560], [SWS_NvM_00561]. De functie is niet-re-entrant en mag uitsluitend worden aangeroepen door de BSW Mode Manager [SWS_NvM_00447], [SWS_NvM_00693].

Initialisatietaken

Tijdens de aanroep voert de functie de volgende acties uit:

• Het resetten van alle interne variabelen, waaronder toestandsmachines, opdrachtwachtrijen en request-flags, naar hun initiële waarden [SWS_NvM_00399].
• Het op nul instellen van de datasetindex van alle NVRAM-blokken van het type NVM_BLOCK_DATASET [SWS_NvM_00192].
• Het intern instellen van het signaal „INIT DONE”, dat de voorwaarde vormt voor de opdrachtverwerking, het wachtrijbeheer en de CRC-herberekening in de module [SWS_NvM_00257], [SWS_NvM_00399].

Beperkingen en interactie

Wegens strikte eisen aan de starttijd van het regeleenheid initialiseert NvM_Init geen geconfigureerde NVRAM-blokken [SWS_NvM_00091]. Permanente RAM-blokinhoud wordt niet gewijzigd en synchronisatie-callbacks worden niet aangeroepen; dit is voorbehouden aan de functie NvM_ReadAll [SWS_NvM_00400]. Bovendien initialiseert NvM_Init noch onderliggende stuurprogramma's noch de geheugen-hardware-abstractie of externe modules, aangezien de initialisatie daarvan door de BSW Mode Manager wordt verondersteld [SWS_NvM_00157], [SWS_NvM_00193].

Gebruik en semantiek

De synchrone en re-entrante functie NvM_SetBlockProtection dient voor het instellen of opheffen van de schrijfbeveiliging voor een NVRAM-blok via het overeenkomstige attribuut in het administratieve blok [SWS_NvM_00450], [SWS_NvM_00016]. Deze is toegewezen aan API-configuratieklasse 3 [SWS_NvM_00560]. De omgeving van de NvM-module kan de schrijfbeveiliging via de parameter ProtectionEnabled gericht activeren of deactiveren [SWS_NvM_00578]. De functie retourneert bij succesvolle uitvoering E_OK en bij een fout E_NOT_OK [SWS_NvM_00450].

Beperkingen en concurrency

Het wijzigen van de schrijfbeveiliging is alleen toegestaan voor blokken waarbij NvMWriteBlockOnce is geconfigureerd op FALSE, ongeacht de waarde van de parameter NvMBlockWriteProt [SWS_NvM_00325]. Als NvMWriteBlockOnce is geconfigureerd op TRUE, mag de schrijfbeveiliging noch worden geactiveerd noch worden gedeactiveerd [SWS_NvM_00398], [SWS_NvM_00577]; deze beveiliging kan ook na leesbewerkingen niet worden opgeheven [SWS_NvM_00314], [SWS_NvM_00316], [SWS_NvM_00784]. Bovendien kan een via NvM_SetBlockLockStatus ingestelde blokkeringstoestand niet worden gewijzigd door NvM_SetBlockProtection [SWS_NvM_00754]. Zolang een individuele blokopdracht voor hetzelfde blok actief of in de wachtrij geplaatst is, is de aanroep niet toegestaan [SWS_NvM_00704].

Foutafhandeling

Bij geactiveerde ontwikkelingsdetectie (DET) meldt de functie specifieke fouttoestanden:

• NVM_E_UNINIT, wanneer de NvM-module nog niet is geïnitialiseerd [SWS_NvM_00606].
• NVM_E_PARAM_BLOCK_ID, wanneer de meegegeven BlockId buiten het geldige bereik ligt [SWS_NvM_00609].
• NVM_E_BLOCK_PENDING, indien voor het blok al een bewerking actief of in de wachtrij geplaatst is [SWS_NvM_00607].
• NVM_E_BLOCK_CONFIG, wanneer het blok is geconfigureerd met NvMWriteBlockOnce = TRUE [SWS_NvM_00608].
• NVM_E_BLOCK_LOCKED, wanneer het blok is geblokkeerd [SWS_NvM_00759].

De synchrone en re-entrante functie NvM_SetRamBlockStatus dient voor het instellen van de RAM-blokstatus voor permanente RAM-blokken of voor blokken met expliciete synchronisatie [SWS_NvM_00453]. Deze is beschikbaar in de API-configuratieklassen 2 en 3 [SWS_NvM_00561], [SWS_NvM_00560], mits deze is geactiveerd via de configuratieparameter NvMSetRamBlockStatusApi [SWS_NvM_00408].

Via de parameter BlockChanged wordt geregeld of het blok als geldig en gewijzigd (TRUE) of als ongeldig en ongewijzigd (FALSE) wordt gemarkeerd [SWS_NvM_00453], [SWS_NvM_00406]. Bij overdracht van TRUE gaat de module uit van de geldigheid van de gegevens [SWS_NvM_00241]. De functie retourneert E_OK bij een succesvolle statuswijziging en E_NOT_OK in geval van een fout [SWS_NvM_00453].

Als BlockChanged op TRUE wordt ingesteld, vraagt de functie op de achtergrond een herberekening van de controlesom in NvM_MainFunction aan, indien NvMCalcRamBlockCrc is geconfigureerd [SWS_NvM_00121]. Bij blokken zonder permanent RAM met expliciete synchronisatie gebruikt deze job de schrijf-callback voor gegevensverwerving [SWS_NvM_00906]. Mislukt deze, dan vinden geconfigureerde herhalingen per aanroep van NvM_MainFunction plaats [SWS_NvM_00907], [SWS_NvM_00908]. Als alle pogingen zonder succes blijven, geldt de job desondanks als beëindigd en blijft het blok als gewijzigd gemarkeerd [SWS_NvM_00909].

Vóór de aanroep moet de NvM-module zijn geïnitialiseerd [SWS_NvM_00711]. Bij actieve detectie van ontwikkelingsfouten meldt de functie NVM_E_UNINIT bij een niet-geïnitialiseerde module [SWS_NvM_00643], NVM_E_PARAM_BLOCK_ID bij een ongeldige BlockId [SWS_NvM_00645] en NVM_E_BLOCK_PENDING bij reeds lopende of in de wachtrij geplaatste opdrachten [SWS_NvM_00644]. Zolang een individuele blokopdracht actief is, mag de functie voor dit blok niet worden aangeroepen [SWS_NvM_00704]. Een via NvM_SetBlockLockStatus ingestelde blokvergrendeling kan hierdoor niet worden gewijzigd [SWS_NvM_00754].

Gebruik en aanroepcontext

De synchrone en re-entrante functie NvM_SetBlockLockStatus dient voor het vergrendelen (BlockLocked = TRUE) of ontgrendelen (BlockLocked = FALSE) van een permanent geconfigureerd RAM-blok of de expliciete synchronisatie van een NVRAM-blok [SWS_NvM_00548]. Deze behoort tot de functionele omvang van de API-configuratieklassen 2 en 3 [SWS_NvM_00561], [SWS_NvM_00560]. De functie is niet opgenomen in de ServicePort-interface en wordt primair aangeroepen door het DCM en door complexe apparaatdrivers (CDD) [SWS_NvM_00732].

Beperkingen en interactie

De aanroep heeft uitsluitend effect op NVRAM-blokken met een permanent RAM-blok of geconfigureerde expliciete synchronisatie; bij alle andere blokken blijft deze zonder effect [SWS_NvM_00732]. Wordt een blok vergrendeld (BlockLocked = TRUE), dan waarborgt de NvM dat de bijbehorende NV-gegevens niet worden gewijzigd: het blok wordt bij NvM_WriteAll overgeslagen, en de services NvM_WriteBlock, NvM_WritePRAMBlock, NvM_InvalidateNvBlock en NvM_EraseNvBlock worden afgewezen [SWS_NvM_00751]. Bij de volgende opstart laadt de NvM het blok bij NvM_ReadBlock of NvM_ReadPRAMBlock gegarandeerd uit het NV-geheugen [SWS_NvM_00752]. De ingestelde vergrendelingstoestand kan noch via NvM_SetRamBlockStatus noch via NvM_SetBlockProtection worden gewijzigd [SWS_NvM_00754]. De overdracht van BlockLocked = FALSE herstelt de reguliere verwerking [SWS_NvM_00753].

Foutafhandeling

Bij geactiveerde ontwikkelingsdetectie (DET) meldt de functie specifieke ontwikkelingsfouten:

• NVM_E_UNINIT, indien de NvM-module op het moment van aanroepen nog niet is geïnitialiseerd [SWS_NvM_00728].
• NVM_E_PARAM_BLOCK_ID, wanneer de parameter BlockId buiten het toegestane bereik ligt [SWS_NvM_00731].
• NVM_E_BLOCK_CONFIG, voor zover het gereferentieerde NVRAM-blok is geconfigureerd met de parameter NvMWriteBlockOnce = TRUE [SWS_NvM_00730].

Gebruik en semantiek

De via NvM.h beschikbare functie NvM_CancelJobs dient ertoe om alle in de wachtrij staande opdrachten voor een bepaald NVRAM-blok synchroon af te breken [SWS_NvM_00535], [SWS_NvM_00536]. De functie is re-entrant ontworpen en verwacht als parameter de BlockId, die de blokdescriptor van het betreffende NVRAM-blok eenduidig identificeert [SWS_NvM_00535]. De aanroep levert E_OK op wanneer openstaande opdrachten succesvol uit de wachtrij konden worden verwijderd, en E_NOT_OK indien er voor het opgegeven blok geen opdracht in de wachtrij vindbaar was [SWS_NvM_00535].

Verloop en gelijktijdigheid

Een opdracht die op het moment van de functieaanroep al actief wordt afgehandeld, wordt door NvM_CancelJobs niet onderbroken, maar loopt door tot het einde [SWS_NvM_00537]. Voor zover het afbreekverzoek voor wachtende opdrachten wordt geaccepteerd, stelt de service het blokspecifieke verzoekresultaat vooraf in op NVM_REQ_CANCELED [SWS_NvM_00225], [SWS_NvM_00536]. Het doel van deze opschoning is om de wachtrij bijvoorbeeld bij beëindiging of herstart van een partitie te legen en zo latere notificaties over voltooide taken te voorkomen [SWS_NvM_00225].

Foutafhandeling en configuratie

Bij geactiveerde ontwikkelingsdetectie (DET) controleert de functie de voorwaarden: is de module nog niet geïnitialiseerd, dan wordt de fout NVM_E_UNINIT gemeld [SWS_NvM_00648]. Ligt de meegegeven BlockId buiten het geldige bereik, dan volgt de DET-melding NVM_E_PARAM_BLOCK_ID [SWS_NvM_00649]. NvM_CancelJobs is geclassificeerd als type-2-API en is beschikbaar in de API-configuratieklassen 2 en 3 [SWS_NvM_00561], [SWS_NvM_00560].

Gebruik en semantiek

De functie NvM_ReadBlock dient voor het asynchroon kopiëren van gebruikersgegevens uit het NV-geheugen naar het bijbehorende RAM-blok [SWS_NvM_00010], [SWS_NvM_00454]. De aanroep is re-entrant [SWS_NvM_00454]. Deze neemt de parameters over, plaatst de leesopdracht in de interne taakwachtrij en retourneert onmiddellijk E_OK bij succesvolle acceptatie resp. E_NOT_OK bij afwijzing [SWS_NvM_00195], [SWS_NvM_00454].

Als een pointer NvM_DstPtr wordt meegegeven, kunnen gegevens in afwijking van de blokconfiguratie naar een tijdelijke RAM-buffer worden gelezen; een ontoelaatbare NULL-pointer leidt in dit scenario tot een DET-fout [SWS_NvM_00196], [SWS_NvM_00278]. Een geconfigureerd permanent RAM-blok wordt direct bij het in de wachtrij plaatsen of bij de start van de taakverwerking als ongeldig gemarkeerd [SWS_NvM_00198]. Pas na een succesvolle kopieerbewerking geldt het RAM-blok als geldig en ongewijzigd [SWS_NvM_00200], en verandert het taakresultaat naar NVM_REQ_OK [SWS_NvM_00206].

Foutafhandeling en gegevensintegriteit

Is voor het blok een controlesom ingeschakeld (NvMCalRamBlockCrC == TRUE), dan verzoekt de taak na het kopiëren om een herberekening [SWS_NvM_00201]:

• Bij CRC-fouten wordt NVM_E_INTEGRITY_FAILED gemeld aan het DEM [SWS_NvM_00203]. Voor zover aanwezig worden standaardwaarden geladen en wordt het resultaat op NVM_REQ_RESTORED_DEFAULTS gezet [SWS_NvM_00202]. Ontbreken ROM-gegevens en initialisatie-callbacks, dan resulteert dit in NVM_REQ_INTEGRITY_FAILED [SWS_NvM_00204].
• Meldt de geheugendriver MEMIF_JOB_FAILED en zijn er geen vervangende waarden beschikbaar, dan eindigt de taak met NVM_REQ_NOT_OK [SWS_NvM_00359].

Bijzonderheden van de bloktypen

• Redundant: Mislukt het lezen van de eerste kopie, dan wordt automatisch de tweede NV-kopie gebruikt [SWS_NvM_00199]. Zijn beide kopieën ongeldig, dan wordt het gehele blok geïnvalideerd [SWS_NvM_00317].
• Dataset: Is het via de dataset-index geselecteerde blok als ongeldig gemarkeerd, dan blijft het kopiëren naar het RAM achterwege [SWS_NvM_00355].
• Write-Once: Consistent gelezen blokken met ingesteld NVM_WRITE_BLOCK_ONCE worden permanent tegen schrijven beveiligd [SWS_NvM_00316].

De functie NvM_WriteBlock dient voor het kopiëren van gegevens van een RAM-blok naar het toegewezen NV-blok [SWS_NvM_00455], [SWS_NvM_00410]. De aanroep wordt re-entrant en asynchroon uitgevoerd: de functie neemt de overgedragen parameters BlockId en NvM_SrcPtr over, plaatst de schrijfopdracht in de interne jobwachtrij en keert onmiddellijk terug [SWS_NvM_00208]. De retourwaarde geeft met E_OK de succesvolle acceptatie of met E_NOT_OK de afwijzing van de opdracht aan [SWS_NvM_00455].

Met betrekking tot parametrering en gegevensbron gelden de volgende voorschriften:

• Als een geldig RAM-adres wordt overgedragen via NvM_SrcPtr, gebruikt de schrijfopdracht deze buffer [SWS_NvM_00210]. Dit maakt ook het opslaan van tijdelijke RAM-blokken mogelijk bij eigenlijk permanent geconfigureerde blokken of expliciete synchronisatie [SWS_NvM_00280].
• Een geconfigureerd permanent RAM-blok wordt als geldig verondersteld of voorafgaand aan het kopieerproces automatisch gevalideerd [SWS_NvM_00303].
• Als voor het NV-blok een controlesom is geconfigureerd, vraagt de job vóór het schrijfproces een CRC-herberekening aan [SWS_NvM_00212].
• Bij datasetblokken (NVM_BLOCK_DATASET) wordt het doel geselecteerd via de gegevensindex die in het administratieve blok is opgeslagen [SWS_NvM_00338].
• Bij redundante blokken (NVM_BLOCK_REDUNDANT) wordt de job afgesloten met NVM_REQ_OK zodra ten minste één kopie succesvol is geschreven [SWS_NvM_00284].
• Als NvMWriteBlockOnce == TRUE is ingesteld, activeert de job na succesvol schrijven onmiddellijk de schrijfbeveiliging in het administratieve blok [SWS_NvM_00328].
• Schrijfopdrachten voor de gereserveerde blok-ID 1 zijn alleen toegestaan bij geactiveerde NvMDynamicConfiguration [SWS_NvM_00311].

Foutafhandeling en gelijktijdigheid:

• Als ontwikkelingsdetectie actief is, meldt NvM_WriteBlock de DET-fout NVM_E_UNINIT bij een niet-geïnitialiseerde module [SWS_NvM_00619] en NVM_E_BLOCK_PENDING als hetzelfde blok al in behandeling of in de wachtrij geplaatst is [SWS_NvM_00620]. Een ontbrekende bronpointer bij tijdelijke buffers leidt tot een DET-parameterfout [SWS_NvM_00280].
• Negatieve terugmeldingen van de geheugeninterface verhogen de herhalingsteller; na overschrijding van NVM_MAX_NUM_OF_WRITE_RETRIES eindigt de job met NVM_REQ_NOT_OK [SWS_NvM_00213], [SWS_NvM_00216].
• Als het blok is geconfigureerd met onmiddellijke prioriteit, breekt NvM_WriteBlock een momenteel lopende job destructief af, zodat de schrijfopdracht als volgende wordt verwerkt [SWS_NvM_00300].

Gebruik en semantiek

De functie NvM_RestoreBlockDefaults herstelt standaardgegevens in het toegewezen RAM-blok ([SWS_NvM_00456], [SWS_NvM_00012]). Deze werkt asynchroon: na de aanroep neemt deze de parameters over, plaatst het verzoek in de interne opdrachtwachtrij en keert direct terug met E_OK bij succesvolle acceptatie of met E_NOT_OK bij afwijzing ([SWS_NvM_00456], [SWS_NvM_00224]). Wordt via de uitgangsparameter NvM_DestPtr een geldig RAM-adres doorgegeven, dan wordt dit als doeladres gebruikt ([SWS_NvM_00435]). Om ROM-gegevens naar een tijdelijk RAM-blok te kopiëren hoewel een permanent RAM-blok of synchronisatie-callbacks zijn geconfigureerd, moet de oproeper dwingend een pointer ongelijk aan NULL doorgeven ([SWS_NvM_00436]).

Foutafhandeling en randvoorwaarden

De functie is niet-re-entrant ([SWS_NvM_00456]) en onderdeel van de API-configuratieklassen 2 en 3 ([SWS_NvM_00561], [SWS_NvM_00560]). Als ontwikkelingsfoutdetectie (DET) actief is, meldt deze NVM_E_UNINIT als de module nog niet geïnitialiseerd is ([SWS_NvM_00625]), NVM_E_PARAM_BLOCK_ID bij ongeldige BlockId ([SWS_NvM_00630]) evenals een parameterfout wanneer bij permanent geconfigureerde blokken voor tijdelijk kopiëren geen geldige doelpointer wordt doorgegeven ([SWS_NvM_00436]). De functie faalt synchroon met E_NOT_OK wanneer het blok van het type NVM_BLOCK_DATASET is, er ten minste één ROM-blok bestaat en de actuele gegevensindex naar een NV-blok verwijst ([SWS_NvM_00353]).

Taakverwerking en interactie

In het kader van de asynchrone taakverwerking laadt de service standaardwaarden uit een geconfigureerd ROM-blok ([SWS_NvM_00267]). Als een permanent RAM-blok is aangevraagd of er een expliciete synchronisatie-callback (NvMReadRamBlockFromNvCallback) wordt gebruikt, wordt het RAM-blok vóór het kopiëren resp. vóór de callback-aanroep geïnvalideerd ([SWS_NvM_00227]). Na een succesvolle kopieerbewerking of na terugkeer van de synchronisatie-callback met E_OK wordt het RAM-blok gevalideerd en als gewijzigd gemarkeerd ([SWS_NvM_00228]). Is voor het blok een controlesom geconfigureerd, dan vraagt de taak tot slot een CRC-herberekening aan ([SWS_NvM_00229]). Dezelfde herstellogica gebruiken ook NvM_ReadBlock en NvM_ReadAll als uitwijkmechanisme bij een foutieve leesactie van het geheugen of bij CRC-fouten ([SWS_NvM_00202], [SWS_NvM_00293], [SWS_NvM_00657]).

De re-entrante, asynchrone functie NvM_EraseNvBlock ([SWS_NvM_00457]) van API-configuratieklasse 3 ([SWS_NvM_00560]) dient voor het wissen van een niet-vluchtig geheugenblok aan de hand van de doorgegeven BlockId. Voor zover er geen schrijfbeveiliging actief is, neemt de functie de parameters over, plaatst de wisopdracht in de interne opdrachtwachtrij en keert onmiddellijk terug ([SWS_NvM_00231], [SWS_NvM_00418]). De retourwaarde E_OK signaleert de succesvolle acceptatie van de opdracht, terwijl E_NOT_OK de afwijzing aangeeft ([SWS_NvM_00457]).

Vóór de aanroep moet de NvM-module volledig geïnitialiseerd zijn ([SWS_NvM_00715]). Na het in de wachtrij plaatsen wordt de schrijfbeveiliging vóór het uit de wachtrij nemen van de taak niet opnieuw gecontroleerd ([SWS_NvM_00662]). Bij redundante blokken van het type NVM_BLOCK_REDUNDANT geldt de wisprocedure pas als geslaagd wanneer beide redundante NV-blokken zijn gewist ([SWS_NvM_00269]). De gegevensinhoud van een toegewezen RAM-blok blijft door de opdrachtafhandeling altijd ongewijzigd ([SWS_NvM_00416]).

Een aanroep wordt afgewezen wanneer een ROM-blok van een dataset-blok wordt geadresseerd ([SWS_NvM_00661]) of het blok middels NvM_SetBlockLockStatus is geblokkeerd ([SWS_NvM_00751]). Bij ingeschakelde ontwikkelingsfoutdetectie (DET) meldt de functie NVM_E_UNINIT bij een niet-geïnitialiseerde module ([SWS_NvM_00631]), NVM_E_PARAM_BLOCK_ID bij een ongeldige BlockId ([SWS_NvM_00635]) evenals NVM_E_BLOCK_LOCKED bij een geblokkeerd blok ([SWS_NvM_00757]). Heeft het blok geen directe prioriteit ("immediate priority") resp. is standaardprioriteit geconfigureerd, dan wordt bij actief DET de fout NVM_E_BLOCK_CONFIG gemeld en E_NOT_OK geretourneerd ([SWS_NvM_00357], [SWS_NvM_00636]). Mislukt de latere asynchrone uitvoering, dan wordt de verzoekstatus op NVM_REQ_NOT_OK gezet ([SWS_NvM_00271]) en wordt NVM_E_REQ_FAILED aan het DEM gemeld ([SWS_NvM_00663]).

De functie NvM_InvalidateNvBlock is een asynchrone en re-entrante service van API-configuratieklasse 3 voor de invalidatie van een NV-blok [SWS_NvM_00459], [SWS_NvM_00560]. Als aanroepvoorwaarde geldt dat de NvM-module vooraf door de module-omgeving moet zijn geïnitialiseerd [SWS_NvM_00717]. De aanroep neemt de parameter BlockId over, plaatst het verzoek bij uitgeschakelde schrijfbeveiliging in de wachtrij en keert terug met E_OK [SWS_NvM_00239], [SWS_NvM_00424]. Indien de opdracht niet kan worden geaccepteerd, levert de functie E_NOT_OK [SWS_NvM_00459].

Een aanroep wordt synchroon afgewezen met E_NOT_OK als via BlockId een ROM-blok van een dataset-blok (Dataset) is opgegeven [SWS_NvM_00664]. Als het blok voordien via NvM_SetBlockLockStatus is vergrendeld, wijst de NvM de opdracht af [SWS_NvM_00751] en meldt bij actieve ontwikkelingsinterface de DET-fout NVM_E_BLOCK_LOCKED [SWS_NvM_00756]. Als het blok al in de wachtrij staat of in uitvoering is, volgt de DET-melding NVM_E_BLOCK_PENDING [SWS_NvM_00639].

De eigenlijke asynchrone taak invalideert het gereferentieerde NV-blok [SWS_NvM_00421] met inachtneming van de volgende randvoorwaarden:

• Bij redundante blokken (NVM_BLOCK_REDUNDANT) wordt het opdrachtresultaat pas op NVM_REQ_OK gezet wanneer beide redundante NV-blokken succesvol zijn geïnvalideerd [SWS_NvM_00274]; hetzelfde mechanisme wordt ook toegepast bij NvM_FirstInitAll [SWS_NvM_00919], [SWS_NvM_00920].
• Voor blokken met NVM_WRITE_BLOCK_ONCE laat de taak de schrijfbeveiliging ongewijzigd [SWS_NvM_00960]. Ging er geen leesbewerking aan vooraf, dan meldt de taak de DET-fout NVM_E_WRITE_ONCE_STATUS_UNKNOWN [SWS_NvM_00958].
• Treedt er tijdens de asynchrone verwerking een fout op, dan wordt het verzoekresultaat op NVM_REQ_NOT_OK gezet [SWS_NvM_00275] en wordt de productiefout NVM_E_REQ_FAILED verzonden naar de DEM [SWS_NvM_00666].

Gebruik

De asynchrone en re-entrante functie [SWS_NvM_00764] dient voor het kopiëren van gegevens van een NV-blok naar het toegewezen permanente RAM-blok. De aanroep neemt de BlockId over, plaatst het leesverzoek in de interne opdrachtwachtrij en keert direct terug [SWS_NvM_00766]. De retourwaarde E_OK bevestigt de acceptatie van de opdracht, terwijl E_NOT_OK een afwijzing signaleert [SWS_NvM_00764]. De functie behoort tot de functionele omvang van de API-configuratieklassen 2 en 3 [SWS_NvM_00560], [SWS_NvM_00561].

Verloop en synchronisatie

Bij succesvolle plaatsing van de opdracht in de wachtrij of het begin van de verwerking wordt het permanente RAM-blok onmiddellijk geïnvalideerd [SWS_NvM_00767]. Is voor het blok expliciete synchronisatie ingesteld, dan mag de applicatie het RAM-blok wijzigen tot het binnenkomen van de synchronisatieroutine; de invalidatie vindt in dit geval direct vóór de aanroep van NvMReadRamBlockFromNvCallback plaats [SWS_NvM_00706], [SWS_NvM_00767]. Werden de NV-gegevens foutloos naar het RAM overgedragen, dan sluit de opdracht af met de status NVM_REQ_OK [SWS_NvM_00765], [SWS_NvM_00775].

Foutafhandeling en redundantie

Bij blokken van het type NVM_BLOCK_REDUNDANT start de opdracht automatisch een leespoging op het tweede blok indien de eerste leespoging mislukt [SWS_NvM_00768]. Bij datasets (NVM_BLOCK_DATASET) wordt het kopiëren verhinderd indien het via de index geselecteerde NV-blok inconsistent is [SWS_NvM_00771]; verwijst de index naar ROM-gegevens, dan worden deze geladen en wordt het resultaat op NVM_REQ_OK gezet [SWS_NvM_00772]. Zijn er standaardgegevens geconfigureerd en is het NV-blok bij ongeldige RAM-toestand niet leesbaar, dan vindt er een impliciet herstel plaats [SWS_NvM_00575], dat het RAM-blok als geldig en gewijzigd classificeert [SWS_NvM_00774]; zonder geconfigureerde standaardwaarden blijft het herstel achterwege [SWS_NvM_00572]. Was voorheen NvM_SetBlockLockStatus actief, dan wordt het opnieuw laden uit het NV-geheugen afgedwongen [SWS_NvM_00752].

De re-entrante, asynchrone functie NvM_WritePRAMBlock initieert het schrijven van de gegevens van een permanent RAM-blok naar het bijbehorende NV-blok [SWS_NvM_00793], [SWS_NvM_00794]. De functie is beschikbaar in de API-configuratieklassen 2 en 3 [SWS_NvM_00561], [SWS_NvM_00560]. De gereserveerde blok-ID 1 mag alleen worden meegegeven wanneer NvMDynamicConfiguration op TRUE is ingesteld [SWS_NvM_00311].

Bij de overdracht levert de functie E_OK bij succesvolle acceptatie of E_NOT_OK [SWS_NvM_00793]. Is het gereferentieerde blok vergrendeld, dan mislukt de aanroep met E_NOT_OK en meldt de module een DET-fout [SWS_NvM_00797]. Een blokbeveiliging wordt al gecontroleerd bij het plaatsen in de opdrachtwachtrij en wordt vóór de opdrachtuitvoering niet opnieuw gevalideerd [SWS_NvM_00799]. Heeft het NVRAM-blok onmiddellijke prioriteit (immediate priority), dan wordt een lopende opdracht direct destructief afgebroken en wordt deze schrijfopdracht als volgende verwerkt [SWS_NvM_00800].

Voorafgaand aan de eigenlijke overdracht naar het NV-geheugen vraagt de opdracht een CRC-herberekening aan, voor zover het blok met CRC is geconfigureerd [SWS_NvM_00801]. Een nog ongeldig permanent RAM-blok wordt automatisch gevalideerd [SWS_NvM_00803]. Bij redundante blokken (NVM_BLOCK_REDUNDANT) worden beide NV-blokken beschreven, beginnend met het blok dat bij voorgaande leesopdrachten niet is gelezen [SWS_NvM_00807], [SWS_NvM_00808]. Bij schrijffouten wordt het aantal herhalingen beperkt door NVM_MAX_NUM_OF_WRITE_RETRIES [SWS_NvM_00806]; bij een overschrijding stelt de NvM het opdrachtresultaat in op NVM_REQ_NOT_OK [SWS_NvM_00804] en meldt NVM_E_REQ_FAILED aan het DEM [SWS_NvM_00805].

Met betrekking tot gelijktijdigheid geldt: bij impliciete synchronisatie mag de applicatie de buffergegevens na de aanroep tot het einde van de opdracht niet meer wijzigen; leestoegang blijft toegestaan [SWS_NvM_00698]. Bij expliciete synchronisatie mag de buffer worden gewijzigd totdat de callback-routine NvMWriteRamBlockToNvCallback wordt aangeroepen [SWS_NvM_00705].

Gebruik en semantiek

De functie NvM_RestorePRAMBlockDefaults herstelt standaardgegevens in het bijbehorende permanente RAM-blok ([SWS_NvM_00813], [SWS_NvM_00814]). De service werkt asynchroon en neemt via de parameter BlockId de identificatie van de NVRAM-blokdescriptor over ([SWS_NvM_00813]). Bij de aanroep wordt het verzoek in de interne opdrachtwachtrij geplaatst ([SWS_NvM_00815]). De retourwaarde E_OK signaleert de succesvolle acceptatie, terwijl E_NOT_OK een afwijzing aangeeft ([SWS_NvM_00813]). Is er een ROM-blok geconfigureerd, dan worden de gegevens in het kader van de asynchrone verwerking daaruit geladen ([SWS_NvM_00816]).

Foutafhandeling en randvoorwaarden

Zijn er voor het blok noch ROM-standaardgegevens noch een callback-routine NvMInitBlockCallback vastgelegd, dan blijft de blokstatus ongewijzigd en levert de aanroep E_NOT_OK op ([SWS_NvM_00884]). Bij geactiveerde ontwikkelingsdetectie (DET) worden specifieke fouten gemeld:

• NVM_E_UNINIT: De module is nog niet geïnitialiseerd ([SWS_NvM_00831]).
• NVM_E_PARAM_BLOCK_ID: De meegegeven BlockId ligt buiten het geldige bereik ([SWS_NvM_00834]).
• NVM_E_BLOCK_PENDING: Voor de block-ID staat er al een opdracht in de wachtrij of is deze in bewerking ([SWS_NvM_00832]).
• NVM_E_BLOCK_WITHOUT_DEFAULTS: Er bestaan noch ROM-standaardgegevens noch een initialisatie-callback ([SWS_NvM_00886]).
• NVM_E_PARAM_ADDRESS: Er is noch een permanent RAM-blok noch een expliciete synchronisatie geconfigureerd ([SWS_NvM_00894]).

Gelijktijdigheid en wisselwerking

De service is gespecificeerd als niet-re-entrant ([SWS_NvM_00813]) en is beschikbaar in de API-configuratieklassen 2 en 3 ([SWS_NvM_00561], [SWS_NvM_00560]). Dezelfde herstellogica wordt bovendien intern toegepast bij NvM_ReadPRAMBlock, indien het onderliggende leesproces mislukt ([SWS_NvM_00789], [SWS_NvM_00882]).

De functie NvM_ReadAll initieert asynchroon een multiblock-leesopdracht voor de initialisatie van de RAM-datablokken [SWS_NvM_00460], [SWS_NvM_00158]. Deze heeft geen parameters, levert geen retourwaarde op en is niet-re-entrant [SWS_NvM_00460]. De aanroep signaleert het verzoek aan de NvM-module en keert direct terug; de daadwerkelijke verwerking wordt echter uitgesteld totdat alle individuele blokopdrachtwachtrijen leeg zijn [SWS_NvM_00243].

Aan het begin valideert de opdracht tijdens de systeemstart de configuratie-ID door vergelijking van de opgeslagen waarde met de gecompileerde waarde [SWS_NvM_00073], [SWS_NvM_00246]:

• Bij overeenstemming vindt de normale voorbereiding plaats voor alle geconfigureerde blokken [SWS_NvM_00247].
• Een configuratieverschil wordt genegeerd als NvMDynamicConfiguration == FALSE is ingesteld [SWS_NvM_00248].
• Als NvMDynamicConfiguration == TRUE en NvMResistantToChangedSw == FALSE, wordt bij niet-overeenstemming een uitgebreide voorbereiding uitgevoerd [SWS_NvM_00249].

Vervolgens itereert de opdracht over alle gebruikersblokken, beginnend met de laagste blok-ID (met uitzondering van de gereserveerde ID's 0 en 1) [SWS_NvM_00244]. Er wordt rekening gehouden met permanente RAM-blokken of blokken met geconfigureerde synchronisatie-callback NvM_ReadRamBlockFromNvm, mits NvmSelectBlockForReadall == TRUE is geconfigureerd [SWS_NvM_00118]. Niet-gelezen maar geselecteerde blokken krijgen het resultaat NVM_REQ_BLOCK_SKIPPED [SWS_NvM_00287].

Bij redundante blokken (NVM_BLOCK_REDUNDANT) wordt bij het mislukken van de eerste leespoging automatisch het tweede NV-blok gelezen [SWS_NvM_00288]. Na succesvol laden in het RAM wordt de blokstatus ingesteld op „valid/unmodified” en het opdrachtresultaat op NVM_REQ_OK [SWS_NvM_00251], [SWS_NvM_00290], [SWS_NvM_00291]. Voor blokken met NvMCalRamBlockCrC == TRUE vraagt de opdracht een CRC-herberekening aan [SWS_NvM_00292]. Indien geconfigureerd wordt per blok NvMSingleBlockCallback en na het laatste blok MultiBlockCallback aangeroepen [SWS_NvM_00281].

Gebruik en aanroepcontext

De functie NvM_WriteAll initieert asynchroon een multiblock-schrijfopdracht en heeft noch parameters noch retourwaarden [SWS_NvM_00461]. Na de aanroep signaleert de functie het verzoek aan de NvM-module en keert onmiddellijk terug [SWS_NvM_00254]. De daadwerkelijke verwerking wordt uitgesteld totdat alle wachtrijen voor individuele blokopdrachten volledig zijn afgewerkt [SWS_NvM_00254]. De aanroep vindt doorgaans plaats in het kader van het fundamentele uitschakelproces (shutdown) door de BSW Mode Manager [SWS_NvM_00092].

Verloop en blokverwerking

Tijdens de shutdown synchroniseert de opdracht permanente RAM-blokken met de bijbehorende NV-blokken of voert deze de expliciete synchronisatie-callback NvM_WriteRamBlockToNvm uit [SWS_NvM_00018]. Daarbij worden uitsluitend blokken meegenomen waarvoor de configuratieparameter NvMSelectBlockForWriteAll is ingesteld op true [SWS_NvM_00252], evenals blok 1 in het geval van afwijkende configuratie-ID's bij actieve dynamische configuratie [SWS_NvM_00310]. Indien voor een NVRAM-blok een CRC is geconfigureerd, vraagt de opdracht vóór het schrijfproces een herberekening aan en werkt deze de controlesom bij [SWS_NvM_00253]. Voor blokken met NvMWriteBlockOnce == TRUE stelt de opdracht na succesvol schrijven direct de schrijfbeveiligingsflag in het administratieve blok in [SWS_NvM_00329].

Gelijktijdigheid en foutafhandeling

• Re-entrantie: de functie is niet-re-entrant [SWS_NvM_00461].
• Foutbewaking: om oneindige lussen te voorkomen, bewaakt een retry-teller de herhaalpogingen bij niet-succesvolle terugmeldingen van de MemIf-module [SWS_NvM_00296].
• Opdrachtresultaten: als de verwerking van ten minste één blok mislukt, wordt het totale resultaat ingesteld op NVM_REQ_NOT_OK [SWS_NvM_00318]. Voor geconfigureerde blokken die niet zijn geschreven, wordt het individuele resultaat NVM_REQ_BLOCK_SKIPPED ingesteld [SWS_NvM_00298]. Bij redundante blokken (NVM_BLOCK_REDUNDANT) geldt de individuele opdracht als NVM_REQ_OK zodra ten minste één van de NV-blokken succesvol is geschreven [SWS_NvM_00337].
• Afbreken: een lopende opdracht kan worden afgebroken door NvM_CancelWriteAll [SWS_NvM_00019]. Dit leidt tot het totale resultaat NVM_REQ_CANCELED [SWS_NvM_00237], waarbij het zojuist verwerkte blok niet-destructief en dataconsistent wordt voltooid [SWS_NvM_00238].

Gebruik en semantiek

De functie NvM_CancelWriteAll dient ertoe om een lopende meervoudige-blok-schrijfbewerking (NvM_WriteAll) voortijdig af te breken [SWS_NvM_00458], [SWS_NvM_00019]. De aanroep is asynchroon, niet-re-entrant, accepteert geen parameters en levert geen retourwaarde op [SWS_NvM_00458]. De functie signaleert de wens tot afbreken direct aan de module en keert onmiddellijk terug [SWS_NvM_00232]. Het verzoek wordt niet in de opdrachtwachtrij geplaatst; er kan steeds slechts één verzoek van dit type openstaan [SWS_NvM_00420]. Is op het moment van aanroepen geen bewerking actief, dan blijft de aanroep zonder effect [SWS_NvM_00233].

Verloop en gegevensconsistentie

Het afbreken wordt zodanig uitgevoerd dat de gegevensconsistentie van het op het moment van afbreken verwerkte NVRAM-blok niet nadelig wordt beïnvloed [SWS_NvM_00019]. De module rondt dit actieve blok regulier af en stelt het statusattribuut ervan afhankelijk van het succes in op NVM_REQ_OK of NVM_REQ_NOT_OK, terwijl alle resterende, nog openstaande blokken op NVM_REQ_CANCELED worden gezet [SWS_NvM_00236]. Het totale resultaat is impliciet bepaald door het resultaat van de afgebroken operatie [SWS_NvM_00235], wordt opgeslagen in een afzonderlijke variabele [SWS_NvM_00393] en kan via NvM_GetErrorStatus met vermelding van de gereserveerde blok-ID 0 worden opgevraagd [SWS_NvM_00394]. Bovendien kan optioneel een overkoepelende callback (NvMMultiBlockCallback) worden genotificeerd [SWS_NvM_00260]. Voor zover geconfigureerd via NvMDrvModeSwitch, schakelt de opdracht de geheugenapparaten na het afbreken om naar de langzame bedrijfsmodus („slow-mode”) [SWS_NvM_00681].

Beperkingen en foutafhandeling

De aanroep van NvM_CancelWriteAll is functioneel beperkt en mag uitsluitend worden uitgevoerd door de BSW Mode Manager (BswM) [SWS_NvM_00703]. Bovendien behoort de functie tot API-configuratieklasse 2 [SWS_NvM_00561]. De module moet vóór de aanroep zijn geïnitialiseerd [SWS_NvM_00716]; bij geactiveerde ontwikkelingsdetectie (DET) leidt een aanroep in niet-geïnitialiseerde toestand tot de foutmelding NVM_E_UNINIT [SWS_NvM_00637].

De functie NvM_ValidateAll brengt de asynchrone validatie van meerdere NVRAM-blokken op gang ([SWS_NvM_00855]) en behoort tot API-configuratieklasse 3 ([SWS_NvM_00560]). Deze is niet-re-entrant, verwacht geen parameters en levert geen retourwaarde op ([SWS_NvM_00855]). Vóór de aanroep moet de NvM-module geïnitialiseerd zijn ([SWS_NvM_00859]).

Bij de aanroep signaleert de functie het verzoek aan de module en keert direct terug ([SWS_NvM_00858]). De feitelijke afhandeling wordt echter vertraagd totdat alle opdrachtwachtrijen voor enkelvoudige blokken volledig zijn verwerkt ([SWS_NvM_00858]). Voor multi-block-opdrachten is in de opdrachtwachtrij in totaal slechts één enkele plaats beschikbaar ([SWS_NvM_00380]). Het totale resultaat van de asynchrone opdracht wordt bijgehouden in een afzonderlijke toestandsvariabele ([SWS_NvM_00393]).

In het kader van de opdrachtafhandeling worden vooraf zowel het multi-block-resultaat als de resultaten van de betreffende individuele blokken op NVM_REQ_PENDING gezet ([SWS_NvM_00861]). De verwerking houdt uitsluitend rekening met blokken waarvoor NvMBlockUseAutoValidation op TRUE is geconfigureerd ([SWS_NvM_00856], [SWS_NvM_00860]):

• Er worden permanente RAM-blokken verwerkt of de expliciete synchronisatie via de callback NvM_WriteRamBlockToNvm wordt uitgevoerd ([SWS_NvM_00860]).
• De RAM-blokstatus wordt ingesteld op „VALID / CHANGED” ([SWS_NvM_00856]).
• Is er daarnaast een CRC-berekening in het RAM geconfigureerd, dan vraagt de opdracht de herberekening op de achtergrond aan, die via NvM_MainFunction wordt verwerkt ([SWS_NvM_00857]).
• Na succesvolle validatie van het RAM-blok wisselt het blokspecifieke resultaat naar NVM_REQ_OK ([SWS_NvM_00862]).

De functie NvM_FirstInitAll brengt de asynchrone eerste initialisatie van meerdere geconfigureerde blokken op gang ([SWS_NvM_91001]). De service is niet-re-entrant, verwacht geen parameters en levert geen retourwaarde op ([SWS_NvM_91001]). Bij de afhandeling wordt er geen rekening mee gehouden of een blok in het niet-vluchtige geheugen al bestaat of geldig dan wel gecorrumpeerd is ([SWS_NvM_91001]). De wachtrijlengte voor multi-block-opdrachten (onder andere uit NvM_FirstInitAll) bedraagt één, zodat er slechts één enkele multi-block-opdracht tegelijk in de wachtrij kan worden geplaatst ([SWS_NvM_00380]).

De verwerking verschilt naargelang het beheertype van het blok:

• NATIVE: Zijn er standaardgegevens aanwezig, dan wordt het NV-blok daarmee beschreven ([SWS_NvM_00913]). Beschikt het blok over permanent RAM of expliciete synchronisatie, dan wordt het RAM zoals bij NvM_RestoreBlockDefaults bijgewerkt met de standaardgegevens (ROM of init-callback) ([SWS_NvM_00915]); zonder permanent RAM en zonder expliciete synchronisatie dient de interne NvM-buffer als RAM, waarbij de RAM-toestand onaangeroerd blijft ([SWS_NvM_00914]). Ontbreken standaardgegevens ([SWS_NvM_00919]) of mislukt een geconfigureerde init-callback met een retourwaarde ongelijk aan E_OK ([SWS_NvM_00921]), dan wordt het blok geïnvalideerd.
• REDUNDANT: Zijn er standaardgegevens aanwezig, dan worden beide blokinstanties daarmee geschreven ([SWS_NvM_00916]) en wordt bij aanwezig permanent RAM dan wel expliciete synchronisatie het RAM bijgewerkt ([SWS_NvM_00918]); anders wordt de interne buffer gebruikt ([SWS_NvM_00917]). Levert een init-callback niet E_OK op, dan worden beide instanties geïnvalideerd ([SWS_NvM_00922]).
• DATASET: Alle voor de verwerking geconfigureerde blokken respectievelijk NV-blokinstanties van dit type worden zonder uitzondering geïnvalideerd ([SWS_NvM_00923], [SWS_NvM_00924]).

Mislukt het schrijven van een NATIVE-blok met standaardgegevens ([SWS_NvM_00925]), de invalidatie van een NATIVE-blok ([SWS_NvM_00927]) of het schrijven van beide instanties van een REDUNDANT-blok ([SWS_NvM_00926]), dan stelt de opdracht het totale resultaat in op NVM_REQ_NOT_OK.

Gebruik

De synchrone callback-functie NvM_JobEndNotification wordt aangeroepen door de onderliggende geheugenabstractie om het foutloze einde van een opdracht te signaleren aan de NVRAM-manager [SWS_NvM_00462]. De functie heeft noch parameters noch een retourwaarde en is beschikbaar via het headerbestand NvM_MemIf.h met service-ID 0x11 [SWS_NvM_00462]. Een succesvolle notificatie van de geheugenabstractie omvat foutloos voltooide lees-, schrijf- of wisoperaties [SWS_NvM_00111].

Gelijktijdigheid en beperkingen

De interface is gespecificeerd als niet-re-entrant [SWS_NvM_00462]. Afhankelijk van de aanroepende functie binnen de geheugenabstractie kan deze routine worden uitgevoerd in de interruptcontext [SWS_NvM_00111]. Alle modules van de geheugenabstractie moeten zo worden geconfigureerd dat ze uniform dezelfde modus – callback of polling – gebruiken [SWS_NvM_00111].

Configuratie en interactie

De NvM-module stelt de callback-functie NvM_JobEndNotification alleen beschikbaar wanneer de polling-modus via de configuratieparameter NvMPollingMode is uitgeschakeld [SWS_NvM_00440]. Bovendien wordt de functie beïnvloed door algemene NvM-configuratieparameters [SWS_NvM_00440].

De callback-functie NvM_JobErrorNotification ([SWS_NvM_00463]) dient ertoe dat de onderliggende geheugenabstractielaag het foutieve einde van een asynchrone opdracht signaleert aan de NVRAM-managermodule (NvM). De aanroep vindt synchroon plaats en is gespecificeerd als niet-re-entrant ([SWS_NvM_00463]).

Gebruik en signatuur

• Interface: De functiedeclaratie wordt beschikbaar gesteld via het headerbestand NvM_MemIf.h ([SWS_NvM_00463]).
• Signatuur: Volgens void NvM_JobErrorNotification(void) heeft de functie invoer-, uitvoer- noch invoer/uitvoerparameters en levert deze geen retourwaarde op ([SWS_NvM_00463]).
• Service-ID: De functie is geïdentificeerd via de hexadecimale identificatie 0x12 ([SWS_NvM_00463]).

Configuratie-afhankelijkheid en samenspel

De module NvM stelt de callback-functie NvM_JobErrorNotification alleen dan beschikbaar wanneer de polling-modus via de configuratieparameter NvMPollingMode is uitgeschakeld ([SWS_NvM_00441]). Wordt polling gebruikt, dan vervalt dit notificatiemechanisme. Daarnaast wordt de functie beïnvloed door de algemene configuratieparameters conform [SWS_NvM_00028] tekst nog niet geïmporteerd ([SWS_NvM_00441]).

Foutafhandeling en gelijktijdigheid

De functie dient uitsluitend voor de foutmelding van opdrachten en definieert noch eigen foutcodes noch DET- of DEM-terugmeldingen ([SWS_NvM_00463]). Vanwege de classificatie als Non Reentrant is het vermoedelijk aan de aanroeper in de geheugenabstractie om ervoor te zorgen dat er geen overlappende of onderbrekende aanroepen plaatsvinden ([SWS_NvM_00463]). Vraag Q-5f72d9d605c25922 (open)

Gebruik

De functie NvM_MainFunction heeft parameters noch een retourwaarde (void NvM_MainFunction(void)) en is gedeclareerd via SchM_NvM.h ([SWS_NvM_00464]). Deze dient voor de verwerking van de NVRAM-manager-opdrachten ([SWS_NvM_00464], [SWS_NvM_00256]). Na het afronden van een asynchrone service voert deze geconfigureerde callback-routines uit voor het notificeren van de hogere laag ([SWS_NvM_00347]). Bovendien neemt deze op de achtergrond aangevraagde CRC-herberekeningen voor NVRAM-blokken over ([SWS_NvM_00333]), bijvoorbeeld als gevolg van NvM_SetRamBlockStatus ([SWS_NvM_00121]) of NvM_ValidateAll ([SWS_NvM_00857]).

Volgordebesturing en prioritering

Voor zover geconfigureerd, bewaakt de functie de immediate-priority-queue op verzoeken met onmiddellijke prioriteit ([SWS_NvM_00259]). Als een regulier verzoek door een spoedopdracht destructief is afgebroken, herstart NvM_MainFunction dit na afloop daarvan ([SWS_NvM_00258]). Bij actieve polling-modus controleert deze de status van de aan de lagere laag overgedragen opdrachten ([SWS_NvM_00346]). Tijdens de verwerking van NvM_WriteAll fragt deze cyclisch de toestand van de geheugendriverabstractie via MemIf_GetStatus voor MEMIF_BROADCAST_ID op en houdt callbacks naar de hogere laag tegen zolang MEMIF_BUSY_INTERNAL wordt gemeld ([SWS_NvM_00350]).

Foutafhandeling en herhalingen

Mislukken applicatiespecifieke callbacks, dan stuurt NvM_MainFunction de herhaalpogingen aan:

• Levert NvMReadRamBlockFromNvCallback de waarde E_NOT_OK op, dan herhaalt de module de aanroep in de volgende cyclus van NvM_MainFunction ([SWS_NvM_00839]).
• Geeft NvMWriteRamBlockToNvCallback E_NOT_OK terug, dan vindt de herhaling eveneens plaats in de volgende aanroep van NvM_MainFunction ([SWS_NvM_00840]).
• Geeft de expliciete synchronisatie-callback bij NvM_SetRamBlockStatus E_NOT_OK terug, dan voert de module de geconfigureerde herhalingen uit met telkens één poging per aanroep van NvM_MainFunction ([SWS_NvM_00908]).

Gebruik

De callback-routine NvM_SingleBlockCallbackFunction notificeert de bovenliggende laag synchroon over de afronding van een eerder geïnitieerd asynchroon enkelvoudig blokverzoek [SWS_NvM_00467].

De functie verwerkt twee overdrachtsparameters [SWS_NvM_00467]:

• BlockRequest (type NvM_BlockRequestType): Draagt het type van het eerder uitgevoerde blokverzoek over, zoals bijvoorbeeld lees- of schrijfoperaties [SWS_NvM_00467].
• JobResult (type NvM_RequestResultType): Meldt het totale resultaat van de afgehandelde blokopdracht [SWS_NvM_00467].

Als retourwaarde levert de functie het type Std_ReturnType [SWS_NvM_00467]. Een succesvolle afhandeling van de callback wordt gesignaleerd door het teruggeven van E_OK; elke andere retourwaarde duidt op een niet-succesvolle uitvoering [SWS_NvM_00467].

Foutafhandeling en gelijktijdigheid

De interface specificeert geen eigen DET- of DEM-foutmeldingen [SWS_NvM_00467]. Het resultaat van de voorafgaande opdracht wordt doorgegeven via de parameter JobResult, terwijl fouten binnen de callback-verwerking zelf worden gemeld via de functieretourwaarde [SWS_NvM_00467].

Wat betreft gelijktijdigheid is de routine gedeclareerd als niet-re-entrant (Non Reentrant) [SWS_NvM_00467]. Deze wordt beschikbaar gesteld via de header NvM_Externals.h [SWS_NvM_00467]. De aanroep door de NvM-module vindt vermoedelijk synchroon plaats in de taakcontext van de cyclische NvM-opdrachtafhandeling (interpretatie). Vraag Q-f50640211851274f (open)

De callback-routine NvM_MultiBlockCallbackFunction notificeert de hogere laag erover dat een eerder geïnitieerde asynchrone multiblock-opdracht is afgerond [SWS_NvM_00468]. De declaratie van de functie wordt via het headerbestand NvM_Externals.h ter beschikking gesteld [SWS_NvM_00468].

Aanroepcontext en parameters

De aanroep door de NVRAM-manager vindt synchroon met de afhandeling in het verwerkingsproces plaats [SWS_NvM_00468]. Bij de aanroep worden twee parameters aan de routine overgedragen:

• MultiBlockRequest (type NvM_MultiBlockRequestType): Duidt het concrete verzoektype aan van de eerder verwerkte multiblock-opdracht, zoals bijvoorbeeld lees- of schrijftoegangen [SWS_NvM_00468].
• JobResult (type NvM_RequestResultType): Draagt het eindresultaat van de verwerking van de voorafgaande multiblock-taak over aan de hogere laag [SWS_NvM_00468].

Retourwaarde en foutafhandeling

De routine geeft een waarde van het type Std_ReturnType terug aan de aanroepende module [SWS_NvM_00468]. De retourwaarde E_OK geeft aan dat de callback-functie succesvol kon worden afgehandeld; elke andere retourwaarde signaleert daarentegen een mislukte verwerking [SWS_NvM_00468]. Specifieke foutcodes, DET- of DEM-meldingen zijn binnen de reikwijdte van de specificatie voor deze functie niet gedefinieerd. Interpretatie: de concrete consequenties van een retourwaarde ongelijk aan E_OK zijn vermoedelijk implementatiespecifiek, aangezien de standaard geen nageschakelde foutafhandeling voorschrijft. Vraag Q-462dea7f3074ae9c (open)

Gelijktijdigheid en beperkingen

De functie is gespecificeerd als niet-re-entrant (Non Reentrant) [SWS_NvM_00468]. Binnen het aanroepende systeem moet er daarom voor worden gezorgd dat er geen gelijktijdige of onderbrekende meervoudige aanroepen van deze callback-interface plaatsvinden.

Gebruik en aanroepcontext

De gebruikersspecifieke callback-routine NvM_InitBlockCallbackFunction wordt aangeroepen door de NvM-module wanneer standaardgegevens voor een NVRAM-blok in het RAM moeten worden hersteld en er geen overeenkomstig ROM-blok is geconfigureerd [SWS_NvM_00469]. De aanroep vindt synchroon plaats en de interface is gedeclareerd via de header NvM_Externals.h [SWS_NvM_00469].

Als overdrachtsparameter ontvangt de functie InitBlockRequest van het type NvM_InitBlockRequestType [SWS_NvM_00469]. Deze waarde informeert de routine over het specifieke verzoektype van het momenteel verwerkte blok, zoals het lezen of herstellen van gegevens (read, restore) [SWS_NvM_00469].

Retourwaarden en foutafhandeling

De routine geeft een statuswaarde van het type Std_ReturnType terug [SWS_NvM_00469]:

• E_OK: Signaleert aan de NvM-module dat de callback-functie de gegevens in het RAM succesvol heeft geïnitialiseerd en verwerkt [SWS_NvM_00469].
• Elke andere retourwaarde: Geeft aan dat de initialisatie niet succesvol kon worden voltooid [SWS_NvM_00469].

Specifieke foutcodes voor DET of DEM zijn voor de interface zelf niet gespecificeerd [SWS_NvM_00469].

Gelijktijdigheid en uitvoeringsbeperkingen

De interface is vastgelegd als synchroon en niet-re-entrant (Non Reentrant) [SWS_NvM_00469]. Aangezien de NVRAM Manager synchroon wacht op de terugkeer van de functie, zal een blokkerende uitvoering binnen de routine de verdere verwerking van de NvM vermoedelijk direct stopzetten (interpretatie). Vraag Q-c0e43c9871c4f2d0 (open)

De blokspecifieke callback-functie NvM_WriteRamBlockToNvm dient voor expliciete synchronisatie om applicatiegegevens vanuit het RAM-blok naar de interne RAM-spiegel van de NvM-module te kopiëren [SWS_NvM_00539]. Deze is declaratief beschikbaar via NvM_Externals.h en wordt synchroon aangeroepen door de NvM [SWS_NvM_00539].

Gebruik en parameters

De functie draagt als uitvoerparameter de pointer NvMBuffer over, die het doeladres van de NvM-spiegel vertegenwoordigt waarnaar de gegevens moeten worden geschreven [SWS_NvM_00539]. Als retourwaarde levert de callback-routine E_OK bij succesvolle verwerking of elke andere waarde bij een foutief verloop [SWS_NvM_00539].

Gelijktijdigheid en beperkingen

Conform de specificatie is NvM_WriteRamBlockToNvm ontworpen als niet-re-entrant (Non Reentrant) [SWS_NvM_00539].

Interactie in de module

• Bij het afsluiten synchroniseert de taak NvM_WriteAll permanente RAM-blokken of roept de callback-routine NvM_WriteRamBlockToNvm aan voor expliciete synchronisatie [SWS_NvM_00018], voor zover de parameter NvMSelectBlockForWriteAll voor het NVRAM-blok is geconfigureerd op true [SWS_NvM_00252].
• De schrijftaken NvM_WriteBlock [SWS_NvM_00303] en NvM_WritePRAMBlock [SWS_NvM_00803] valideren een nog ongeldig permanent RAM-blok automatisch na de aanroep van NvM_WriteRamBlockToNvm.

De functie NvM_ReadRamBlockFromNvm is een blokspecifieke callback-routine die wordt gedeclareerd via NvM_Externals.h [SWS_NvM_00540]. Het doel ervan is om de applicatie in staat te stellen gegevens vanuit de interne spiegelbuffer van de NvM-module naar het bijbehorende RAM-blok te kopiëren om een expliciete synchronisatie uit te voeren [SWS_NvM_00540], [SWS_NvM_00118].

Gebruik en semantiek

• Aanroepcontext en gelijktijdigheid: De aanroep vindt synchroon plaats en is gespecificeerd als niet-re-entrant (Non Reentrant) [SWS_NvM_00540].
• Parameters: Als overdrachtsparameter dient de pointer NvMBuffer (type const void*). Deze draagt het bufferadres over waaruit de gegevens kunnen worden gelezen en naar het RAM-blok kunnen worden gekopieerd [SWS_NvM_00540].
• Retourwaarde en foutafhandeling: De callback-functie levert een Std_ReturnType terug. De retourwaarde E_OK signaleert de succesvolle afhandeling; elke andere retourwaarde duidt op een niet-succesvolle verwerking [SWS_NvM_00540].

Samenspel

In het kader van de multiblock-service NvM_ReadAll wordt NvM_ReadRamBlockFromNvm aangeroepen voor expliciete synchronisatie voor die NVRAM-blokken die dienovereenkomstig zijn geconfigureerd en waarvoor NvmSelectBlockForReadall == TRUE geldt [SWS_NvM_00118], [SWS_NvM_00356]. Dit vormt het alternatief voor het directe kopieerproces naar permanente RAM-blokken, terwijl NvM_ReadAll de beheergegevens van de blokken initialiseert [SWS_NvM_00356].

Het enumeratietype NvM_MultiBlockRequestType wordt beschikbaar gesteld via het headerbestand NvM.h en dient voor de eenduidige aanduiding van een uitgevoerd multi-block-verzoek [SWS_NvM_91003]. Het type wordt gebruikt wanneer het resultaat of de status van een multi-block-operatie via een callback-functie wordt gesignaleerd of aan de module BswM wordt gemeld [SWS_NvM_91003].

Waardebereik en semantiek

De enumeratie definieert de volgende waarden ter differentiatie van de multi-block-opdrachten [SWS_NvM_91003]:

• NVM_READ_ALL (0x00): Geeft aan dat NvM_ReadAll is uitgevoerd.
• NVM_WRITE_ALL (0x01): Geeft aan dat NvM_WriteAll is uitgevoerd.
• NVM_VALIDATE_ALL (0x02): Geeft aan dat NvM_ValidateAll is uitgevoerd.
• NVM_FIRST_INIT_ALL (0x03): Geeft aan dat NvM_FirstInitAll is uitgevoerd.
• NVM_CANCEL_WRITE_ALL (0x04): Geeft aan dat NvM_CancelWriteAll is uitgevoerd.

Samenspel

Door dit type door te geven, kunnen aangeroepen callbacks en de BswM vaststellen welke concrete multiblok-service de melding heeft geactiveerd. Interpretatie: Vermoedelijk dient de terugkoppeling aan de BswM ertoe vervolgacties of statusovergangen in het totale systeem te koppelen aan de voltooiing van specifieke multiblok-services. Vraag Q-69b4d985301acfeb (open)

Het type NvM_RequestResultType is gebaseerd op uint8, is beschikbaar via Rte_NvM_Type.h en representeert het asynchrone verzoekresultaat van lees-, schrijf- en besturingsopdrachten van de NVRAM Manager [SWS_NvM_00470]. Het resultaat wordt primair opgevraagd via de API-dienst NvM_GetErrorStatus en kan aanvullend worden gesignaleerd via een geconfigureerde callback-functie [SWS_NvM_00470].

Het waardebereik representeert verschillende uitvoeringstoestanden en foutgevallen [SWS_NvM_00470]:

• NVM_REQ_OK (0x00): De laatste asynchrone opdracht is succesvol beëindigd; dit is tevens de standaardwaarde na een reset.
• NVM_REQ_NOT_OK (0x01): Het asynchrone lees-, schrijf- of besturingsverzoek is niet succesvol beëindigd.
• NVM_REQ_PENDING (0x02): Een asynchroon verzoek is momenteel nog in behandeling.
• NVM_REQ_INTEGRITY_FAILED (0x03): Gegevensintegriteitsfout bij NvM_ReadBlock of NvM_ReadAll. In het geval van NvM_ReadBlock is de inhoud van het RAM-blok gewijzigd, maar ongeldig geworden; de applicatie is er verantwoordelijk voor om de inhoud te vernieuwen en te valideren.
• NVM_REQ_BLOCK_SKIPPED (0x04): Het gerefereerde blok is tijdens NvM_ReadAll of NvM_WriteAll overgeslagen (bijv. dataset-NVRAM-blokken bij NvM_ReadAll of blokken zonder permanent geconfigureerd RAM-blok).
• NVM_REQ_NV_INVALIDATED (0x05): Het gerefereerde NV-blok is geïnvalideerd.
• NVM_REQ_CANCELED (0x06): Afbreken van NvM_WriteAll door NvM_CancelWriteAll of afbreken van een individuele blokopdracht (NvM_ReadBlock, NvM_WriteBlock, NvM_EraseNvBlock, NvM_InvalidateNvBlock, NvM_RestoreBlockDefaults) door NvM_CancelJobs.
• NVM_REQ_RESTORED_DEFAULTS (0x08): De standaardwaarden zijn succesvol gekopieerd naar de RAM-kopie.

In samenspel met redundante blokken (NVM_BLOCK_REDUNDANT) stelt de functie NvM_InvalidateNvBlock het verzoekresultaat NvM_RequestResultType pas dan in op NVM_REQ_OK wanneer beide NV-blokken zijn geïnvalideerd [SWS_NvM_00274].

Het datatype NvM_InitBlockRequestType is gebaseerd op uint8 en wordt beschikbaar gesteld via het headerbestand Rte_NvM_Type.h [SWS_NvM_91123]. Het dient ertoe het type van het op een NVRAM-blok uitgevoerde verzoek te identificeren wanneer dit via een bijbehorende callbackfunctie wordt gesignaleerd [SWS_NvM_91123].

Het toegestane waardebereik omvat vier verzoektypen [SWS_NvM_91123]:

• NVM_INIT_READ_BLOCK (0x00): Geeft aan dat NvM_ReadBlock of NvM_ReadPRAMBlock voor het blok is aangevraagd [SWS_NvM_91123].
• NVM_INIT_RESTORE_BLOCK_DEFAULTS (0x01): Signaleert dat NvM_RestoreBlockDefaults of NvM_RestorePRAMBlockDefaults voor het blok is aangevraagd [SWS_NvM_91123].
• NVM_INIT_READ_ALL_BLOCK (0x02): Wijst erop dat de verwerking van het blok plaatsvindt in het kader van NvM_ReadAll [SWS_NvM_91123].
• NVM_INIT_FIRST_INIT_ALL (0x03): Markeert de blokverwerking tijdens de uitvoering van NvM_FirstInitAll [SWS_NvM_91123].

Aan de hand van deze opsommingswaarde kan de aangeroepen applicatielogica onderscheiden of het om een expliciet enkelblokverzoek gaat (lezen of herstellen van standaardwaarden) dan wel om een globale verzameloperatie tijdens het opstarten van het systeem [SWS_NvM_91123]. Interpretatie: Het type zal vermoedelijk als parameter worden doorgegeven aan blokgerelateerde initialisatie-callbacks, zodat de applicatie passend bij de situatie standaardgegevens kan aanleveren of specifieke voorbereidingen kan treffen. Vraag Q-42d0d469e305728e (open)

Het enumeratietype NvM_BlockRequestType is gebaseerd op uint8 en wordt via de header Rte_NvM_Type.h ter beschikking gesteld [SWS_NvM_91002]. Het dient ertoe om bij een notificatie via een callback-functie het type van het verzoek over te dragen dat eerder op een NVRAM-blok is uitgevoerd [SWS_NvM_91002].

Het waardebereik omvat zes specifieke blokverzoeken [SWS_NvM_91002]:

• NVM_READ_BLOCK (0x00): Signaleert dat NvM_ReadBlock of NvM_ReadPRAMBlock voor het blok is uitgevoerd [SWS_NvM_91002].
• NVM_WRITE_BLOCK (0x01): Signaleert dat NvM_WriteBlock of NvM_WritePRAMBlock voor het blok is uitgevoerd [SWS_NvM_91002].
• NVM_RESTORE_BLOCK_DEFAULTS (0x02): Signaleert dat NvM_RestoreBlockDefaults of NvM_RestorePRAMBlockDefaults is uitgevoerd [SWS_NvM_91002].
• NVM_ERASE_NV_BLOCK (0x03): Signaleert dat NvM_EraseNvBlock op het blok is uitgevoerd [SWS_NvM_91002].
• NVM_INVALIDATE_NV_BLOCK (0x04): Signaleert dat NvM_InvalidateNvBlock op het blok is uitgevoerd [SWS_NvM_91002].
• NVM_READ_ALL_BLOCK (0x05): Signaleert dat NvM_ReadAll de verwerking van dit blok heeft voltooid [SWS_NvM_91002].

In de applicatiearchitectuur zal de waarde vermoedelijk als parameter in callback-routines worden geëvalueerd om bovenliggende softwarecomponenten gedifferentieerd te informeren over het einde van bepaalde blokoperaties [SWS_NvM_91002]. Vraag Q-467801b6b5e898a2 (open) Bij gebrek aan verdere specificaties in de payload over foutcodes of gelijktijdigheid beperken de specificatiedetails zich tot de typedefinitie en het waardebereik [SWS_NvM_91002].