MT2523 API Reference  LinkIt SDK v4
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.

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.

How to use this driver

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_portis 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]msis 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]usis 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_countis the value of start count.
[in]end_countis the value of end count.
[out]duration_countis 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_sourceis 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]countis 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_portis the port number.
[out]running_statusis 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_portis 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_portis the port number.
[in]callbackis the function pointer of the callback. This callback will be called when the timer expires.
[in]user_datais 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_portis the port number.
[in]timeout_time_msis the expiration time in milliseconds.
[in]timer_typeis 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_portis the port number.
[in]timeout_time_usis the expiration time in microseconds.
[in]timer_typeis 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_portis 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]handleis 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]handleis the handle of the timer to get the remaining time from.
[out]remaing_timeis 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]handleis 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]handleis the handle of the timer to be started.
[in]timeout_time_msis the timeout value in milliseconds.
[in]callbackis the callback to be registered with this timer. This callback will be called when the timer times out.
[in]user_datais 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]handleis 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.