PWM Driver (Pwm)

Die synchrone Funktion Pwm_Init dient als zentraler Dienst zur Initialisierung des gesamten PWM-Treibers ([SWS_Pwm_00095]). Sie wird über die Header-Datei Pwm.h bereitgestellt und besitzt die hexadezimale Service-ID 0x00 ([SWS_Pwm_00095]). Als einziger Eingangsparameter wird ConfigPtr übergeben, der als Zeiger auf den treiberspezifischen Konfigurationssatz vom Typ Pwm_ConfigType fungiert ([SWS_Pwm_00095]). Die Schnittstelle besitzt keinen Rückgabewert und verwendet weder Ausgabeparameter noch Ein-/Ausgabeparameter ([SWS_Pwm_00095]).

In Bezug auf das Laufzeitverhalten ist Pwm_Init synchron und als nicht reentrant (Non Reentrant) spezifiziert ([SWS_Pwm_00095]). Ein gleichzeitiger oder unterbrechender Aufruf dieser Funktion aus mehreren Threads, Tasks oder Unterbrechungsroutinen ist daher strikt unzulässig. Die Ausführung dürfte typischerweise einmalig während des Systemstarts in der Initialisierungsphase des Steuergeräts vor der weiteren Nutzung der PWM-Kanäle erfolgen. Frage Q-ff3f1cf769dfed70 (offen)

Zur Absicherung der zulässigen Aufrufreihenfolge überwacht das Modul seinen Zustand: Wird der Dienst Pwm_Init aufgerufen, wenn der PWM-Treiber bereits initialisiert ist, meldet das Modul den Entwicklungsfehler PWM_E_ALREADY_INITIALIZED mit der Kennung 0x14 ([SWS_Pwm_50002]). Eine wiederholte Initialisierung wird somit als Fehler gewertet.

Verwendung und Signatur

Die Funktion Pwm_DeInit dient als Service zur Deinitialisierung des PWM-Treibers ([SWS_Pwm_00096]). Sie wird über die Header-Datei Pwm.h bereitgestellt und führt die Service-ID 0x01 ([SWS_Pwm_00096]). Die Schnittstelle besitzt die Signatur void Pwm_DeInit(void), nimmt weder Eingangs- noch Ausgangsparameter entgegen und liefert keinen Rückgabewert an den Aufrufer ([SWS_Pwm_00096]).

Der Aufruf von Pwm_DeInit wird synchron ausgeführt ([SWS_Pwm_00096]). Der aufrufende Kontrollfluss verbleibt somit in der Funktion, bis die Deinitialisierungsschritte des PWM-Moduls abgeschlossen sind.

Nebenläufigkeit und Einschränkungen

Für die Ausführung gelten folgende Randbedingungen bezüglich Nebenläufigkeit:

• Nicht reentrant: Der Dienst ist als nicht reentrant spezifiziert ([SWS_Pwm_00096]). Ein gleichzeitiger oder unterbrechender Aufruf aus mehreren Threads, Tasks oder ISRs ist unzulässig.
• Aufrufkontext: Aufgrund der synchronen Semantik und der fehlenden Reentranz dürfte der Aufruf typischerweise im Rahmen einer kontrollierten Shutdown-Phase auf Task-Ebene erfolgen. Frage Q-f1afc58637cba5cf (offen)

Fehlerbehandlung

In der Spezifikation von Pwm_DeInit sind weder Rückgabewerte noch spezifische Fehlercodes definiert ([SWS_Pwm_00096]). Etwaige Laufzeit- oder Zustandsfehler dürften vermutlich über modulinterne Überwachungsmechanismen wie die Entwicklungsschnittstelle (DET) protokolliert oder abgefangen werden, da eine direkte Fehlerrückmeldung über die Funktionsschnittstelle nicht vorgesehen ist. Frage (offen)

Die Funktion Pwm_DisableNotification dient dem Deaktivieren der Flankenbenachrichtigung (Signal Edge Notification) eines bestimmten PWM-Kanals [SWS_Pwm_91003]. Die Funktionsdeklaration und zugehörigen Typdefinitionen werden über die Header-Datei Pwm.h zur Verfügung gestellt [SWS_Pwm_91003].

Parameter und Rückgabewert

Die Schnittstelle besitzt die Service-ID 0x06 und weist folgende Signaturmerkmale auf [SWS_Pwm_91003]:

• ChannelNumber (in): Numerischer Bezeichner des zu konfigurierenden PWM-Kanals vom Typ Pwm_ChannelType [SWS_Pwm_91003].

