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 callback function registration.
A callback function must be registered using hal_gpt_register_callback(), then call hal_gpt_start_timer_ms() or hal_gpt_start_timer_us() 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.
Software timer supporting multiple users.
The software timer supports multiple users. It is based on GPT driver, and occupies the hardware GPT port.
The software timer uses GPT oneshot mode. The maximum number of users is 32. The unit of the software timer is milliseconds.

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.
  }
- For the timer whose unit of the tick count is microseconds, the hal_gpt_start_timer_us() works the same way as with hal_gpt_start_timer_ms().
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.
- Sample code:
  hal_gpt_delay_us(10); //Delay for 10 us.
Using software timer.
Call hal_gpt_sw_get_timer() to allocate a software timer handle.
Call hal_gpt_sw_start_timer_ms() to register the callback function and start the timer.
The unit of the software timer is milliseconds.
The software timer is a oneshot timer. To run the software timer continuously, call it again in its callback function. Call hal_gpt_sw_stop_timer_ms() to stop the running timer. If the timer is not running, the HAL_GPT_STATUS_ERROR is returned. Call hal_gpt_sw_get_remaining_time_ms() to get the remaining timeout value at any time. Call hal_gpt_sw_free_timer() to free the allocated timer resource.
- Step1: Call hal_gpt_sw_get_timer() to allocate a software timer handle.
- Step2: Call hal_gpt_sw_start_timer_ms() to register the callback function and start the timer.
- Step3: Call hal_gpt_sw_free_timer() to free the allocated timer if it's no longer in use.
- Sample code:
  uint32_t handle;
  //Get the allocated timer handle
  if (HAL_GPT_STATUS_OK != hal_gpt_sw_get_timer(&handle) ) {
  //error handler
  }
  //Set the timeout to 10 ms, and register the callback at the same time
  if(HAL_GPT_STATUS_OK != hal_gpt_sw_start_timer_ms(handle, 10, user_gpt_callback, NULL)) {
  //error handler
  }
  //....
  //Waiting for the timer to timeout.
  
  // Callback function.
  void user_gpt_callback (void *user_data)
  {
  // user's handler
  hal_gpt_sw_free_timer(handle); //If it's no longer in use.
  }

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_start_timer_us (hal_gpt_port_t gpt_port, uint32_t timeout_time_us, hal_gpt_timer_type_t timer_type)
	This function sets the expiration time in microseconds and the timer mode, then starts the timer. 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...

hal_gpt_status_t	hal_gpt_sw_get_timer (uint32_t *handle)
	This function allocates timer handle. More...

hal_gpt_status_t	hal_gpt_sw_free_timer (uint32_t handle)
	This function frees timer. More...

hal_gpt_status_t	hal_gpt_sw_start_timer_ms (uint32_t handle, uint32_t timeout_time_ms, hal_gpt_callback_t callback, void *user_data)
	This function starts the software timer. More...

hal_gpt_status_t	hal_gpt_sw_stop_timer_ms (uint32_t handle)
	This function stops the specified software timer. More...

hal_gpt_status_t	hal_gpt_sw_get_remaining_time_ms (uint32_t handle, uint32_t *remaing_time)
	This function gets the remaining timeout value of the specified software timer. 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_start_timer_us	(	hal_gpt_port_t	gpt_port,
		uint32_t	timeout_time_us,
		hal_gpt_timer_type_t	timer_type
	)

This function sets the expiration time in microseconds 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_us	is the expiration time in microseconds.
[in]	timer_type	is the timer mode, i.e. 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.

hal_gpt_status_t hal_gpt_sw_free_timer ( uint32_t handle )

This function frees timer.

Parameters

[in] handle is the handle of the timer to be freed.

Returns: HAL_GPT_STATUS_OK, if the operation is successful.
HAL_GPT_STATUS_INVALID_PARAMETER, if the handle is invalid.
HAL_GPT_STATUS_ERROR, for all other errors.

hal_gpt_status_t hal_gpt_sw_get_remaining_time_ms	(	uint32_t	handle,
		uint32_t *	remaing_time
	)

This function gets the remaining timeout value of the specified software timer.

Parameters

[in]	handle	is the handle of the timer to get the remaining time from.
[out]	remaing_time	is the pointer to the value of the remaining timeout, after the return of this function.

Returns: HAL_GPT_STATUS_OK, if the operation is successful.
HAL_GPT_STATUS_INVALID_PARAMETER, if the handle is invalid.
HAL_GPT_STATUS_ERROR, if the handle is not allocated.

hal_gpt_status_t hal_gpt_sw_get_timer ( uint32_t * handle )

This function allocates timer handle.

Parameters

[out] handle is an unsigned integer for accessing this timer. It's equivalent to an ID number of the timer.

Returns: HAL_GPT_STATUS_OK, if the operation is successful.
HAL_GPT_STATUS_ERROR, if a timer cannot be allocated.

hal_gpt_status_t hal_gpt_sw_start_timer_ms	(	uint32_t	handle,
		uint32_t	timeout_time_ms,
		hal_gpt_callback_t	callback,
		void *	user_data
	)

This function starts the software timer.

Parameters

[in]	handle	is the handle of the timer to be started.
[in]	timeout_time_ms	is the timeout value in milliseconds.
[in]	callback	is the callback to be registered with this timer. This callback will be called when the timer times out.
[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_INVALID_PARAMETER, if the parameter is invalid.
HAL_GPT_STATUS_ERROR, for all other errors.

hal_gpt_status_t hal_gpt_sw_stop_timer_ms ( uint32_t handle )

This function stops the specified software timer.

Parameters

[in] handle is the handle of the timer to be stopped.

Returns: HAL_GPT_STATUS_OK, if the operation is successful.
HAL_GPT_STATUS_INVALID_PARAMETER, if the handle is invalid.
HAL_GPT_STATUS_ERROR, for all other errors.

Overview

Terms and acronyms

Supported features

How to use this driver

Functions

Modules

Function Documentation