PWM Driver (Pwm)

As an MCAL module, the PWM driver controls the pulse-width-modulated outputs of the microcontroller on a per-channel basis, accessing its registers directly for this purpose. According to Pwm_Init, Pwm Users set the duty cycle and, for channels with a variable period, also the period. They can switch outputs to the idle state and enable or disable edge notifications [SWS_Pwm_91000]. Optionally, the driver manages two-phase power state transitions via prepare and set. It reports errors such as missing initialization or invalid channels when error detection is active and then performs no action [SWS_Pwm_00201].

more ›

The PWM driver is an MCAL module and controls the pulse-width-modulated outputs of the microcontroller via its registers. Therefore, it does not require interfaces of lower-layer modules (SWS PWM Driver p. 44). It is initialized synchronously with Pwm_Init and a pointer to the configuration set [SWS_Pwm_00095], which the ECU State Manager calls as an optional initialization interface (SWS EcuM p. 152). It is typically used by the IoHwAb, for example via a power stage driver (SWS IoHwAb p. 37).

Context diagram: EcuM initializes the driver, the Pwm User operates it, and the driver reports notifications and errors back. Sources: [SWS_Pwm_00105], [SWS_Pwm_00198], [SWS_Pwm_00104]

Control is performed via a 16-bit duty cycle, where 0x8000 represents 100% (SWS PWM Driver p. 18). The most important services:

• Pwm_SetDutyCycle changes the duty cycle [SWS_Pwm_91000]. At 0% and 100%, it sets a static level depending on the polarity.
• Pwm_SetPeriodAndDuty additionally changes the period, but only for channels of class PWM_VARIABLE_PERIOD [SWS_Pwm_00110].
• Pwm_SetOutputToIdle immediately switches to the idle level [SWS_Pwm_91002].
• Pwm_GetOutputState reads the internal level [SWS_Pwm_00100].

State diagram: A channel transitions via API between modulation, static level, and idle state. Sources: [SWS_Pwm_91000], [SWS_Pwm_91001], SWS PWM Driver p. 31

Edge notifications are enabled per channel using Pwm_EnableNotification [SWS_Pwm_91004] and arrive as Pwm_Notification_<#Channel> at the Pwm User [SWS_Pwm_00105]. Optionally, the driver also manages power states in two phases. Pwm_PreparePowerState starts the preparation [SWS_Pwm_00183], which the cyclic Pwm_Main_PowerTransitionManager concludes [SWS_Pwm_00189]. After that, Pwm_SetPowerState sets the state [SWS_Pwm_00166].

With active error detection, the functions report errors such as PWM_E_UNINIT, PWM_E_PARAM_CHANNEL, or PWM_E_PERIOD_UNCHANGEABLE [SWS_Pwm_00201] and return without effect (SWS PWM Driver p. 44). In these cases, Pwm_GetOutputState returns PWM_LOW [SWS_Pwm_30051]. If Pwm_SetPowerState is called while the driver is still in use, the runtime error PWM_E_NOT_DISENGAGED [SWS_Pwm_00202] occurs.

more ›

Role in the MCAL: Driver between PWM unit and Pwm User

The PWM driver encapsulates the pulse-width-modulated outputs of the microcontroller. As a module of the MCAL layer, it accesses the microcontroller registers directly and therefore does not require interfaces of lower-layer modules (SWS PWM Driver p. 44). For the same reason, it provides no callbacks for lower layers (SWS PWM Driver p. 40) and also offers no service interfaces (SWS PWM Driver p. 44). Its services are available via Pwm.h, such as Pwm_Init [SWS_Pwm_00095], Pwm_SetDutyCycle [SWS_Pwm_91000], and Pwm_GetOutputState [SWS_Pwm_00100]. It imports the standard types Std_ReturnType and Std_VersionInfoType from Std_Types.h [SWS_Pwm_00094].

The ECU State Manager lists Pwm_Init among its optional initialization interfaces (SWS EcuM p. 152). In the power stage use case, an IoHwAb power stage driver calls services of PWM, DIO, and SPI, thereby adjusting voltages and frequencies, among other things (SWS IoHwAb p. 37). In the reverse direction, the driver calls two types of functions: the channel-specific notifications Pwm_Notification_<#Channel> [SWS_Pwm_00105] and, in power management, IoHwAb_Pwm_NotifyReadyForPowerState<#Mode> [SWS_Pwm_00198]. It optionally reports development errors via Det_ReportError [SWS_Pwm_00104]. If the hardware offers different mechanisms for different channels, this is not abstracted via vendor-specific API infixes, but via the channel number (TPS BSWMDT p. 122).

