Output Compare - Peripheral Abstraction Layer (OC PAL)

Detailed Description

The S32 SDK provides a Peripheral Abstraction Layer for the output compare mode of S32 SDK devices.

The OC PAL driver allows to set pin, clear pin or toggle pin. It was designed to be portable across all platforms and IPs which support FTM, eMIOS and eTIMER.

How to integrate OC PAL in your application

Unlike the other drivers, OC PAL modules need to include a configuration file named oc_pal_cfg.h. This one allows the user to specify which IPs are used. The following code example shows how to configure one instance for each available OC IPs.

#ifndef OC_PAL_CFG_H
#define OC_PAL_CFG_H
/* Define which IP instance will be used in current project */
#define OC_PAL_OVER_EMIOS
#endif /* OC_PAL_CFG_H */

The following table contains the matching between platforms and available IPs

IP/MCU S32K116 S32K118 S32K142 S32K144 S32K146 S32K148 MPC5748G MPC5746C MPC5744P
FTM_OC YES YES YES YES YES YES NO NO NO
eMIOS_OC NO NO NO NO NO NO YES YES NO
eTIMER NO NO NO NO NO NO NO NO YES

Features

Functionality

Initialization

In order to use the OC PAL driver it must be first initialized, using OC_Init() function. Once initialized, it should be de-initialized before initialized again for the same OC module instance, using OC_Deinit(). The initialization function does the following operations:

Example:

const oc_instance_t oc_pal1_instance = { OC_INST_TYPE_ETIMER, 0U };
channel_extension_etimer_for_oc_t oc_pal1_etimerChnExtension0 =
{
.primaryInput =
{
.source = ETIMER_IN_SRC_CLK_DIV_128,
.polarity = ETIMER_POLARITY_POSITIVE,
},
.outputPin =
{
.enable = true,
.polarity = ETIMER_POLARITY_POSITIVE,
},
};
oc_output_ch_param_t oc_pal1_ChnConfig[1] =
{
/* Channel configuration 0 */
{
.hwChannelId = 4U,
.chMode = OC_TOGGLE_ON_MATCH,
.comparedValue = 62500,
.channelExtension = &oc_pal1_etimerChnExtension0,
.channelCallbackParams = NULL,
.channelCallbacks = oc_pal1_channel_callBack0
}
};
oc_config_t oc_pal1_InitConfig =
{
.nNumChannels = 1U,
.outputChConfig = oc_pal1_ChnConfig,
.extension = NULL
};
/* Initialize output compare mode */
OC_Init(&oc_pal1_instance, &oc_pal1_InitConfig);

De-initialize a output compare instance

This function will disable the output compare mode. The driver can't be used again until reinitialized. All register are reset to default value and counter is stopped.

Example:

/* De-initialize output compare mode */
OC_Deinit(&oc_pal1_instance);

Start the channel in the output compare mode

This function will set the channel is in the output compare mode.

Example:

uint8_t hwChannel = oc_pal1_InitConfig.outputChConfig->hwChannelId;
/* Start channel in the output compare mode */
OC_StartChannel(&oc_pal1_instance, hwChannel);

Stop the channel in the output compare mode

This function will set the channel is used in GPIO mode or other peripheral.

Example:

uint8_t hwChannel = oc_pal1_InitConfig.outputChConfig->hwChannelId;
/* Stop channel in the output compare mode */
OC_StopChannel(&oc_pal1_instance, hwChannel);

Control the channel output by software

This function is used to forces the output pin to a specified value. It can be used to control the output pin value when the OC channel is disabled.

Example:

uint8_t hwChannel = oc_pal1_InitConfig.outputChConfig->hwChannelId;
/* Force the channel output by software */
OC_SetOutputState(&oc_pal1_instance, hwChannel, false);

Set the operation mode of channel output

This function will set the action executed on a compare match value to set output pin, clear output pin, toggle output pin.

Example:

uint8_t hwChannel = oc_pal1_InitConfig.outputChConfig->hwChannelId;
/* Change the channel output to toggle pin */
OC_SetOutputAction(&oc_pal1_instance, hwChannel, OC_TOGGLE_ON_MATCH);

Update the match value on the channel

This function will update the value of an output compare channel to the counter matches to this value.

Example:

uint8_t hwChannel = oc_pal1_InitConfig.outputChConfig->hwChannelId;
/* Set the match counter to new value */
OC_SetCompareValue(&oc_pal1_instance, hwChannel, 0x1000UL, OC_RELATIVE_VALUE);

Important Notes

Data Structures

struct  oc_output_ch_param_t
 The configuration structure of output compare parameters for each channel. More...
 
struct  oc_config_t
 Defines the configuration structures are used in the output compare mode. More...
 

Enumerations

enum  oc_option_mode_t { OC_DISABLE_OUTPUT = 0x00U, OC_TOGGLE_ON_MATCH = 0x01U, OC_CLEAR_ON_MATCH = 0x02U, OC_SET_ON_MATCH = 0x03U }
 The type of comparison for output compare mode Implements : oc_option_mode_t_Class. More...
 
enum  oc_option_update_t { OC_RELATIVE_VALUE = 0x00U, OC_ABSOLUTE_VALUE = 0x01U }
 The type of update on the channel match Implements : oc_option_mode_t_Class. More...
 

Functions

status_t OC_Init (const oc_instance_t *const instance, const oc_config_t *const configPtr)
 Initializes the output compare mode. More...
 
status_t OC_Deinit (const oc_instance_t *const instance)
 De-initialize the output compare instance. More...
 
void OC_StartChannel (const oc_instance_t *const instance, const uint8_t channel)
 Start the counter. More...
 
void OC_StopChannel (const oc_instance_t *const instance, const uint8_t channel)
 Stop the counter. More...
 
status_t OC_SetOutputState (const oc_instance_t *const instance, const uint8_t channel, bool outputValue)
 Control the channel output by software. More...
 
status_t OC_SetOutputAction (const oc_instance_t *const instance, const uint8_t channel, oc_option_mode_t channelMode)
 Set the operation mode of channel output. More...
 
status_t OC_SetCompareValue (const oc_instance_t *const instance, const uint8_t channel, uint32_t nextCompareMatchValue, oc_option_update_t typeOfupdate)
 Update the match value on the channel. More...
 
void OC_EnableNotification (const oc_instance_t *const instance, const uint8_t channel)
 Enable channel notifications. More...
 
void OC_DisableNotification (const oc_instance_t *const instance, const uint8_t channel)
 Disable channel notifications. More...
 

Enumeration Type Documentation

The type of comparison for output compare mode Implements : oc_option_mode_t_Class.

Enumerator
OC_DISABLE_OUTPUT 

No action on output pin

OC_TOGGLE_ON_MATCH 

Toggle on match

OC_CLEAR_ON_MATCH 

Clear on match

OC_SET_ON_MATCH 

Set on match

Definition at line 62 of file oc_pal.h.

The type of update on the channel match Implements : oc_option_mode_t_Class.

Enumerator
OC_RELATIVE_VALUE 

Next compared value is relative to current value

OC_ABSOLUTE_VALUE 

Next compared value is absolute

Definition at line 74 of file oc_pal.h.

Function Documentation

status_t OC_Deinit ( const oc_instance_t *const  instance)

De-initialize the output compare instance.

This function will disable the output compare mode. The driver can't be used again until reinitialized. The context structure is no longer needed by the driver and can be freed after calling this function.

Parameters
[in]instanceThe output compare instance number.
Returns
Operation status
  • STATUS_SUCCESS: Operation was successful

Definition at line 742 of file oc_pal.c.

void OC_DisableNotification ( const oc_instance_t *const  instance,
const uint8_t  channel 
)

Disable channel notifications.