Es existieren weder Ein-/Ausgabeparameter (inout) noch reine Ausgabeparameter (out) [SWS_Pwm_91003]. Die Funktion liefert keinen Rückgabewert (void) an den Aufrufer zurück [SWS_Pwm_91003].

Synchronisationsverhalten und Nebenläufigkeit

Der Aufruf von Pwm_DisableNotification arbeitet asynchron [SWS_Pwm_91003]. In Bezug auf das Multithreading-Verhalten ist der Dienst reentrant, solange unterschiedliche Kanalnummern angesprochen werden [SWS_Pwm_91003].

Interpretation: Da die Reentranz explizit auf unterschiedliche Kanäle beschränkt ist, ist die Funktion für denselben PWM-Kanal vermutlich nicht reentrant [SWS_Pwm_91003]. Frage Q-005e97fd25679da7 (offen) Zeitgleiche Aufrufe für den identischen Kanal dürften daher auf Anruferseite gegeneinander synchronisiert werden müssen.

Verwendung

Die Funktion Pwm_EnableNotification dient der Aktivierung von Signalflanken-Benachrichtigungen für einen bestimmten PWM-Kanal gemäß dem übergebenen Benachrichtigungsparameter [SWS_Pwm_91004]. Der Dienst wird über die Header-Datei Pwm.h bereitgestellt, besitzt die Service-ID 0x07 und liefert keinen Rückgabewert (void) an den Aufrufer zurück [SWS_Pwm_91004].

Beim Aufruf der Schnittstelle sind zwei obligatorische Eingangsparameter zu übergeben [SWS_Pwm_91004]:

• ChannelNumber (vom Typ Pwm_ChannelType): Numerische Kennung des anzusprechenden PWM-Kanals [SWS_Pwm_91004].
• Notification (vom Typ Pwm_EdgeNotificationType): Definiert die Art der Flanken-Benachrichtigung mit den zulässigen Werten PWM_RISING_EDGE, PWM_FALLING_EDGE oder PWM_BOTH_EDGES [SWS_Pwm_91004].

Semantik und Nebenläufigkeit

Die Ausführung des Dienstes ist als asynchron spezifiziert [SWS_Pwm_91004]. In Bezug auf Nebenläufigkeit ist Pwm_EnableNotification reentrant für unterschiedliche Kanalnummern ausgelegt [SWS_Pwm_91004]. Bei einem gleichzeitigen oder unterbrechenden Zugriff auf denselben PWM-Kanal ist der Dienst vermutlich nicht reentrant; ein solcher Aufruf muss daher aufruferseitig abgesichert werden. Frage Q-73309ed8589161a3 (offen)

Fehlerbehandlung und Randbedingungen

Der Spezifikationsauszug definiert für diese Funktion weder spezifische Rückgabewerte noch Fehlermeldungen für das Development Error Tracer (DET) oder das Diagnostic Event Manager (DEM) [SWS_Pwm_91004]. Ebenso fehlen Vorgaben zu zulässigen Aufrufkontexten oder taskbezogenen Reihenfolgen. Da keine Vorbedingungen genannt werden, dürfte der Funktionsaufruf erst nach einer erfolgreichen Initialisierung des PWM-Treibers zulässig sein. Frage Q-7f428f59a20175c2 (offen)

Die synchrone Funktion Pwm_SetPowerState versetzt das PWM-Modul in einen zuvor vorbereiteten Zustand aus einer vorkonfigurierten Auswahl von Power-States [SWS_Pwm_00166]. Die Deklaration ist über den Header Pwm.h verfügbar [SWS_Pwm_00166].

Verwendung und Rückgabewerte

Die Funktion nimmt keine Eingabeparameter entgegen und übergibt das detaillierte Ergebnis über den Zeigerparameter Result vom Typ Pwm_PowerStateRequestResultType* [SWS_Pwm_00166]:

• Konnte der Modus erfolgreich gewechselt werden, liefert die Funktion E_OK zurück und setzt Result auf PWM_SERVICE_ACCEPTED [SWS_Pwm_00166].
• Wird die Anforderung zurückgewiesen, gibt der Aufruf E_NOT_OK zurück [SWS_Pwm_00166].

Fehlerbehandlung

Im Fehlerfall (Rückgabewert E_NOT_OK) spezifiziert Result die Ursache des Scheiterns [SWS_Pwm_00166]:

• PWM_NOT_INIT: Das PWM-Modul ist nicht initialisiert [SWS_Pwm_00166].
• PWM_SEQUENCE_ERROR: Es liegt eine unzulässige API-Aufrufsequenz vor [SWS_Pwm_00166].
• PWM_HW_FAILURE: Ein Fehler im Hardwaremodul verhindert den Eintritt in den angeforderten Power-State [SWS_Pwm_00166].

Nebenläufigkeit und Randbedingungen

Pwm_SetPowerState ist nicht reentrant (Non Reentrant) und erfordert zur Vermeidung eines Sequenzfehlers, dass der Zielzustand vor dem Aufruf vorbereitet wurde [SWS_Pwm_00166].

Verwendung

Die synchrone Funktion Pwm_PreparePowerState leitet den erforderlichen Vorbereitungsprozess ein, damit das PWM-Hardwaremodul in einen angeforderten Energiezustand wechseln kann [SWS_Pwm_00183]. Der gewünschte Zielzustand wird über den Parameter PowerState übergeben, während das detaillierte Ergebnis über den Ausgabepointer Result bereitgestellt wird [SWS_Pwm_00183]. Wurde die Vorbereitung erfolgreich angestoßen, gibt die Funktion E_OK zurück und setzt Result auf PWM_SERVICE_ACCEPTED [SWS_Pwm_00183].

Fehlerbehandlung

Wird der Dienst abgewiesen, liefert die Funktion E_NOT_OK und meldet die spezifische Ursache über Result [SWS_Pwm_00183]:

• PWM_NOT_INIT: Das PWM-Modul ist nicht initialisiert [SWS_Pwm_00183].
• PWM_SEQUENCE_ERROR: Unzulässige Aufrufsequenz, da der aktuelle Energiezustand bereits dem Zielzustand entspricht [SWS_Pwm_00183].
• PWM_POWER_STATE_NOT_SUPP: Das Modul unterstützt den angeforderten Energiezustand nicht [SWS_Pwm_00183].
• PWM_TRANS_NOT_POSSIBLE: Ein direkter Übergang ist nicht möglich oder die Hardware-Peripherie ist noch beschäftigt [SWS_Pwm_00183].

Nebenläufigkeit und Zusammenspiel

Die Funktion ist nicht reentrant (Non Reentrant) und darf daher für dasselbe Modul nicht nebenläufig aufgerufen werden [SWS_Pwm_00183]. Nach erfolgreicher Vorbereitung durch Pwm_PreparePowerState müssen nachgelagerte, nicht unmittelbar wirksame Aktionen ausgeführt werden, um den Energiezustandsübergang final abzuschließen [SWS_Pwm_00190].

Die Schnittstelle Pwm_Main_PowerTransitionManager dient der zyklischen Überwachung von Energiezustandsübergängen (Power State Transitions) des PWM-Treibers gemäß [SWS_Pwm_00189]. Sie besitzt die Service-ID 0x0d, nimmt keine Übergabeparameter entgegen und liefert keinen Rückgabewert (Signatur void Pwm_Main_PowerTransitionManager(void)).

Im Rahmen ihrer zyklischen Ausführung überprüft die Funktion die Betriebsbereitschaft des Moduls für den jeweiligen Energiezustand. Sobald die Bereitschaft vorliegt, löst sie die Benachrichtigungs-Callbacks IoHwAb_Pwm_NotifyReadyForPowerState<Mode> aus, welche über den Konfigurationsparameter PwmPowerStateReadyCbkRef referenziert werden [SWS_Pwm_00189].

Die Funktion ist für einen zyklischen Aufrufkontext vorgesehen und wird über die Header-Datei SchM_Pwm.h bereitgestellt. Infolgedessen dürfte der periodische Aufruf typischerweise im Kontext des BSW-Schedulers (Schedule Manager) erfolgen [SWS_Pwm_00189]. Frage Q-b9b0431e7ccbca88 (offen) Spezifische Fehlercodes, Mechanismen zur Fehlerbehandlung über DET oder DEM sowie besondere Reentranz-Bedingungen sind in der Modulspezifikation für diesen Service nicht definiert.

Die kanalbezogene Benachrichtigungsfunktion Pwm_Notification_<#Channel> wird vom PWM-Modul synchron aufgerufen, sobald das für den jeweiligen Kanal konfigurierte Flankenereignis eintritt [SWS_Pwm_00105]. Die Funktion besitzt die Signatur void Pwm_Notification_<#Channel>(void), nimmt keine Übergabeparameter entgegen und liefert keinen Rückgabewert [SWS_Pwm_00105]. Sie ist in der Datei Pwm_Externals.h deklariert und muss vom Anwender bereitgestellt werden [SWS_Pwm_00105].