Context diagram: The Pwm driver is initialized by EcuM and operated by the Pwm User. It is called cyclically by the scheduler, reports notifications to the Pwm User and errors to DET, and controls the PWM unit via its registers. Sources: [SWS_Pwm_00104], [SWS_Pwm_00105], [SWS_Pwm_00189], [SWS_Pwm_00198], SWS EcuM p. 152, SWS IoHwAb p. 37, RS PWM Driver p. 14

Signal model: Period, duty cycle, polarity, and channel classes

A channel is addressed via the numerical identifier Pwm_ChannelType [SWS_Pwm_00106]. The period is of type Pwm_PeriodType, an implementation-specific type with 8 to 32 bits [SWS_Pwm_00107]. Three concepts define the signal (SWS PWM Driver p. 9):

• The polarity defines the starting level of each period.
• The duty cycle specifies the proportion of this starting level in the period.
• The idle state is the initial state after Pwm_SetOutputToIdle or Pwm_DeInit.

The diagram for signal description compares both polarities PWM_HIGH and PWM_LOW (SWS PWM Driver p. 7).

The duty cycle is a 16-bit value. 0x0000 represents 0% and 0x8000 represents 100%. As an implementation aid, the specification mentions AbsoluteDutyCycle = ((uint32)AbsolutePeriodTime * RelativeDutyCycle) >> 15; (SWS PWM Driver p. 18). Accordingly, Pwm_SetDutyCycle and Pwm_SetPeriodAndDuty limit the parameter DutyCycle to Min=0x0000 and Max=0x8000 [SWS_Pwm_91000] [SWS_Pwm_91001].

The channel class Pwm_ChannelClassType defines what a channel may change at runtime [SWS_Pwm_00110]:

• PWM_VARIABLE_PERIOD: Period and duty cycle can be changed.
• PWM_FIXED_PERIOD: Only the duty cycle can be changed.
• PWM_FIXED_PERIOD_SHIFTED: Fixed, shifted period that cannot be changed; only available if supported by hardware.

The diagram for the shifted period shows channels with the same period whose period start is offset by a fixed time in each case (SWS PWM Driver p. 23).

Lifecycle and signal control: from Pwm_Init to idle state

Pwm_Init is synchronous and non-reentrant. With ConfigPtr, the function receives a pointer to the configuration set [SWS_Pwm_00095]. Its type Pwm_ConfigType contains hardware-specific content [SWS_Pwm_00111]. According to the initialization diagram, the outputs are subsequently in low, high, or modulation state depending on the configuration. Notifications occur only after the first call to Pwm_EnableNotification (SWS PWM Driver p. 46). If Pwm_Init is called again on an already initialized driver, the development error PWM_E_ALREADY_INITIALIZED must be reported [SWS_Pwm_50002].

Pwm_DeInit is likewise synchronous and non-reentrant [SWS_Pwm_00096]. The function de-initializes the module, sets the outputs to the idle state, and disables PWM interrupts as well as edge notifications. It can be enabled and disabled via PwmDeInitApi (SWS PWM Driver p. 27). Interpretation: After that, the module should again be considered uninitialized, so that a renewed call to Pwm_Init is permissible. Question Q-a892974ddbe644e0 (open)

State diagram: Lifecycle of the module with initialization, de-initialization, and errors in case of incorrect call sequence. The return to the “uninitialized” state after Pwm_DeInit is an interpretation. Sources: [SWS_Pwm_00095], [SWS_Pwm_00096], [SWS_Pwm_50002], [SWS_Pwm_20002], [SWS_Pwm_30051], SWS PWM Driver p. 27

During operation, Pwm_SetDutyCycle sets the duty cycle of a channel [SWS_Pwm_91000]. At 0% and 100%, the output is set statically (SWS PWM Driver p. 28):

• At 0%, the level is inverse to the configured polarity.
• At 100%, the level corresponds to the polarity.
• For values in between, modulation takes place according to period, duty cycle, and polarity.

According to the diagram, the driver applies the new duty cycle at the end of the current period if the implementation supports this, otherwise immediately (SWS PWM Driver p. 37).

Pwm_SetPeriodAndDuty sets period and duty cycle together [SWS_Pwm_91001]. Three rules apply here (SWS PWM Driver p. 30):

• The period is updated at the end of the period if the implementation supports this and it is configured via PwmPeriodUpdatedEndperiod.
• Glitches at the output must be suppressed.
• The duty cycle is provided so that frequency and duty cycle match each other.

Activity diagram: Processing of Pwm_SetDutyCycle and Pwm_SetPeriodAndDuty with verification of channel class and special handling of 0% and 100%. Sources: [SWS_Pwm_40002], SWS PWM Driver p. 28, SWS PWM Driver p. 30, SWS PWM Driver p. 44