This function disables channel notification.

Parameters
[in]instanceThe output compare instance number
[in]channelThe channel number

Definition at line 1170 of file oc_pal.c.

void OC_EnableNotification ( const oc_instance_t *const  instance,
const uint8_t  channel 
)

Enable channel notifications.

This function enables channel notification.

Parameters
[in]instanceThe output compare instance number
[in]channelThe channel number

Definition at line 1146 of file oc_pal.c.

status_t OC_Init ( const oc_instance_t *const  instance,
const oc_config_t *const  configPtr 
)

Initializes the output compare mode.

This function will initialize the OC PAL instance, including the other platform specific HW units used together in the output compare mode. This function configures a group of channels in instance to set, clear toggle the output signal.

Parameters
[in]instanceThe output compare instance number.
[in]configPtrThe pointer to configuration structure.
Returns
Operation status
  • STATUS_SUCCESS : Completed successfully.
  • STATUS_ERROR : Error occurred.

Definition at line 688 of file oc_pal.c.

status_t OC_SetCompareValue ( const oc_instance_t *const  instance,
const uint8_t  channel,
uint32_t  nextCompareMatchValue,
oc_option_update_t  typeOfupdate 
)

Update the match value on the channel.

This function will update the value of an output compare channel to the counter matches to this value.

Parameters
[in]instanceThe output compare instance number.
[in]channelThe channel number.
[in]nextCompareMatchValueThe timer value in ticks until the next compare match event should be appeared.
[in]typeOfupdateThe type of update:
  • OC_RELATIVE_VALUE : nextCompareMatchValue will be added to current counter value into the channel value register
  • OC_ABSOLUTE_VALUE : nextCompareMatchValue will be written into the channel value register
Returns
Operation status
  • STATUS_SUCCESS : Completed successfully.
  • STATUS_ERROR : Error occurred.

Definition at line 1047 of file oc_pal.c.

status_t OC_SetOutputAction ( const oc_instance_t *const  instance,
const uint8_t  channel,
oc_option_mode_t  channelMode 
)

Set the operation mode of channel output.

This function will set the action executed on a compare match value to set output pin, clear output pin, toggle output pin.

Parameters
[in]instanceThe output compare instance number.
[in]channelThe channel number.
[in]channelModeThe channel mode in output compare:
  • OC_DISABLE_OUTPUT : No action on output pin
  • OC_TOGGLE_ON_MATCH : Toggle on match
  • OC_CLEAR_ON_MATCH : Clear on match
  • OC_SET_ON_MATCH : Set on match
Returns
Operation status
  • STATUS_SUCCESS : Completed successfully.
  • STATUS_ERROR : Error occurred.

Definition at line 982 of file oc_pal.c.

status_t OC_SetOutputState ( const oc_instance_t *const  instance,
const uint8_t  channel,
bool  outputValue 
)

Control the channel output by software.

This function is used to forces the output pin to a specified value. It can be used to control the output pin value when the OC channel is disabled.

Parameters
[in]instanceThe output compare instance number.
[in]channelThe channel number.
[in]outputValueThe output value:
  • false : The software output control forces 0 to the channel output.
  • true : The software output control forces 1 to the channel output.
Returns
Operation status
  • STATUS_SUCCESS : Completed successfully.
  • STATUS_ERROR : Error occurred.

Definition at line 925 of file oc_pal.c.

void OC_StartChannel ( const oc_instance_t *const  instance,
const uint8_t  channel 
)

Start the counter.

This function start channel counting.

Parameters
[in]instanceThe output compare instance number.
[in]channelThe channel number.

Definition at line 817 of file oc_pal.c.

void OC_StopChannel ( const oc_instance_t *const  instance,
const uint8_t  channel 
)

Stop the counter.

This function stop channel counting.

Parameters
[in]instanceThe output compare instance number.
[in]channelThe channel number.

Definition at line 874 of file oc_pal.c.