Zephyr Counter Driver Limitations for Short Delay Generation on Ambiq Apollo3 EVB

[AlienSarlak]

An issue has been identified with the use of the Zephyr counter API on the Ambiq Apollo3 microcontroller. When configuring counter0 with clock source 2 CTIMER_CTRL0_TMRA0CLK_HFRC_DIV16, which yields a timer frequency of 3 MHz, the expected timing resolution should be approximately 334 ns. However, attempts to generate short delays using the standard Zephyr counter sample code revealed that the (ISR) is not invoked for delays shorter than approximately 10 µs. This behavior limits the ability to achieve fine-grained timing control, and the underlying cause of this limitation remains unknown to me.

What target platform are you using?

• Target platform is Ambiq Apollo3 Blue EVB

What have you tried to diagnose or workaround this issue?

• As a workaround, I used (HAL) directly within the Zephyr environment, bypassing the counter API. This approach enabled the successful generation of precise pulses with durations below 1 µs, including those as short as 334 ns, indicating that the hardware is capable of such resolution.

Furthermore, I observed that setting alarm_cfg.flags = 0 results in deteriorated timing accuracy, while using COUNTER_ALARM_CFG_ABSOLUTE leads to improved precision for delays greater than 50 µs. This result was unexpected, as the default relative alarm mode was initially assumed to provide better accuracy.

To Reproduce
apollo3_evb.overlay:

/ {
    aliases {
        timer0 = &counter0;
        pin0 = &gpio17;
    };

    my_gpio{
        compatible = "gpio-leds";
        gpio17: gpio_17 {
            gpios = <&gpio0_31 17 GPIO_ACTIVE_HIGH>;
        };
    };
};

&counter0 {
    clock-frequency = <DT_FREQ_M(12)>;
    clk-source = <1>;
    status = "okay";
};

&gpio0_31 {
    status = "okay";
};

code: https://github.com/zephyrproject-rtos/zephyr/tree/main/samples/drivers/counter/alarm

modify main.c as:

#include <zephyr/device.h>
#include <zephyr/sys/printk.h>
#include <zephyr/kernel.h>
#include <zephyr/drivers/counter.h>
#include <zephyr/drivers/gpio.h>

// Delay in uS
#define DELAY 10
#define ALARM_CHANNEL_ID 0

#if defined(CONFIG_BOARD_APOLLO3_EVB)
#define TIMER DT_ALIAS(timer0)
#define PIN_GPIO DT_ALIAS(pin0)
#else
#error Unable to find a counter device node in devicetree
#endif

// Hardware related devices
const struct device *const counter_dev = DEVICE_DT_GET(TIMER);
const struct gpio_dt_spec gpio_pin = GPIO_DT_SPEC_GET(PIN_GPIO, gpios);

void test_counter_interrupt_fn(const struct device *counter_dev,
                               uint8_t chan_id, uint32_t ticks,
                               void *user_data)
{
    if (gpio_pin_toggle_dt(&gpio_pin) < 0)
    {
        printk("GPIO could not be toggle!\n");
    }
}

int main(void)
{

    // User Data Struct
    struct counter_alarm_cfg alarm_cfg;

    // GPIO

    if (!gpio_is_ready_dt(&gpio_pin))
    {
        printk("device not ready.\n");
        return -ENODEV;
    }

    if (gpio_pin_configure_dt(&gpio_pin, GPIO_OUTPUT_ACTIVE) < 0)
    {
        printk("GPIO Configuration is not supported!\n");
        return 0;
    }


    printk("Counter alarm sample\n\n");

    if (!device_is_ready(counter_dev))
    {
        printk("device not ready.\n");
        return -ENODEV;
    }

    // Free run mode
    counter_start(counter_dev);

    // alarm_cfg.flags = COUNTER_ALARM_CFG_ABSOLUTE;
    alarm_cfg.flags = 0;
    alarm_cfg.ticks = counter_us_to_ticks(counter_dev, DELAY);
    alarm_cfg.callback = test_counter_interrupt_fn;
    alarm_cfg.user_data = &alarm_cfg;

    /* Single shot alarm */
    int err = counter_set_channel_alarm(counter_dev,
                                        ALARM_CHANNEL_ID,
                                        &alarm_cfg);

    if (-EINVAL == err)
    {
        printk("Alarm settings invalid\n");
    }
    else if (-ENOTSUP == err)
    {
        printk("Alarm setting request not supported\n");
    }
    else if (0 != err)
    {
        printk("Unknown Error\n");
    }

    printk("tick = %d\n", alarm_cfg.ticks);
    printk("SLEEP FOREVER .... -_-\n");

    while (1)
    {
        k_sleep(K_FOREVER);
    }
    return 0;
}

