counter: add input-capture feature-flag

[jlh-makeen]

I would like to propose an request for improvement on the driver counter API to add the input capture feature.

The feature would work as a selector flag passed to the counter_set_channel_alarm function and therefore doesn't add new functions to the API.

Why this would make sense ?
The counter callback structure is already thought to pass the tick value together with the channel id and user_data.
When setting up an alarm as input-capture, the user is passed back the capture value from the timer.
FTM timer on NXP IMX7 and General purpose timers on STM32 are capable of generating output_compare and input_capture interrupts and are also able to reconfigure the channels as OC or IC at will.
We can therefore multiplex the use of timer channels for OC/IC depending on application needs without needing to instanciate 2 peripherals (PWM and COUNTER drivers), which could save power, software resources and maybe simplify the layout decisions on some boards where the choice of pads make it mandatory to share the Timer's OC/IC feature.

typedef void (*counter_alarm_callback_t)(const struct device *dev,
					 uint8_t chan_id, uint32_t ticks,
					 void *user_data);

As context, I have a (special) application on the IMX7D/M4 core that needs to use 1 single FTM timer to trigger both output_compare and input_capture interrupts that need to be issued from the exact same timer tick source.

I've therefore implemented the output_compare and input_capture driver into the counter implementation for imx7d in my zephyr fork.

I use it as follows:

    // Start the external interrupts
    struct counter_alarm_cfg *config = &pIntDataStruct->hTimICAlarmConfig;
    config->user_data = pIntDataStruct;
    config->flags = COUNTER_ALARM_FLAG_IC_NONSTOP | COUNTER_ALARM_FLAG_IC_UPDATE_EDGE;
    config->flags |= (bFallingNRising ? COUNTER_ALARM_FLAG_IC_FALLING : COUNTER_ALARM_FLAG_IC_RISING);

    counter_set_channel_alarm(pIntDataStruct->hTim, pIntDataStruct->nCounterAlarmIc, config);   

A channel can be configured as a normal timing alarm while not setting any attribute flags (or only the ABSOLUTE flag).

If a user needs to be notified when a falling edge or rising edge occurs on the line, the specific input capture flag can be used.

• COUNTER_ALARM_FLAG_IC_NONSTOP : the channel is not automatically stopped upon input_capture event, allowing the next input_capture to trigger
• COUNTER_ALARM_FLAG_IC_UPDATE_EDGE : update the channel trigger edge, to keep the channel active but change the trigger to rising/falling/both, this is not to return -EBUSY and force update the channel edge if the event hasn't occured yet and the channel released.
• COUNTER_ALARM_FLAG_IC_FALLING : trigger on falling edge
• COUNTER_ALARM_FLAG_IC_RISING : trigger on rising edge

Multiple vendors are able to provide both input_capture and output_compare on the same peripheral, at least, STM32, NXP general purpose timers and Flexible timers. I'm sure others can provide this feature too.

As per the implementation, drivers not supporting the Input capture can simply return -ENOTSUP upon calls of the counter_set_channel_alarm function.

I know that the PWM driver is mean to be used with input-capture but I wanted the simplicity of the counter API to implement it into the FTM/GPT drivers for my IMX7d platform. Knowing it could also work on STM32, I thought it would be a great addition to other developers.

Here is my FTM implementation for the input-capture and output-compare features working in parallel:

/*
 * Copyright (c) 2024, MAKEEN Energy
 *
 * SPDX-License-Identifier: Apache-2.0
 */

#define DT_DRV_COMPAT nxp_imx_ftm_counter

#include <zephyr/drivers/counter.h>
#include <zephyr/drivers/clock_control.h>
#include <zephyr/irq.h>
#include <soc.h>
#include <ftm_imx.h>
#include <zephyr/logging/log.h>
#include <zephyr/sys/barrier.h>
#include <zephyr/drivers/pinctrl.h>
#include "counter_ic_flags.h"


LOG_MODULE_REGISTER(imx_ftm_counter, CONFIG_COUNTER_LOG_LEVEL);

struct imx_ftm_config {
	/* info must be first element */
	struct counter_config_info info;
	FTM_Type *base;
	const struct pinctrl_dev_config *pincfg;
	ftm_clock_prescale_t prescaler;
};

struct imx_ftm_data {
	counter_top_callback_t top_callback;
	void *top_user_data;
	uint32_t freq;
	struct counter_alarm_cfg alarm_cfgs[8];
};

static int imx_ftm_start(const struct device *dev)
{
	const struct imx_ftm_config *config = dev->config;
	unsigned int key;

	key=irq_lock();
	FTM_StartTimer(config->base,kFTM_SystemClock);
	irq_unlock(key);

	LOG_DBG("FTM start: mode:%x sc:%x\n",config->base->MODE,config->base->SC);

	return 0;
}

