PWM Driver (Pwm)

De synchrone functie Pwm_Init dient als centrale service voor de initialisatie van de gehele PWM-driver ([SWS_Pwm_00095]). Deze wordt ter beschikking gesteld via het headerbestand Pwm.h en heeft de hexadecimale service-ID 0x00 ([SWS_Pwm_00095]). Als enige invoerparameter wordt ConfigPtr doorgegeven, die fungeert als pointer naar de driverspecifieke configuratieset van het type Pwm_ConfigType ([SWS_Pwm_00095]). De interface heeft geen retourwaarde en gebruikt noch uitvoerparameters noch invoer-/uitvoerparameters ([SWS_Pwm_00095]).

Met betrekking tot het runtimegedrag is Pwm_Init synchroon en gespecificeerd als niet-re-entrant (Non Reentrant) ([SWS_Pwm_00095]). Een gelijktijdige of onderbrekende aanroep van deze functie vanuit meerdere threads, taken of interruptroutines is daarom strikt ontoelaatbaar. De uitvoering vindt typisch eenmalig plaats tijdens het opstarten van het systeem in de initialisatiefase van de ECU vóór het verdere gebruik van de PWM-kanalen. Vraag Q-ff3f1cf769dfed70 (open)

Ter borging van de toegestane aanroepvolgorde bewaakt de module zijn toestand: Als de service Pwm_Init wordt aangeroepen wanneer de PWM-driver al is geïnitialiseerd, meldt de module de ontwikkelingsfout PWM_E_ALREADY_INITIALIZED met het ID 0x14 ([SWS_Pwm_50002]). Een herhaalde initialisatie wordt zodoende als fout beschouwd.

Gebruik en signatuur

De functie Pwm_DeInit dient als service voor de de-initialisatie van de PWM-driver ([SWS_Pwm_00096]). Deze wordt via het headerbestand Pwm.h ter beschikking gesteld en heeft service-ID 0x01 ([SWS_Pwm_00096]). De interface heeft de signatuur void Pwm_DeInit(void), accepteert noch ingangs- noch uitgangsparameters en levert geen retourwaarde aan de aanroeper ([SWS_Pwm_00096]).

De aanroep van Pwm_DeInit wordt synchroon uitgevoerd ([SWS_Pwm_00096]). De aanroepende control flow blijft zodoende in de functie totdat de de-initialisatiestappen van de PWM-module zijn voltooid.

Gelijktijdigheid en beperkingen

Voor de uitvoering gelden de volgende randvoorwaarden met betrekking tot gelijktijdigheid:

• Niet-re-entrant: De service is gespecificeerd als niet-re-entrant ([SWS_Pwm_00096]). Een gelijktijdige of onderbrekende aanroep vanuit meerdere threads, tasks of ISR's is niet toegestaan.
• Aanroepcontext: Vanwege de synchrone semantiek en het ontbreken van re-entrantie vindt de aanroep vermoedelijk typisch plaats in het kader van een gecontroleerde shutdown-fase op taskniveau. Vraag Q-f1afc58637cba5cf (open)

Foutafhandeling

In de specificatie van Pwm_DeInit zijn noch retourwaarden noch specifieke foutcodes gedefinieerd ([SWS_Pwm_00096]). Eventuele runtime- of toestandsfouten worden vermoedelijk via module-interne bewakingsmechanismen zoals de ontwikkelingsinterface (DET) gelogd of afgevangen, aangezien een directe foutterugmelding via de functie-interface niet is voorzien. Vraag (open)

De functie Pwm_DisableNotification dient voor het deactiveren van de flankmelding (Signal Edge Notification) van een bepaald PWM-kanaal [SWS_Pwm_91003]. De functiedeclaratie en bijbehorende typedefinities worden ter beschikking gesteld via het headerbestand Pwm.h [SWS_Pwm_91003].

Parameters en retourwaarde

De interface heeft de service-ID 0x06 en vertoont de volgende signatuurkenmerken [SWS_Pwm_91003]:

• ChannelNumber (in): numerieke identificator van het te configureren PWM-kanaal van het type Pwm_ChannelType [SWS_Pwm_91003].