Pwm_SetOutputToIdle immediately sets the output to the configured idle state [SWS_Pwm_91002]. Channels with variable period are subsequently re-enabled via Pwm_SetPeriodAndDuty (SWS PWM Driver p. 31). The diagram “Setting Pwm output to idle” shows precisely this sequence (SWS PWM Driver p. 50). Pwm_GetOutputState synchronously reads the internal output state as PWM_HIGH or PWM_LOW [SWS_Pwm_00100] [SWS_Pwm_00108]. A diagram in the requirements specification locates the read value at the output of the PWM unit, i.e., before the port logic and not at the physical pin (RS PWM Driver p. 14).

State diagram: Output states of a channel (modulation, static level, idle) and the APIs switching between them. Sources: [SWS_Pwm_91000], [SWS_Pwm_91001], [SWS_Pwm_91002], SWS PWM Driver p. 28, SWS PWM Driver p. 31, SWS PWM Driver p. 46

Edge notifications per channel

With Pwm_EnableNotification, the Pwm User enables the notification for a channel. The parameter of type Pwm_EdgeNotificationType selects PWM_RISING_EDGE, PWM_FALLING_EDGE, or PWM_BOTH_EDGES [SWS_Pwm_91004] [SWS_Pwm_00109]. The function discards pending interrupts (SWS PWM Driver p. 35). Like Pwm_DisableNotification [SWS_Pwm_91003], it exists only if PwmNotificationSupported is enabled (SWS PWM Driver p. 34).

The driver calls the configured function Pwm_Notification_<#Channel> according to the last call to Pwm_EnableNotification or Pwm_DisableNotification. In doing so, it resets the corresponding interrupt flag (SWS PWM Driver p. 42). The callback has no parameters and is made known via Pwm_Externals.h. Whether it is reentrant depends on the implementation of the Pwm User [SWS_Pwm_00105].

Sequence diagram: Sequence from initialization through enabling and disabling of edge notification up to the absence of further callbacks. Sources: [SWS_Pwm_91004], [SWS_Pwm_91003], [SWS_Pwm_00105], SWS PWM Driver p. 52, SWS PWM Driver p. 42

Power states of the PWM peripheral

The control of power states is an optional feature. It is restricted to the PWM peripheral and requires that the application, mode management, and IoHwAb already satisfy the higher-level constraints (SWS PWM Driver p. 17). If PwmLowPowerStatesSupport is active, the four power state APIs are generated (SWS PWM Driver p. 16). Pwm_PowerStateType recognizes PWM_FULL_POWER (0x00) as well as the range 1..255 for states with decreasing consumption. In R20-11, the type is defined as an enumeration [SWS_Pwm_00197]. A later version, by contrast, lists it as a type derived from uint8 (SWS PWM Driver p. 25).

The power state transition proceeds in two phases:

1. Pwm_PreparePowerState starts the preparation and provides PWM_SERVICE_ACCEPTED or a rejection reason in the result parameter [SWS_Pwm_00183] [SWS_Pwm_00165]. Whatever cannot be concluded immediately is handled by the cyclically called Pwm_Main_PowerTransitionManager [SWS_Pwm_00189] [SWS_Pwm_00190]. Its call rate is variable, and it sends callbacks only in asynchronous mode (SWS PWM Driver p. 41). The driver reports the completed preparation with IoHwAb_Pwm_NotifyReadyForPowerState<#Mode> [SWS_Pwm_00198].
2. Pwm_SetPowerState sets the hardware into the prepared state [SWS_Pwm_00166]. Prerequisites such as setting all channels to IDLE and unregistering all notifications must already have been fulfilled by the responsible SWCs, such as the IoHwAb. The function does not execute implicit intermediate states (SWS PWM Driver p. 36).

State diagram: Two-phase power state transition with preparation, completion, and setting, as well as the sequence errors. Sources: [SWS_Pwm_00183], [SWS_Pwm_00166], [SWS_Pwm_00165], [SWS_Pwm_00190], SWS PWM Driver p. 39, SWS IoHwAb p. 61

Pwm_GetCurrentPowerState [SWS_Pwm_00177] returns the current state, Pwm_GetTargetPowerState [SWS_Pwm_00180] the requested one. As long as no transition is in progress, both match (SWS PWM Driver p. 38). The IoHwAb specification shows the interaction of BswM, RTE/SchM, IoHwAb, ADC, and PWM for the asynchronous case (SWS IoHwAb p. 60). In the synchronous case, the preparation is already completed when the preparation API returns (SWS IoHwAb p. 61).

Sequence diagram: Asynchronous transition to a low-power state, controlled by the IoHwAb. The sequence is simplified and ADC has been omitted. Sources: [SWS_Pwm_00183], [SWS_Pwm_00189], [SWS_Pwm_00198], [SWS_Pwm_00166], SWS IoHwAb p. 57, SWS IoHwAb p. 60

