GPT

This section introduces the General Purpose Timer(GPT) driver APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, GPT function groups, enums, structures and functions. More...

Overview

This section introduces the General Purpose Timer(GPT) driver APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, GPT function groups, enums, structures and functions.

• If the parameter HAL_GPT_CLOCK_SOURCE_1M is used in hal_gpt_get_free_run_count(), the unit of the tick count is in microseconds.

Terms and acronyms

Terms	Details
GPT	General Purpose Timer(GPT) is used as an alarm clock for timing.
NVIC	The Nested Vectored Interrupt Controller (NVIC) is the interrupt controller of ARM Cortex-M. For more details, please refer to NVIC introduction in ARM Cortex-M4 Processor Technical Reference Manual .

Supported features

This controller has a generic design to support various combinations of the timer functionality.

• Support oneshot, repeat and free run modes.
  A timer can be configured in one of the modes, oneshot mode, repeat mode and free run mode. The timer mode is configured through the mode configuration.
  • Oneshot mode. In this mode, the interrupt is triggered only once when the timer expires.
  • Repeat mode. In this mode, the interrupt is triggered when the timer expires. At the same time, the timer is reloaded again with the same value and starts ticking till the next expiration. This pattern repeats until the timer is cancelled. This mode is useful for handling functions that are executed periodically.
    
  • Free run mode. In this mode, the timer simply becomes a counter. There is no interrupt triggered in this mode. The counter keeps running once using hal_gpt_get_free_run_count(), and never stops. Call hal_gpt_get_free_run_count() to get the stamp of counter ticks. This mode is useful when a delay or counting operations are performed.
• Support delay function.
  The GPT driver supports delays in milliseconds hal_gpt_delay_ms() and microseconds hal_gpt_delay_us(). It utilizes the free run mode of the timer and the polling mechanism to determine if the timeout for the timer is reached.
  The delay function is a hardware delay. It is for some programs to delay for a specified period without the need for the context switch.
  
• Support callback function registration.
  A callback function must be registered using hal_gpt_register_callback() function, then call hal_gpt_start_timer_ms() to set the oneshot mode or the repeat mode to start the timer.
  The callback function is called after the GPT triggers an interrupt in the GPT ISR routine.
  

How to use this driver

• Using GPT oneshot or repeat mode.
  Call hal_gpt_get_running_status() function to manually check the GPT status before using the GPT driver in oneshot or repeat mode. If the status is HAL_GPT_RUNNING, user should wait till the status is HAL_GPT_STOPPED.
  Call hal_gpt_init() then hal_gpt_start_timer_ms() functions to set the GPT mode and expiration time.
  The timer then starts ticking. Once the pre-set time expires in a oneshot mode, the GPT triggers an interrupt, stops the timer, and calls user's callback function. In a repeat mode, when the set time expires, the timer is reloaded with the set time and the user callback function is invoked. To ensure the precise timing, do not overload the callback function. Let the callback return as fast as possible.
  • Step1: Call hal_gpt_get_running_status() to get the current running status.
  • Step2: Call hal_gpt_init() to configure the base environment.
  • Step3: Call hal_gpt_register_callback() to register a callback function.
  • Step4: Call hal_gpt_start_timer_ms() to set the timer mode and the expiration time and start the timer.
  • Step5: Call hal_gpt_stop_timer() to stop the timer.
  • Step6: Call hal_gpt_deinit() to de-initilize the GPT module if it's no longer in use.
  • Sample code:

    hal_gpt_running_status_t running_status;
    hal_gpt_status_t         ret_status;
    
    //Get the running status to check if this port is in use or not.
    if (HAL_GPT_STATUS_OK != hal_gpt_get_running_status(HAL_GPT_1,&running_status)) {//Handle the error, if the timer is running.
       //error handle
    }
    //Set the GPT base environment.
    if(HAL_GPT_STATUS_OK != hal_gpt_init(HAL_GPT_1)) {
       //error handle
    }
    hal_gpt_register_callback(HAL_GPT_1, user_gpt_callback, &user_data); //Register a user callback.
    hal_gpt_start_timer_ms(HAL_GPT_1, 10, HAL_GPT_TIMER_TYPE_ONE_SHOT); //Set 10ms timeout, set oneshot mode and start timer.
    //if in repeat mode, please call hal_gpt_start_timer_ms(gpt_port, 10, HAL_GPT_TIMER_TYPE_REPEAT);
    //....

    // Callback function. This function should be registered with #hal_gpt_register_callback().
    void user_gpt_callback (void *user_data)
    {
        // user's handle
        hal_gpt_stop_timer(HAL_GPT_1);                                    //Stop the timer.
        hal_gpt_deinit(HAL_GPT_1);                                        //If it's no longer in use.
    }