Der Aufruf erfolgt in Abhängigkeit vom letzten Aufruf von Pwm_EnableNotification für den betreffenden Kanal [SWS_Pwm_00105]. Die auslösenden Ereignisse orientieren sich an den Werten von Pwm_EdgeNotificationType, welcher steigende (PWM_RISING_EDGE), fallende (PWM_FALLING_EDGE) oder beide Signalflanken (PWM_BOTH_EDGES) unterscheidet [SWS_Pwm_00109]. Vor der Signalerzeugung und Ereignisbenachrichtigung muss das PWM-Modul über Pwm_Init mit einer hardwareabhängigen Pwm_ConfigType-Struktur initialisiert worden sein [SWS_Pwm_00095], [SWS_Pwm_00111].

Hinsichtlich der Nebenläufigkeit ist die Reentranz der Callback-Funktion explizit als anwenderabhängig definiert (PWM user implementation dependant) [SWS_Pwm_00105]. Der genaue Ausführungskontext (etwa ob der Aufruf direkt in einer Interrupt-Service-Routine oder im Task-Kontext erfolgt) dürfte von der zugrunde liegenden Treiberimplementierung abhängen (Interpretation). Frage Q-327872e0e8fecb37 (offen) Spezifische Fehlercodes, Rückgabewerte oder standardisierte DET- bzw. DEM-Meldungen existieren für diese Benachrichtigungsschnittstelle nicht [SWS_Pwm_00105].