prj.conf

CONFIG_LOG=y
CONFIG_GPIO=y

CONFIG_PRINTK=y
CONFIG_COUNTER=y

Expected behavior

With a 3 MHz timer (334 ns resolution), the counter should generate accurate delays. A configured delay of 10 µs should produce a 10 µs pulse, and a 5 µs delay should result in a 5 µs pulse. This precision is expected given the hardware capabilities and timer resolution.

Impact

The lack of precise timing support has effectively blocked further development of my project.

Environment

• OS: Ubuntu 22.04.4 LTS (Linux kernel 6.8.0-52) (inside a docker container)
• Toolchain (Zephyr SDK)
• Commit SHA (1207ccf)

Additional context
Delay of 50 µs when using alarm_cfg.flags = COUNTER_ALARM_CFG_ABSOLUTE;

Delay of 50 µs when using alarm_cfg.flags = 0;

[AlessandroLuo]

@AlienSarlak Sorry for the late reply, the correct logic of ctimer according to ambiq hal is first config and then start, however in the counter\alarm sample, it calls counter_start first and then counter_set_channel_alarm, it will make the delay not accurate and ever miss the isr when the delay is too small like the one you set 10us. I suggest you place counter_start after counter_set_channel_alarm and try again.

[AlienSarlak]

@AlessandroLuo Thank you for your suggestion. Unfortunately, the issue remains unresolved despite implementing the recommended changes.

Below is my overlay:

/ {
    aliases {
        timer0 = &counter0;
        pin0 = &gpio12;
    };

    my_gpio{
        compatible = "gpio-leds";
        gpio12: gpio_12 {
            gpios = <&gpio0_31 12 GPIO_ACTIVE_HIGH>;
        };
    };
};

&counter0 {
    clock-frequency = <DT_FREQ_M(12)>;
    clk-source = <1>;
    status = "okay";
};


&gpio0_31 {
    status = "okay";
};

And below is main.c code:

/*
 * Copyright (c) 2019 Linaro Limited
 *
 * SPDX-License-Identifier: Apache-2.0
 */

#include <zephyr/kernel.h>

#include <zephyr/device.h>
#include <zephyr/drivers/counter.h>
#include <zephyr/sys/printk.h>
#include <zephyr/drivers/gpio.h>

#define DELAY 10
#define ALARM_CHANNEL_ID 0

struct counter_alarm_cfg alarm_cfg;

#if defined(CONFIG_BOARD_APOLLO3_EVB)
#define TIMER DT_ALIAS(timer0)
#define PIN_GPIO DT_ALIAS(pin0)
#else
#error Unable to find a counter device node in devicetree
#endif

// Hardware related devices
const struct device *const counter_dev = DEVICE_DT_GET(TIMER);
const struct gpio_dt_spec gpio_pin = GPIO_DT_SPEC_GET(PIN_GPIO, gpios);

static void test_counter_interrupt_fn(const struct device *counter_dev,
                                      uint8_t chan_id, uint32_t ticks,
                                      void *user_data)
{
    int ret = gpio_pin_toggle_dt(&gpio_pin);
    if (ret < 0)
    {
        printk("GPIO is not toggle!\n");
        return;
    }
}