• Using GPT in free run mode.
  Call hal_gpt_get_free_run_count() to get the first stamp of timer ticks.
  Call hal_gpt_get_free_run_count() again to get the second stamp of timer ticks.
  If HAL_GPT_CLOCK_SOURCE_32K parameter is in use, the unit of tick is 1/32768 seconds. The difference between the first and the second stamps is the counting ticks. In a free run mode, the GPT runs continuously and never stops. It does not provide interrupt feature. The GPT driver also uses this function implementation similar to the delay function hal_gpt_delay_ms().
  
  • Note: when the GPT works at freerun mode, we need not call hal_gpt_init() and hal_gpt_deinit() to init and deinit the GPT.
  • Step1: Call hal_gpt_get_free_run_count() to get the first tick count.
  • Step2: Call hal_gpt_get_free_run_count() to get the second tick count.
  • Step3: Call hal_gpt_get_duration_count() to get the duration time.

  • Sample code:

    hal_gpt_status_t         ret_status;
    uint32_t                 count1, count2, duration_count;
    uint32_t                 time;
    
    //Get the first value.
    if(HAL_GPT_STATUS_OK != hal_gpt_get_free_run_count(HAL_GPT_CLOCK_SOURCE_32K, &count1)) {
       //error handle
    }
    
    hal_gpt_delay_ms(10);                               //Delay for 10 ms.
    
    //Get the second value.
    if(HAL_GPT_STATUS_OK != hal_gpt_get_free_run_count(HAL_GPT_CLOCK_SOURCE_32K, &count2)) {
       //error handle
    }
    
    //Calculate count1 and count2 durations, the duration unit is 1/32768 seconds.
    if(HAL_GPT_STATUS_OK != hal_gpt_get_duration_count(count1, count2, &duration_count)) {
       //error handle
    }
    
    time = (duration_count*1000)/32768;                //The time duration in milliseconds.

    For more details about HAL_GPT_CLOCK_SOURCE_1M, please refer to Enum about hal_gpt_clock_source_t.

  • Sample code:

    hal_gpt_status_t         ret_status;
    uint32_t                 count1, count2, duration_count;
    uint32_t                 time;
    
    //Get the first value.
    if(HAL_GPT_STATUS_OK != hal_gpt_get_free_run_count(HAL_GPT_CLOCK_SOURCE_1M, &count1)) {
       //error handle
    }
    
    hal_gpt_delay_us(10);                       //Delay for 10 us.
    
    //Get the second value.
    if(HAL_GPT_STATUS_OK != hal_gpt_get_free_run_count(HAL_GPT_CLOCK_SOURCE_1M, &count2)) {
       //error handle
    }
    
    //Calculate count1 and count2 durations, the duration unit is 1 microseconds.
    if(HAL_GPT_STATUS_OK != hal_gpt_get_duration_count(count1, count2, &duration_count)) {
       //error handle
    }
    
    time = duration_count;                      //The time duration in microseconds.

• Using the GPT delay function.
  Call hal_gpt_delay_ms() function to set the delay time. When in a delay, the GPT driver uses free run mode and polls register value until it expires.
  • Sample code:

    hal_gpt_delay_ms(10);  //Delay for 10 ms.

Functions
hal_gpt_status_t	hal_gpt_init (hal_gpt_port_t gpt_port)
	This function initializes the GPT base enironment. More...
hal_gpt_status_t	hal_gpt_deinit (hal_gpt_port_t gpt_port)
	This function de-initializes the GPT timer. More...
hal_gpt_status_t	hal_gpt_get_running_status (hal_gpt_port_t gpt_port, hal_gpt_running_status_t *running_status)
	This function gets the running status of the port as specified. More...
hal_gpt_status_t	hal_gpt_register_callback (hal_gpt_port_t gpt_port, hal_gpt_callback_t callback, void *user_data)
	This function registers a callback function with the timer specified at the port. More...
hal_gpt_status_t	hal_gpt_get_free_run_count (hal_gpt_clock_source_t clock_source, uint32_t *count)
	This function gets the current count of timer in the free run mode. More...
hal_gpt_status_t	hal_gpt_start_timer_ms (hal_gpt_port_t gpt_port, uint32_t timeout_time_ms, hal_gpt_timer_type_t timer_type)
	This function sets the expiration time in milliseconds and the timer mode, then starts the timer. More...
hal_gpt_status_t	hal_gpt_delay_ms (uint32_t ms)
	This function sets the delay time in milliseconds. More...
hal_gpt_status_t	hal_gpt_delay_us (uint32_t us)
	This function sets delay time in microseconds. More...
hal_gpt_status_t	hal_gpt_stop_timer (hal_gpt_port_t gpt_port)
	This function stops the timer only for oneshot mode and repeat mode. More...
hal_gpt_status_t	hal_gpt_get_duration_count (uint32_t start_count, uint32_t end_count, uint32_t *duration_count)
	This function calculates the count duration. More...

Modules
	Enum
	Typedef

Function Documentation

hal_gpt_status_t hal_gpt_deinit

(

hal_gpt_port_t

gpt_port

)

This function de-initializes the GPT timer.

After calling this function, the callback is cleared, the clock power is turned off, interrupts and GPT module are disabled.

Parameters

[in]

gpt_port

is the port number.

Returns

HAL_GPT_STATUS_OK, if the operation is successful.
HAL_GPT_STATUS_ERROR_PORT, if the gpt_port value is wrong.