static int imx_ftm_stop(const struct device *dev)
{
	const struct imx_ftm_config *config = dev->config;
	unsigned int key;

	key=irq_lock();
	FTM_StopTimer(config->base);
	irq_unlock(key);

	LOG_DBG("FTM stop\n");
	return 0;	
}

static int imx_ftm_get_value(const struct device *dev, uint32_t *ticks)
{
	const struct imx_ftm_config *config = dev->config;

	*ticks = FTM_GetCurrentTimerCount(config->base);

	return 0;
}

static int imx_ftm_set_alarm(const struct device *dev, uint8_t chan_id,
			      const struct counter_alarm_cfg *alarm_cfg)
{
	const struct imx_ftm_config *config = dev->config;
	struct imx_ftm_data *data = dev->data;

	uint32_t current = FTM_GetCurrentTimerCount(config->base);
	uint32_t ticks = alarm_cfg->ticks;
	unsigned int key;

	struct counter_alarm_cfg * alarm_data=NULL;

	if (chan_id >= config->info.channels) {
		LOG_ERR("FTM Invalid channel id: %d",chan_id);
		return -EINVAL;
	}

	alarm_data=&data->alarm_cfgs[chan_id];

	/* Channels is always busy if it is has callback and not an input capture. */ 
	/* or it's an input capture but the update edge flag is not set */
	if (alarm_data->callback && (alarm_data->flags & COUNTER_ALARM_FLAG_IC_BOTH) == 0) 
	{
		LOG_ERR("FTM Invalid OC channel busy: %d",chan_id);
		return -EBUSY;
	}


	/* Alarm is configured as input capture, so everytime there is a trigger on the channel line */
	if((alarm_cfg->flags & COUNTER_ALARM_FLAG_IC_BOTH) != 0) 
	{
		/* Alarm input capture already started but no update flag is given, so it's busy */
		if(alarm_data->callback && 
		  (alarm_cfg->flags & COUNTER_ALARM_FLAG_IC_UPDATE_EDGE) == 0 )
		{
			LOG_ERR("FTM Invalid IC channel busy: %d",chan_id);
			return -EBUSY;
		}

		ftm_input_capture_edge_t edge=0;
		edge |= alarm_cfg->flags & COUNTER_ALARM_FLAG_IC_RISING ? kFTM_RisingEdge : 0;
		edge |= alarm_cfg->flags & COUNTER_ALARM_FLAG_IC_FALLING ? kFTM_FallingEdge : 0;

		if(alarm_data->callback==alarm_cfg->callback && (alarm_cfg->flags & COUNTER_ALARM_FLAG_IC_UPDATE_EDGE) != 0)
		{
			alarm_data->user_data = alarm_cfg->user_data;
			alarm_data->flags = alarm_cfg->flags;
			key = irq_lock();
			FTM_UpdateChnlEdgeLevelSelect(config->base, chan_id, edge);
			irq_unlock(key);
			LOG_DBG("FTM Update IC %d\n",chan_id);
			return 0;
		}
		
		/* the interrupt is not started yet, set it up */		

		alarm_data->callback = alarm_cfg->callback;
		alarm_data->user_data = alarm_cfg->user_data;
		alarm_data->flags = alarm_cfg->flags;
		key = irq_lock();
		FTM_DisableInterrupts(config->base, (1UL<<chan_id));
		FTM_SetupInputCapture(config->base,chan_id,edge,0);
		FTM_EnableInterrupts(config->base, (1UL<<chan_id));
		irq_unlock(key);

		LOG_DBG("FTM set alarm IC %d: edge:%d alarm_flags:%x\n",chan_id,edge, alarm_data->flags);
		return 0;
	}


	/* relative alarm must trigger for a period strictly less than the TOP */
	if((alarm_cfg->flags & COUNTER_ALARM_CFG_ABSOLUTE) == 0 &&
	   alarm_cfg->ticks >= config->info.max_top_value ) {
		LOG_ERR("Error setting max %d / %d\n",alarm_cfg->ticks,config->info.max_top_value );
		return -EINVAL;
	}

	if ((alarm_cfg->flags & COUNTER_ALARM_CFG_ABSOLUTE) == 0) {
		ticks += current;
		ticks &= config->info.max_top_value; //mask with the TOP value
	}

	/* Ticks can only match if they are bellow the MAX top */
	if(ticks > config->info.max_top_value)
	{
		LOG_ERR("Error ticks max %d / %d\n",alarm_cfg->ticks,config->info.max_top_value);
		return -EINVAL;
	}

	alarm_data->callback = alarm_cfg->callback;
	alarm_data->user_data = alarm_cfg->user_data;
	alarm_data->flags = alarm_cfg->flags;
	key = irq_lock();
	FTM_SetupOutputCompare(config->base, (ftm_chnl_t)(chan_id),kFTM_NoOutputSignal, ticks);
	FTM_EnableInterrupts(config->base, (1UL<<chan_id));
	irq_unlock(key);
	LOG_DBG("FTM set alarm OC %d: %d/%d  : isr: %x \n",chan_id,current,ticks,FTM_GetEnabledInterrupts(config->base));
	return 0;
}