Configuration, channel containers, and concurrency

Mandatory parameters of a channel are the assigned hardware channel, default values for period and duty cycle, polarity, idle level, and channel class. Phase shift, reference channel, and microcontroller-specific properties are optional, provided the hardware offers them (SWS PWM Driver p. 25). In the configuration model, PwmChannelConfigSet contains at least one PwmChannel, and PwmDutycycleDefault is limited to 0 to 0x8000 (ECUC-Parameter p. 545). PwmChannelClass is mapped to Pwm_ChannelClassType. PwmChannelId is assigned to the symbolic name of the channel container (SWS PWM Driver p. 57).

Optional services are enabled and disabled via configuration: PwmSetOutputToIdle (SWS PWM Driver p. 31), PwmGetOutputState (SWS PWM Driver p. 33), as well as the above-mentioned PwmDeInitApi and PwmNotificationSupported.

The following applies to concurrency:

• Channel services such as Pwm_SetDutyCycle are reentrant for different channel numbers [SWS_Pwm_91000].
• The power state APIs are non-reentrant [SWS_Pwm_00183].
• Configurations with partition assignments that the implementation does not support must be rejected by the module [SWS_Pwm_00203].

The BSW Distribution Guide explains the reentrancy levels up to “multi-core reentrant” (BSW Distribution Guide p. 18).

Behavior in the event of an error

If development error detection is active, the functions report detected errors to the Default Error Tracer. They subsequently skip the requested function so that neither data nor hardware registers are corrupted (SWS PWM Driver p. 44). The error codes are [SWS_Pwm_00201]:

• PWM_E_INIT_FAILED (0x10)
• PWM_E_UNINIT (0x11) for calls prior to initialization [SWS_Pwm_20002]
• PWM_E_PARAM_CHANNEL (0x12) for invalid channels [SWS_Pwm_30002]
• PWM_E_PERIOD_UNCHANGEABLE (0x13) for period changes on channels with fixed period [SWS_Pwm_40002]
• PWM_E_ALREADY_INITIALIZED (0x14)
• PWM_E_PARAM_POINTER (0x15) for a NULL parameter to Pwm_GetVersionInfo

Pwm_GetOutputState must always return a value. Prior to initialization or for an invalid channel, this is PWM_LOW [SWS_Pwm_30051].

Activity diagram: General checks of the channel APIs with active development error detection, aborting without effect. Sources: [SWS_Pwm_20002], [SWS_Pwm_30002], [SWS_Pwm_30051], SWS PWM Driver p. 44

The power state APIs additionally report errors via Std_ReturnType and the result type Pwm_PowerStateRequestResultType. Possible values are PWM_NOT_INIT, PWM_SEQUENCE_ERROR, PWM_HW_FAILURE, PWM_POWER_STATE_NOT_SUPP, and PWM_TRANS_NOT_POSSIBLE [SWS_Pwm_00165]. For an unsupported state, PWM_E_POWER_STATE_NOT_SUPPORTED is additionally specified [SWS_Pwm_00174]; for a state that cannot be reached directly, PWM_E_TRANSITION_NOT_POSSIBLE [SWS_Pwm_00175].

If Pwm_SetPowerState is called even though channels are still outside IDLE or notifications are registered, the runtime error PWM_E_NOT_DISENGAGED (0x16) occurs [SWS_Pwm_00202] (SWS PWM Driver p. 20). Pwm_Main_PowerTransitionManager simply returns without initialization and deliberately does not report a development error. The reason: Cyclic tasks may run even before initialization is completed (SWS PWM Driver p. 41).

Further detailed evidence

• Lifecycle: [SWS_Pwm_00095] and [SWS_Pwm_00096] with the detailed obligations for de-initialization (SWS PWM Driver p. 27).
• Signal control: [SWS_Pwm_91000], [SWS_Pwm_91001], and [SWS_Pwm_91002], as well as the duty cycle scaling (SWS PWM Driver p. 18).
• Notifications: [SWS_Pwm_91004], [SWS_Pwm_91003], and [SWS_Pwm_00105] with the callback behavior (SWS PWM Driver p. 42).
• Power states: [SWS_Pwm_00183], [SWS_Pwm_00166], [SWS_Pwm_00189], and [SWS_Pwm_00198]; the “Background” section describes the concept (SWS PWM Driver p. 17).
• Errors: [SWS_Pwm_00201], [SWS_Pwm_00202], and [SWS_Pwm_30051], as well as parameter checking (SWS PWM Driver p. 44).
• Source situation: Many document citations originate from later versions (R23-11 to R25-11) or lack a release specification. Authoritative for R20-11 are the requirements; deviations such as for the type Pwm_PowerStateType [SWS_Pwm_00197] are identified in the text.