See also

hal_gpt_init()

hal_gpt_status_t hal_gpt_delay_ms

(

uint32_t

ms

)

This function sets the delay time in milliseconds.

The maximum delay time = 1/GPT_clock * 0xffffffff.

Parameters

[in]

ms

is the delay time in milliseconds.

Returns

HAL_GPT_STATUS_OK, if the operation is successful.
HAL_GPT_STATUS_ERROR_PORT, if the gpt_port value is wrong.

hal_gpt_status_t hal_gpt_delay_us

(

uint32_t

us

)

This function sets delay time in microseconds.

The maximum delay time = 1/GPT_clock * 0xffffffff.

Parameters

[in]

us

is the delay time in microseconds.

Returns

HAL_GPT_STATUS_OK, if the operation is successful.
HAL_GPT_STATUS_ERROR_PORT, if the gpt_port value is wrong.

hal_gpt_status_t hal_gpt_get_duration_count	(	uint32_t	start_count,
		uint32_t	end_count,
		uint32_t *	duration_count
	)

This function calculates the count duration.

This API is to help user cover count value rollback problem. For example, if start_count < end_count, it means the count value has grown up from 0xffffffff to 0.

Parameters

[in]	start_count	is the value of start count.
[in]	end_count	is the value of end count.
[out]	duration_count	is the user's parameter pointer to get count duration.

Returns

HAL_GPT_STATUS_OK, if the operation is successful.
HAL_GPT_STATUS_INVALID_PARAMETER, if the duration_count is null.

hal_gpt_status_t hal_gpt_get_free_run_count	(	hal_gpt_clock_source_t	clock_source,
		uint32_t *	count
	)

This function gets the current count of timer in the free run mode.

Parameters

[in]	clock_source	is the clock source of the timer in the free run mode. For more details, please refer to Enum about hal_gpt_clock_source_t.
[out]	count	is the user's pointer to a parameter to get the count value.

Returns

HAL_GPT_STATUS_OK, if the operation is successful.

hal_gpt_status_t hal_gpt_get_running_status	(	hal_gpt_port_t	gpt_port,
		hal_gpt_running_status_t *	running_status
	)

This function gets the running status of the port as specified.

Parameters

[in]	gpt_port	is the port number.
[out]	running_status	is the pointer to the running status after the function returns. For more details about this parameter, please refer to hal_gpt_running_status_t.

Returns

HAL_GPT_STATUS_OK, if the operation is successful.
HAL_GPT_STATUS_ERROR_PORT, if the gpt_port value is wrong.

hal_gpt_status_t hal_gpt_init

(

hal_gpt_port_t

gpt_port

)

This function initializes the GPT base enironment.

Call this function if a timer is required.

Parameters

[in]

gpt_port

is the port number.

Returns

HAL_GPT_STATUS_OK, if the operation is successful.
HAL_GPT_STATUS_ERROR_PORT, if the gpt_port value is wrong.

See also

hal_gpt_deinit()

hal_gpt_status_t hal_gpt_register_callback	(	hal_gpt_port_t	gpt_port,
		hal_gpt_callback_t	callback,
		void *	user_data
	)

This function registers a callback function with the timer specified at the port.

The callback can only be registered when the timer, as specified by the port, is in HAL_GPT_STOPPED state. If the timer is in HAL_GPT_RUNNING state, the callback cannot be registered and this function returns HAL_GPT_STATUS_ERROR.

Parameters

[in]	gpt_port	is the port number.
[in]	callback	is the function pointer of the callback. This callback will be called when the timer expires.
[in]	user_data	is the pointer to the user defined data to pass to the callback function.

Returns

HAL_GPT_STATUS_OK, if the operation is successful.
HAL_GPT_STATUS_ERROR_PORT, if the gpt_port value is wrong.
HAL_GPT_STATUS_ERROR, if the callback registration failed.

hal_gpt_status_t hal_gpt_start_timer_ms	(	hal_gpt_port_t	gpt_port,
		uint32_t	timeout_time_ms,
		hal_gpt_timer_type_t	timer_type
	)

This function sets the expiration time in milliseconds and the timer mode, then starts the timer.

The function should only be called while the timer is stopped. An error would be returned if this function is called when the timer is running.

Parameters

[in]	gpt_port	is the port number.
[in]	timeout_time_ms	is the expiration time in milliseconds.
[in]	timer_type	is the timer mode, such as oneshot or repeat timer mode defined in hal_gpt_timer_type_t.

Returns

HAL_GPT_STATUS_OK, if the operation is successful.
HAL_GPT_STATUS_ERROR_PORT, if the gpt_port value is wrong.

hal_gpt_status_t hal_gpt_stop_timer

(

hal_gpt_port_t

gpt_port

)

This function stops the timer only for oneshot mode and repeat mode.

Parameters

[in]

gpt_port

is the port number.

Returns

HAL_GPT_STATUS_OK, if the timer is stopped successfully.
HAL_GPT_STATUS_ERROR_PORT, if the gpt_port value is wrong.