Er bestaan noch ingangs-/uitgangsparameters (inout) noch zuivere uitgangsparameters (out) [SWS_Pwm_91003]. De functie levert geen retourwaarde (void) terug aan de aanroeper [SWS_Pwm_91003].

Synchronisatiegedrag en concurrency

De aanroep van Pwm_DisableNotification werkt asynchroon [SWS_Pwm_91003]. Met betrekking tot het multithreading-gedrag is de service re-entrant, zolang verschillende kanaalnummers worden aangesproken [SWS_Pwm_91003].

Interpretatie: Aangezien de re-entrantie expliciet beperkt is tot verschillende kanalen, is de functie voor hetzelfde PWM-kanaal vermoedelijk niet re-entrant [SWS_Pwm_91003]. Vraag Q-005e97fd25679da7 (open) Gelijktijdige aanroepen voor een identiek kanaal moeten daarom vermoedelijk aan aanroeperszijde onderling worden gesynchroniseerd.

Gebruik

De functie Pwm_EnableNotification dient voor de activering van signaalflanknotificaties voor een bepaald PWM-kanaal conform de overgedragen notificatieparameter [SWS_Pwm_91004]. De service wordt via het headerbestand Pwm.h ter beschikking gesteld, heeft service-ID 0x07 en levert geen retourwaarde (void) terug aan de aanroeper [SWS_Pwm_91004].

Bij de aanroep van de interface moeten twee verplichte ingangsparameters worden overgedragen [SWS_Pwm_91004]:

• ChannelNumber (van het type Pwm_ChannelType): Numerieke identificatie van het aan te spreken PWM-kanaal [SWS_Pwm_91004].
• Notification (van het type Pwm_EdgeNotificationType): Definieert de aard van de flanknotificatie met de toegestane waarden PWM_RISING_EDGE, PWM_FALLING_EDGE of PWM_BOTH_EDGES [SWS_Pwm_91004].

Semantiek en gelijktijdigheid

De uitvoering van de service is gespecificeerd als asynchroon [SWS_Pwm_91004]. Met betrekking tot gelijktijdigheid is Pwm_EnableNotification re-entrant ontworpen voor verschillende kanaalnummers [SWS_Pwm_91004]. Bij een gelijktijdige of onderbrekende toegang tot hetzelfde PWM-kanaal is de service vermoedelijk niet-re-entrant; een dergelijke aanroep moet daarom aanroeperszijde worden beveiligd. Vraag Q-73309ed8589161a3 (open)

Foutafhandeling en randvoorwaarden

Het specificatie-uittreksel definieert voor deze functie noch specifieke retourwaarden noch foutmeldingen voor de Development Error Tracer (DET) of de Diagnostic Event Manager (DEM) [SWS_Pwm_91004]. Eveneens ontbreken voorschriften over toegestane aanroepcontexten of taskgerelateerde volgorden. Aangezien er geen randvoorwaarden worden genoemd, is de functieaanroep vermoedelijk pas na een succesvolle initialisatie van de PWM-driver toegestaan. Vraag Q-7f428f59a20175c2 (open)

De synchrone functie Pwm_SetPowerState brengt de PWM-module in een vooraf voorbereide toestand uit een voorgeconfigureerde selectie van power-states [SWS_Pwm_00166]. De declaratie is beschikbaar via de header Pwm.h [SWS_Pwm_00166].

Gebruik en retourwaarden

De functie accepteert geen invoerparameters en draagt het gedetailleerde resultaat over via de pointerparameter Result van het type Pwm_PowerStateRequestResultType* [SWS_Pwm_00166]:

• Kon de modus succesvol worden gewijzigd, dan retourneert de functie E_OK en stelt Result in op PWM_SERVICE_ACCEPTED [SWS_Pwm_00166].
• Wordt het verzoek afgewezen, dan retourneert de aanroep E_NOT_OK [SWS_Pwm_00166].

Foutafhandeling

In het geval van een fout (retourwaarde E_NOT_OK) specificeert Result de oorzaak van het mislukken [SWS_Pwm_00166]:

• PWM_NOT_INIT: De PWM-module is niet geïnitialiseerd [SWS_Pwm_00166].
• PWM_SEQUENCE_ERROR: Er is sprake van een niet-toegestane API-aanroepsequentie [SWS_Pwm_00166].
• PWM_HW_FAILURE: Een fout in de hardwaremodule verhindert het binnengaan van de aangevraagde power-state [SWS_Pwm_00166].

Gelijktijdigheid en randvoorwaarden

Pwm_SetPowerState is niet-re-entrant (Non Reentrant) en vereist ter voorkoming van een sequentiële fout dat de doeltoestand voorafgaand aan de aanroep is voorbereid [SWS_Pwm_00166].

Gebruik

De synchrone functie Pwm_PreparePowerState leidt het vereiste voorbereidingsproces in, zodat de PWM-hardwaremodule naar een aangevraagde energietoestand kan overgaan [SWS_Pwm_00183]. De gewenste doeltoestand wordt via de parameter PowerState overgedragen, terwijl het gedetailleerde resultaat via de uitvoerpointer Result ter beschikking wordt gesteld [SWS_Pwm_00183]. Werd de voorbereiding succesvol in gang gezet, dan retourneert de functie E_OK en stelt Result in op PWM_SERVICE_ACCEPTED [SWS_Pwm_00183].

Foutafhandeling

Wordt de service geweigerd, dan levert de functie E_NOT_OK en meldt de specifieke oorzaak via Result [SWS_Pwm_00183]:

• PWM_NOT_INIT: De PWM-module is niet geïnitialiseerd [SWS_Pwm_00183].
• PWM_SEQUENCE_ERROR: Niet-toegestane aanroepsequentie, aangezien de actuele energietoestand al overeenkomt met de doeltoestand [SWS_Pwm_00183].
• PWM_POWER_STATE_NOT_SUPP: De module ondersteunt de aangevraagde energietoestand niet [SWS_Pwm_00183].
• PWM_TRANS_NOT_POSSIBLE: Een directe overgang is niet mogelijk of het randapparaat van de hardware is nog bezig [SWS_Pwm_00183].

Gelijktijdigheid en wisselwerking

De functie is niet-re-entrant (Non Reentrant) en mag daarom voor dezelfde module niet gelijktijdig worden aangeroepen [SWS_Pwm_00183]. Na succesvolle voorbereiding door Pwm_PreparePowerState moeten downstream, niet onmiddellijk effectieve acties worden uitgevoerd om de energietoestandsovergang finaal te voltooien [SWS_Pwm_00190].

De interface Pwm_Main_PowerTransitionManager dient voor de cyclische bewaking van energietoestandsovergangen (Power State Transitions) van de PWM-driver conform [SWS_Pwm_00189]. Deze heeft service-ID 0x0d, accepteert geen overdrachtsparameters en levert geen retourwaarde op (signatuur void Pwm_Main_PowerTransitionManager(void)).

In het kader van haar cyclische uitvoering controleert de functie de operationele gereedheid van de module voor de desbetreffende energietoestand. Zodra de gereedheid aanwezig is, triggert deze de notificatie-callbacks IoHwAb_Pwm_NotifyReadyForPowerState<Mode>, waarnaar via de configuratieparameter PwmPowerStateReadyCbkRef wordt verwezen [SWS_Pwm_00189].

De functie is voorzien voor een cyclische aanroepcontext en wordt via het headerbestand SchM_Pwm.h ter beschikking gesteld. Bijgevolg vindt de periodieke aanroep vermoedelijk typisch plaats in de context van de BSW-scheduler (Schedule Manager) [SWS_Pwm_00189]. Vraag Q-b9b0431e7ccbca88 (open) Specifieke foutcodes, mechanismen voor foutafhandeling via DET of DEM evenals bijzondere re-entrantievoorwaarden zijn in de modulespecificatie voor deze service niet gedefinieerd.

De kanaalgebonden notificatiefunctie Pwm_Notification_<#Channel> wordt door de PWM-module synchroon aangeroepen zodra de voor het desbetreffende kanaal geconfigureerde flankgebeurtenis optreedt [SWS_Pwm_00105]. De functie heeft de signatuur void Pwm_Notification_<#Channel>(void), accepteert geen overdrachtsparameters en levert geen retourwaarde op [SWS_Pwm_00105]. Deze is gedeclareerd in het bestand Pwm_Externals.h en moet door de gebruiker worden geleverd [SWS_Pwm_00105].