static int imx_ftm_cancel_alarm(const struct device *dev, uint8_t chan_id)
{
	const struct imx_ftm_config *config = dev->config;
	struct imx_ftm_data *data = dev->data;
	struct counter_alarm_cfg * alarm_data=NULL;

	if (chan_id >= config->info.channels) {
		LOG_ERR("Invalid channel id");
		return -EINVAL;
	}

	alarm_data=&data->alarm_cfgs[chan_id];

	unsigned int key=irq_lock();
	FTM_DisableInterrupts(config->base, (1UL<<chan_id));
	alarm_data->callback = NULL;
	alarm_data->flags=0;
	irq_unlock(key);

	return 0;
}

static uint32_t imx_ftm_get_pending_int(const struct device *dev)
{
	const struct imx_ftm_config *config = dev->config;

	return FTM_GetStatusFlags(config->base) & 			
			(kFTM_Chnl0Flag | 
			kFTM_Chnl1Flag | 
			kFTM_Chnl2Flag | 
			kFTM_Chnl3Flag | 
			kFTM_Chnl4Flag | 
			kFTM_Chnl5Flag | 
			kFTM_Chnl6Flag | 
			kFTM_Chnl7Flag | kFTM_TimeOverflowFlag);
}

void imx_ftm_isr(const struct device *dev)
{
	const struct imx_ftm_config *config = dev->config;
	struct imx_ftm_data *data = dev->data;
	unsigned int key = irq_lock();

	uint32_t current = FTM_GetCurrentTimerCount(config->base);
	uint32_t status;
	uint32_t int_enable = FTM_GetEnabledInterrupts(config->base);

	status =  imx_ftm_get_pending_int(dev);

	FTM_ClearStatusFlags(config->base, status);
	barrier_dsync_fence_full();

	if ((status & kFTM_TimeOverflowFlag) && (int_enable & kFTM_TimeOverflowFlag) && data->top_callback) {
		LOG_DBG("FTM TOP callback: %p\n",data->top_callback);

		data->top_callback(dev, data->top_user_data);
	}

	for(uint8_t chan_id=0;chan_id<config->info.channels;chan_id++)
	{
		uint32_t channel_flag=(1UL<<chan_id);
		struct counter_alarm_cfg * alarm_data=&data->alarm_cfgs[chan_id];

		if ((status & channel_flag) && (int_enable & channel_flag) && alarm_data->callback) 
		{
			counter_alarm_callback_t alarm_cb = alarm_data->callback;
			/* If the channel interrupt should be disabled */
			if((alarm_data->flags & COUNTER_ALARM_FLAG_IC_NONSTOP) == 0)
			{
				FTM_DisableInterrupts(config->base,channel_flag);
				alarm_data->callback = NULL;
			}
			/* For input capture copy into the alarm_data->ticks the input capture value */
			if((alarm_data->flags & COUNTER_ALARM_FLAG_IC_BOTH))
			{
				/* for input capture the current timer value is the input capture register */
				current = FTM_GetInputCaptureValue(config->base, chan_id);
				LOG_DBG("IC interrupt %d CSC: %x CV: %d\n",chan_id,config->base->C[chan_id].CSC,alarm_data->ticks);			
			}

			alarm_cb(dev, chan_id, current, alarm_data->user_data);
		}
	}
	
	//LOG_DBG("FTM ISR: SC: %x STATUS: %x/%x\n", config->base->SC, status,config->base->STATUS);
	irq_unlock(key);
}


static int imx_ftm_set_top_value(const struct device *dev,
				  const struct counter_top_cfg *cfg)
{
	const struct imx_ftm_config *config = dev->config;
	struct imx_ftm_data *data = dev->data;
	int res=0;

	if (cfg->ticks != config->info.max_top_value) {
		LOG_ERR("Wrap can only be set to 0x%x",
			config->info.max_top_value);
		res=-ENOTSUP;
	}

	data->top_callback = cfg->callback;
	data->top_user_data = cfg->user_data;

	FTM_EnableInterrupts(config->base, kFTM_TimeOverflowInterruptEnable);

	/* set_top_value resets the counter as per flags in Zephyr API */
	if ((cfg->flags & COUNTER_TOP_CFG_DONT_RESET)==0) {
		config->base->CNT=0;
	}	

	return res;
}