Die Funktion IoHwAb_Pwm_NotifyReadyForPower (in der Syntax als IoHwAb_Pwm_NotifyReadyForPowerState<#Mode> deklariert) wird über den Header IoHwAb_Pwm.h bereitgestellt und dient als Callback-Schnittstelle im AUTOSAR-Powermanagement [SWS_Pwm_00198].

Hinsichtlich Verwendung, Schnittstelleneigenschaften und Systemzusammenspiel gelten die folgenden verbindlichen Vorgaben:

• Verwendung und Aufrufkontext: Die Schnittstelle besitzt die Service-ID 0x60 und wird synchron ausgeführt [SWS_Pwm_00198]. Sie ist zwingend vom PWM-Treiber aufzurufen, sobald die geräteseitige Vorbereitung für einen angeforderten Leistungszustand (Power State) eines Modus erfolgreich abgeschlossen wurde [SWS_Pwm_00198].
• Parameter und Rückgabewerte: Die Funktionssignatur definiert weder Eingangs-, Ein-/Ausgangs- noch Ausgangsparameter und besitzt keinen Rückgabewert (void) [SWS_Pwm_00198]. Interpretation: Die Zuordnung zum jeweiligen Leistungsmodus dürfte sich unmittelbar aus dem modusspezifischen Funktionsnamen im Quellcode ableiten. Frage Q-ab761160ed91de78 (offen)
• Nebenläufigkeit und Einschränkungen: Die Funktion ist als nicht-reentrant (Non Reentrant) spezifiziert [SWS_Pwm_00198]. Aufrufe dürfen folglich nicht parallel oder verschachtelt innerhalb desselben Treiberkontexts erfolgen.
• Zusammenspiel: Im modulübergreifenden Ablauf signalisiert der Aufruf der übergeordneten I/O-Hardware-Abstraktion, dass die Treiberstufe bereit für den Wechsel in den gewünschten Betriebszustand ist [SWS_Pwm_00198].

In den Spezifikationsquellen sind für diese Funktion keine spezifischen Fehlercodes sowie keine Meldungen an DET oder DEM vorgesehen [SWS_Pwm_00198].

Der Enumerationstyp Pwm_OutputStateType definiert den Ausgangszustand eines PWM-Kanals innerhalb des Classic-AUTOSAR-Treibers Pwm [SWS_Pwm_00108]. Die Typdefinition wird über die Header-Datei Pwm.h für aufrufende Softwareeinheiten und Treiberanwendungen bereitgestellt [SWS_Pwm_00108].

Der Wertebereich dieser Enumeration unterscheidet zwei eindeutig festgelegte Zustände des Kanals [SWS_Pwm_00108]:

• PWM_HIGH (numerischer Wert 0x00): Kennzeichnet, dass sich der betreffende PWM-Kanal im High-Zustand befindet [SWS_Pwm_00108].
• PWM_LOW (numerischer Wert 0x01): Kennzeichnet, dass sich der betreffende PWM-Kanal im Low-Zustand befindet [SWS_Pwm_00108].

In Bezug auf Aufrufkontext und Verwendungszweck definiert das Element selbst als Typ keine Schnittstellenfunktionen [SWS_Pwm_00108]. Interpretation: Die Werte dürften typischerweise als Parameter oder Rückgabewerte bei API-Funktionen des Moduls dienen, um den aktuellen oder gewünschten logischen Pegelzustand eines Kanals zu signalisieren. Frage Q-9c142d658ab7fcfd (offen)

Da es sich um eine elementare Typdefinition handelt, existieren keine spezifischen Fehlerbehandlungen bezüglich DET oder DEM sowie keine Anforderungen an Reentranz oder synchrone Ausführung im Spezifikationsumfang [SWS_Pwm_00108].

Der Enumerationstyp Pwm_PowerStateRequestResultType liefert das Ergebnis von Anforderungen zur Zustandsänderung des Energieverwaltungsmodus (Power State Transitions) im PWM-Treiber gemäß [SWS_Pwm_00165]. Die Typdefinition steht über den Header Pwm.h zur Verfügung [SWS_Pwm_00165].

Der Typ bildet sowohl den erfolgreichen Übergang als auch spezifische Fehlerbedingungen ab [SWS_Pwm_00165]:

• PWM_SERVICE_ACCEPTED (0x00): Der angeforderte Wechsel des Power-States wurde erfolgreich ausgeführt [SWS_Pwm_00165].
• PWM_NOT_INIT (0x01): Das PWM-Modul ist noch nicht initialisiert [SWS_Pwm_00165].
• PWM_SEQUENCE_ERROR (0x02): Die Aufrufsequenz der API ist unzulässig [SWS_Pwm_00165].
• PWM_HW_FAILURE (0x03): Ein Hardwarefehler verhindert das Einnehmen des geforderten Energiezustands [SWS_Pwm_00165].
• PWM_POWER_STATE_NOT_SUPP (0x04): Der angeforderte Zustand wird vom Modul nicht unterstützt [SWS_Pwm_00165].
• PWM_TRANS_NOT_POSSIBLE (0x05): Ein direkter Zustandsübergang ist nicht möglich oder die Hardware-Peripherie ist noch beschäftigt [SWS_Pwm_00165].

Aufrufer müssen das Resultat auswerten, um festzustellen, ob ein Zustandswechsel unmittelbar wirksam wurde. Interpretation: Der Typ dürfte typischerweise als Rückgabewert oder Ausgabeparameter entsprechender Power-Management-Funktionen fungieren, um übergeordnete Module über Übergangskonflikte oder Hardware-Blockaden zu informieren. Frage Q-fd06829e5c030906 (offen)

Der Aufzählungstyp Pwm_PowerStateType dient im Modul PWM zur Beschreibung von Energiezuständen [SWS_Pwm_00197]. Er repräsentiert entweder den gegenwärtig aktiven Betriebszustand oder einen neu als Ziel vorgegebenen Leistungszustand des Treibers [SWS_Pwm_00197]. Bereitgestellt wird dieser Datentyp über die Header-Datei Pwm.h [SWS_Pwm_00197].

Die Spezifikation definiert für die Aufzählung folgende Werte und Wertebereiche [SWS_Pwm_00197]:

• PWM_FULL_POWER (Wert 0x00): Kennzeichnet den Zustand voller Leistung („Full Power“) [SWS_Pwm_00197].
• Wertebereich 1..255: Definiert abgestufte Leistungsmodi mit schrittweise abnehmendem Energieverbrauch („power modes with decreasing power consumptions“) [SWS_Pwm_00197].

Hinsichtlich des Verwendungskontexts dürfte der Typ als Übergabeparameter bei der Anforderung eines Energiesparmodus sowie als Rückgabewert bei Statusabfragen fungieren, da der Typ sowohl aktive als auch Ziel-Zustände abbildet [SWS_Pwm_00197]. Frage Q-f0423f8b958d7e91 (offen) Konkrete API-Funktionen, Fehlerbehandlungen (DET/DEM) sowie Nebenläufigkeitseinschränkungen sind für diesen Datentyp im vorliegenden Spezifikationsauszug nicht enthalten und daher weggelassen [SWS_Pwm_00197].