int main(void)
{
    const struct device *const counter_dev = DEVICE_DT_GET(TIMER);
    int err;

    if (!gpio_is_ready_dt(&gpio_pin))
    {
        printk("GPIO is not ready!\n");
        return -1;
    }

    err = gpio_pin_configure_dt(&gpio_pin, GPIO_OUTPUT_ACTIVE);
    if (err < 0)
    {
        printk("GPIO is not configured!\n");
        return 0;
    }

    printk("Counter alarm sample\n\n");

    if (!device_is_ready(counter_dev))
    {
        printk("device not ready.\n");
        return 0;
    }

    alarm_cfg.flags = 0;
    alarm_cfg.ticks = counter_us_to_ticks(counter_dev, DELAY);
    alarm_cfg.callback = test_counter_interrupt_fn;
    alarm_cfg.user_data = &alarm_cfg;

    err = counter_set_channel_alarm(counter_dev, ALARM_CHANNEL_ID,
                                    &alarm_cfg);
    printk("Set alarm in %u sec (%u ticks)\n",
           (uint32_t)(counter_ticks_to_us(counter_dev,
                                          alarm_cfg.ticks) /
                      USEC_PER_SEC),
           alarm_cfg.ticks);

    if (-EINVAL == err)
    {
        printk("Alarm settings invalid\n");
    }
    else if (-ENOTSUP == err)
    {
        printk("Alarm setting request not supported\n");
    }
    else if (err != 0)
    {
        printk("Error\n");
    }

    counter_start(counter_dev);

    while (1)
    {
        k_sleep(K_FOREVER);
    }
    return 0;
}

I am still unable to generate a precise 10 µs square wave on pin 12, as the output pulse width does not fall below 20 µs. However, when utilizing the Ambiq HAL (Hardware Abstraction Layer) directly—bypassing higher-level abstractions—I am able to achieve a minimum pulse width of approximately 400 ns.

Using Zephyr, 10uS timing gives me 25uS as shown below:

[AlessandroLuo]

Hi @AlienSarlak,
I analized the delay with codes a little bit and here are my findings:
If you do not change current dts and ambiq counter driver and set delay very small, you will not get an accurate delay, and it is consist of following parts, take 10us as example:

1. 10us real delay from the counter;
2. 5us cost by DT_INST_FOREACH_STATUS_OKAY in counter_ambiq_isr, as for apollo3, all 8 counters share the same IRQ number, there will be a polling check when multiple timers been enabled. And this extra time cost can be eliminated by disable other counters that you do not use in dts.

&counter1 {
	status = "disabled";
};
&counter2 {
	status = "disabled";
};

3. 8us cost by counter_ambiq_get_value in APOLLO3_HANDLE_SHARED_TIMER_IRQm, as the apollo3 am_hal_ctimer_read function is quite complex, it will cost unnecessary time for the application which has high requirement for real-time performance, if you don't need to read the counter for your application, just delete it, or move it to your callback if you need.
4. 2us cost by other context switch in zephyr architecture, like the lookup for callback.
   So if you need very small delay (<25us) achieved by apollo3 ctimer, I would suggest you not connect the irq defined in counter_ambiq_timer, and write your own one in application layer.

[AlienSarlak]

@AlessandroLuo Thank you very much for your detailed analysis, it now makes sense. The only question I still have is the following:
considering the real-time nature of my application, I implemented custom code using ambiq_hal in Zephyr (essentially adapting one of Ambiq’s ctimer examples), and I was able to achieve a resolution of 333 ns. Given this result, does it make sense to avoid using the Ambiq counter driver and instead rely on my own implementation? I am uncertain whether this is a good long-term approach.

[AlessandroLuo]

@AlienSarlak Are you going to push your codes to zephyr? If so it may not be a good long-term approach...

Hi @nordic-krch, we found it's hard to achieve very short delay (<10us) via the counter driver, is it allowed to bypass zephyr architecture and call our HAL APIs directly?

[AlienSarlak]

@AlessandroLuo and @nordic-krch I don't intend to push my code into the Zephyr repository, but the reason I’m raising this point is that, from a software architecture perspective, bypassing the Ambiq driver(s) and directly using the HAL effectively bypasses Zephyr itself. This seems counterproductive, especially considering that my initial goal was to adopt Zephyr as the main operating system layer. If I implement everything using ambiq_hal, it raises the question: what added value does Zephyr provide in this setup?

[nordic-krch]

using zephyr driver model and generic counter implementation may have some performance cost and increase latency. imo, for application specific cases you might need to rely on custom solution (using hal and direct isr). Sometimes it's the only option.