static uint32_t imx_ftm_get_top_value(const struct device *dev)
{
	const struct imx_ftm_config *config = dev->config;

	return config->info.max_top_value;
}

#define TO_FTM_PRESCALE_DIVIDE(val) _DO_CONCAT(kFTM_Prescale_Divide_, val)

uint32_t imx_ftm_get_freq(const struct device *dev)
{
	const struct imx_ftm_config *config = dev->config;
	struct imx_ftm_data *data = dev->data;

	if(data->freq==0)
	{
		uint32_t clock_freq = get_ftm_clock_freq(config->base);
		data->freq = clock_freq >> config->prescaler;
	}

	return data->freq;
}


static int imx_ftm_init(const struct device *dev)
{
	const struct imx_ftm_config *config = dev->config;
	struct imx_ftm_data *data = dev->data;
	ftm_config_t ftmConfig;
	uint32_t clock_freq;
	int err;

	/* Adjust divider to match expected freq */
	data->top_callback=NULL;
	data->top_user_data=NULL;

	/* soc.c hardcodes the clock to 24Mhz*/
	clock_freq = get_ftm_clock_freq(config->base);

	uint32_t ftm_freq=clock_freq >> config->prescaler;

	imx_ftm_get_freq(dev);

	LOG_DBG("FTM srcClock: %u configClock: %u presc: %u/%u cntFreq: %u\n",
	    clock_freq, config->info.freq,(1<<config->prescaler),config->prescaler, ftm_freq);

	err = pinctrl_apply_state(config->pincfg, PINCTRL_STATE_DEFAULT);
	if (err == -ENOENT) {
		LOG_DBG("No pinctrl defined for FTM %p:\n",dev);
	}

	FTM_GetDefaultConfig(&ftmConfig);
	ftmConfig.prescale=config->prescaler;

	FTM_Init(config->base,&ftmConfig);

	LOG_DBG("FTM Init: SC: %x STATUS: %x noch: %d\n", config->base->SC,config->base->STATUS, config->info.channels);

	return 0;
}

static const struct counter_driver_api imx_ftm_driver_api = {
	.start = imx_ftm_start,
	.stop = imx_ftm_stop,
	.get_value = imx_ftm_get_value,
	.set_alarm = imx_ftm_set_alarm,
	.cancel_alarm = imx_ftm_cancel_alarm,
	.set_top_value = imx_ftm_set_top_value,
	.get_pending_int = imx_ftm_get_pending_int,
	.get_top_value = imx_ftm_get_top_value,
	.get_freq = imx_ftm_get_freq,
};

#define FTM_DEVICE_INIT_MCUX(n)						\
	\
	PINCTRL_DT_INST_DEFINE(n); \
	\
	static struct imx_ftm_data imx_ftm_data_ ## n = {0};		\
									\
	static const struct imx_ftm_config imx_ftm_config_ ## n = {	\
		.base = (void *)DT_INST_REG_ADDR(n),			\
		.pincfg = PINCTRL_DT_INST_DEV_CONFIG_GET(n),		\
		.prescaler = TO_FTM_PRESCALE_DIVIDE(DT_INST_PROP(n, prescaler)),\
		.info = {						\
			.max_top_value = UINT16_MAX,			\
			.freq = 0,           \
			.channels = 8,		\
			.flags = COUNTER_CONFIG_INFO_COUNT_UP,		\
		},							\
	};								\
									\
	static int imx_ftm_## n ##_init(const struct device *dev);	\
	\
	DEVICE_DT_INST_DEFINE(n,					\
			    imx_ftm_## n ##_init,			\
			    NULL,					\
			    &imx_ftm_data_ ## n,			\
			    &imx_ftm_config_ ## n,			\
			    POST_KERNEL,				\
			    CONFIG_COUNTER_INIT_PRIORITY,		\
			    &imx_ftm_driver_api);			\
									\
	static int imx_ftm_## n ##_init(const struct device *dev)	\
	{								\
		IRQ_CONNECT(DT_INST_IRQN(n),				\
			    DT_INST_IRQ(n, priority),			\
			    imx_ftm_isr, DEVICE_DT_INST_GET(n), 0);	\
		irq_enable(DT_INST_IRQN(n));				\
		return imx_ftm_init(dev);				\
	}								\

DT_INST_FOREACH_STATUS_OKAY(FTM_DEVICE_INIT_MCUX)