De aanroep vindt plaats afhankelijk van de laatste aanroep van Pwm_EnableNotification voor het desbetreffende kanaal [SWS_Pwm_00105]. De triggerende gebeurtenissen baseren zich op de waarden van Pwm_EdgeNotificationType, die stijgende (PWM_RISING_EDGE), dalende (PWM_FALLING_EDGE) of beide signaalflanken (PWM_BOTH_EDGES) onderscheidt [SWS_Pwm_00109]. Voorafgaand aan de signaalgeneratie en gebeurtenisnotificatie moet de PWM-module via Pwm_Init met een hardware-afhankelijke Pwm_ConfigType-structuur zijn geïnitialiseerd [SWS_Pwm_00095], [SWS_Pwm_00111].

Wat betreft gelijktijdigheid is de re-entrantie van de callback-functie expliciet gedefinieerd als gebruikersafhankelijk (PWM user implementation dependant) [SWS_Pwm_00105]. De exacte uitvoeringscontext (bijvoorbeeld of de aanroep direct in een interrupt-service-routine of in de taskcontext plaatsvindt) hangt vermoedelijk af van de onderliggende driverimplementatie (interpretatie). Vraag Q-327872e0e8fecb37 (open) Specifieke foutcodes, retourwaarden of gestandaardiseerde DET- of DEM-meldingen bestaan er voor deze notificatie-interface niet [SWS_Pwm_00105].

De functie IoHwAb_Pwm_NotifyReadyForPower (in de syntaxis gedeclareerd als IoHwAb_Pwm_NotifyReadyForPowerState<#Mode>) wordt via de header IoHwAb_Pwm.h beschikbaar gesteld en dient als callback-interface in het AUTOSAR-powermanagement [SWS_Pwm_00198].

Met betrekking tot gebruik, interface-eigenschappen en systeemsamenspel gelden de volgende bindende voorschriften:

• Gebruik en aanroepcontext: De interface heeft de service-ID 0x60 en wordt synchroon uitgevoerd [SWS_Pwm_00198]. Deze moet verplicht door de PWM-driver worden aangeroepen zodra de voorbereiding aan apparaatzijde voor een aangevraagde vermogenstoestand (Power State) van een modus met succes is voltooid [SWS_Pwm_00198].
• Parameters en retourwaarden: De functiesignatuur definieert noch ingangs-, ingangs-/uitgangs- noch uitgangsparameters en heeft geen retourwaarde (void) [SWS_Pwm_00198]. Interpretatie: De toewijzing aan de betreffende vermogensmodus vloeit vermoedelijk direct voort uit de modusspecifieke functienaam in de broncode. Vraag Q-ab761160ed91de78 (open)
• Gelijktijdigheid en beperkingen: De functie is gespecificeerd als niet-re-entrant (Non Reentrant) [SWS_Pwm_00198]. Aanroepen mogen bijgevolg niet parallel of genest binnen dezelfde drivercontext plaatsvinden.
• Samenspel: In het module-overschrijdende verloop signaleert de aanroep aan de bovenliggende I/O-hardware-abstractie dat de driverfase gereed is voor de overgang naar de gewenste bedrijfstoestand [SWS_Pwm_00198].

In de specificatiebronnen zijn voor deze functie geen specifieke foutcodes en geen meldingen aan DET of DEM voorzien [SWS_Pwm_00198].

Het enumeratietype Pwm_OutputStateType definieert de uitgangstoestand van een PWM-kanaal binnen de Classic AUTOSAR-driver Pwm [SWS_Pwm_00108]. De typedefinitie wordt via het headerbestand Pwm.h beschikbaar gesteld voor aanroepende software-eenheden en drivertoepassingen [SWS_Pwm_00108].

Het waardebereik van deze enumeratie onderscheidt twee eenduidig vastgelegde toestanden van het kanaal [SWS_Pwm_00108]:

• PWM_HIGH (numerieke waarde 0x00): Geeft aan dat het desbetreffende PWM-kanaal zich in de High-toestand bevindt [SWS_Pwm_00108].
• PWM_LOW (numerieke waarde 0x01): Geeft aan dat het desbetreffende PWM-kanaal zich in de Low-toestand bevindt [SWS_Pwm_00108].

Met betrekking tot aanroepcontext en gebruiksdoel definieert het element zelf als type geen interfacefuncties [SWS_Pwm_00108]. Interpretatie: De waarden dienen vermoedelijk typisch als parameters of retourwaarden bij API-functies van de module om de actuele of gewenste logische niveautoestand van een kanaal te signaleren. Vraag Q-9c142d658ab7fcfd (open)

Aangezien het om een elementaire typedefinitie gaat, bestaan er in de specificatieomvang geen specifieke foutafhandelingen met betrekking tot DET of DEM en geen eisen aan re-entrantie of synchrone uitvoering [SWS_Pwm_00108].

Het enumeratietype Pwm_PowerStateRequestResultType levert het resultaat van verzoeken tot toestandsverandering van de energiebeheermodus (Power State Transitions) in de PWM-driver conform [SWS_Pwm_00165]. De typedefinitie is beschikbaar via de header Pwm.h [SWS_Pwm_00165].

Het type representeert zowel de succesvolle overgang als specifieke foutcondities [SWS_Pwm_00165]:

• PWM_SERVICE_ACCEPTED (0x00): De aangevraagde wisseling van de power-state is succesvol uitgevoerd [SWS_Pwm_00165].
• PWM_NOT_INIT (0x01): De PWM-module is nog niet geïnitialiseerd [SWS_Pwm_00165].
• PWM_SEQUENCE_ERROR (0x02): De aanroepsequentie van de API is niet toegestaan [SWS_Pwm_00165].
• PWM_HW_FAILURE (0x03): Een hardwarefout verhindert het aannemen van de vereiste energietoestand [SWS_Pwm_00165].
• PWM_POWER_STATE_NOT_SUPP (0x04): De aangevraagde toestand wordt niet ondersteund door de module [SWS_Pwm_00165].
• PWM_TRANS_NOT_POSSIBLE (0x05): Een directe toestandsovergang is niet mogelijk of het hardware-randapparaat is nog bezig [SWS_Pwm_00165].

Aanroepers moeten het resultaat evalueren om vast te stellen of een toestandsverandering direct van kracht is geworden. Interpretatie: Het type fungeert vermoedelijk typisch als retourwaarde of uitgangsparameter van overeenkomstige power-managementfuncties om bovenliggende modules te informeren over overgangsconflicten of hardware-blokkades. Vraag Q-fd06829e5c030906 (open)

Het opsommingstype Pwm_PowerStateType dient in de module PWM ter beschrijving van energietoestanden [SWS_Pwm_00197]. Het representeert ofwel de momenteel actieve bedrijfstoestand ofwel een nieuw als doel opgegeven vermogenstoestand van de driver [SWS_Pwm_00197]. Dit datatype wordt beschikbaar gesteld via het headerbestand Pwm.h [SWS_Pwm_00197].

De specificatie definieert voor de opsomming de volgende waarden en waardebereiken [SWS_Pwm_00197]:

• PWM_FULL_POWER (waarde 0x00): Markeert de toestand van vol vermogen (“Full Power”) [SWS_Pwm_00197].
• Waardebereik 1..255: Definieert getrapte vermogensmodi met stapsgewijs afnemend energieverbruik (“power modes with decreasing power consumptions”) [SWS_Pwm_00197].

Met betrekking tot de gebruikscontext fungeert het type vermoedelijk als overdrachtsparameter bij het aanvragen van een energiebesparingsmodus alsook als retourwaarde bij statusopvragingen, aangezien het type zowel actieve als doel-toestanden afbeeldt [SWS_Pwm_00197]. Vraag Q-f0423f8b958d7e91 (open) Concrete API-functies, foutafhandelingen (DET/DEM) en gelijktijdigheidsbeperkingen zijn voor dit datatype in het voorliggende specificatie-uittreksel niet opgenomen en derhalve weggelaten [SWS_Pwm_00197].