Temperature driver.
The Temperature driver provides services related to measuring and reacting to the current temperature of the chip and changes to it.
The two main services provided are:
Unlike most drivers, there is only a single instance of the temperature driver that is always available once Temperature_init() is called. Temperature_init() should be called once before using other Temperature driver APIs. Subsequent Temperature_init() calls will have no effect.
The most basic function of the driver is to provide the current temperature and return it. It is encoded as a signed integer in degrees C.
The other major function of the Temperature driver is to notify the application when the temperature changes and crosses an application-defined threshold.
There are three default usecases for this:
There are three functions that register a notification for the application:
Multiple notifications may be registered. The different parts of the application and drivers that need to respond to a temperature change do not need to know of one another. Each notification must have its own Temperature_NotifyObj and must be registered individually.
Once the chip temperature crosses the smallest high threshold or largest low threshold amongst the registered notifications, the driver will iterate over the entire list of registered notification and check which ones have triggered. Notifications that have triggered are removed from the list of registered notifications and thus are no longer registered. Their callback function is then invoked.
If an application wishes to reregister a notification that just triggered and was unregistered, it may register it again from within the notification callback or another context.
It is possible to determine whether the high or low threshold triggered the notification callback as follows:
Registered notifications are unregistered in two ways:
Unregistered notifications may be registered again at any time.
While the driver aims to supply and act on an accurate absolute temperature, there will be differences between the measured vs the true temperature due to inherent variances in the manufacturing process. The nature of these differences varies by device family.
Examples of such differences:
It is strongly recommended to read the device-specific Temperature driver documentation for details of the temperature sensor characteristics and how they might affect choices of threshold values.
Go to the source code of this file.
Data Structures | |
struct | Temperature_NotifyObj |
Temperature notify object structure. More... | |
Macros | |
#define | Temperature_STATUS_RESERVED (-32) |
#define | Temperature_STATUS_SUCCESS (0) |
Successful status code. More... | |
#define | Temperature_STATUS_ERROR (-1) |
Generic error status code. More... | |
Typedefs | |
typedef void(* | Temperature_NotifyFxn) (int16_t currentTemperature, int16_t thresholdTemperature, uintptr_t clientArg, Temperature_NotifyObj *notifyObject) |
Function prototype for a notification callback. More... | |
Functions | |
void | Temperature_init (void) |
This function initializes the Temperature driver. More... | |
int16_t | Temperature_getTemperature (void) |
Gets the current temperature in degrees C. More... | |
int_fast16_t | Temperature_registerNotifyHigh (Temperature_NotifyObj *notifyObject, int16_t thresholdHigh, Temperature_NotifyFxn notifyFxn, uintptr_t clientArg) |
Registers a notification with a high threshold. More... | |
int_fast16_t | Temperature_registerNotifyLow (Temperature_NotifyObj *notifyObject, int16_t thresholdLow, Temperature_NotifyFxn notifyFxn, uintptr_t clientArg) |
Registers a notification with a low threshold. More... | |
int_fast16_t | Temperature_registerNotifyRange (Temperature_NotifyObj *notifyObject, int16_t thresholdHigh, int16_t thresholdLow, Temperature_NotifyFxn notifyFxn, uintptr_t clientArg) |
Registers a notification with both a high and low threshold. More... | |
int_fast16_t | Temperature_unregisterNotify (Temperature_NotifyObj *notifyObject) |
Unregisters a currently registered notification. More... | |
int16_t | Temperature_getThresholdHigh (Temperature_NotifyObj *notifyObject) |
Get the high threshold of a notification. More... | |
int16_t | Temperature_getThresholdLow (Temperature_NotifyObj *notifyObject) |
Get the low threshold of a notification. More... | |
void | Temperature_getThresholdRange (Temperature_NotifyObj *notifyObject, int16_t *thresholdHigh, int16_t *thresholdLow) |
Get the high and low threshold of a notification. More... | |
uintptr_t | Temperature_getClientArg (Temperature_NotifyObj *notifyObject) |
Get the application-provided clientArg of a notification. More... | |
Temperature_NotifyFxn | Temperature_getNotifyFxn (Temperature_NotifyObj *notifyObject) |
Get the notifyFxn provided during registration. More... | |
#define Temperature_STATUS_RESERVED (-32) |
Common Temperature status code reservation offset. Temperature driver implementations should offset status codes with Temperature_STATUS_RESERVED growing negatively.
Example implementation specific status codes:
#define Temperature_STATUS_SUCCESS (0) |
Successful status code.
Functions return Temperature_STATUS_SUCCESS if the function was executed successfully.
#define Temperature_STATUS_ERROR (-1) |
Generic error status code.
Functions return Temperature_STATUS_ERROR if the function was not executed successfully.
typedef void(* Temperature_NotifyFxn) (int16_t currentTemperature, int16_t thresholdTemperature, uintptr_t clientArg, Temperature_NotifyObj *notifyObject) |
Function prototype for a notification callback.
[in] | currentTemperature | Current chip temperature |
[in] | thresholdTemperature | Temperature threshold that caused this notification callback. |
[in] | clientArg | Argument provided by the application during registration. |
[in/out] | notifyObject The notification object that was registered previously. This pointer may be used to register the notification again with updated inputs from within the notification callback. |
void Temperature_init | ( | void | ) |
This function initializes the Temperature driver.
This function initializes the internal state of the Temperature driver. It must be called before calling any other Temperature functions. Calling this function multiple times will only have an effect the first time.
int16_t Temperature_getTemperature | ( | void | ) |
Gets the current temperature in degrees C.
int_fast16_t Temperature_registerNotifyHigh | ( | Temperature_NotifyObj * | notifyObject, |
int16_t | thresholdHigh, | ||
Temperature_NotifyFxn | notifyFxn, | ||
uintptr_t | clientArg | ||
) |
Registers a notification with a high threshold.
This function registers a Temperature notification with a high threshold. Once the chip temperature rises above thresholdHigh
, notifyFxn
is called and the notification is automatically unregistered.
notifyObject | Structure to be initialized. After returning, it will contain the data necessary to issue a notification callback. The memory of the structure must persist while the notification is registered. | |
[in] | thresholdHigh | Threshold temperature in degrees C |
[in] | notifyFxn | Callback function that is called once the chip temperature rises above thresholdHigh . |
[in] | clientArg | Application-specified argument |
Temperature_STATUS_SUCCESS | The notification was successfully registered. |
Temperature_STATUS_ERROR | There was an error during registration. |
int_fast16_t Temperature_registerNotifyLow | ( | Temperature_NotifyObj * | notifyObject, |
int16_t | thresholdLow, | ||
Temperature_NotifyFxn | notifyFxn, | ||
uintptr_t | clientArg | ||
) |
Registers a notification with a low threshold.
This function registers a Temperature notification with a low threshold. Once the chip temperature falls below thresholdLow
, notifyFxn
is called and the notification is automatically unregistered.
notifyObject | Structure to be initialized. After returning, it will contain the data necessary to issue a notification callback. The memory of the structure must persist while the notification is registered. | |
[in] | thresholdLow | Threshold temperature in degrees C |
[in] | notifyFxn | Callback function that is called once the chip temperature falls below thresholdLow . |
[in] | clientArg | Application-specified argument |
Temperature_STATUS_SUCCESS | The notification was successfully registered. |
Temperature_STATUS_ERROR | There was an error during registration. |
int_fast16_t Temperature_registerNotifyRange | ( | Temperature_NotifyObj * | notifyObject, |
int16_t | thresholdHigh, | ||
int16_t | thresholdLow, | ||
Temperature_NotifyFxn | notifyFxn, | ||
uintptr_t | clientArg | ||
) |
Registers a notification with both a high and low threshold.
This function registers a Temperature notification with a high and low threshold. Once the chip temperature rises above thresholdHigh
or falls below thresholdLow
, notifyFxn
is called and the notification is automatically unregistered.
notifyObject | Structure to be initialized. After returning, it will contain the data necessary to issue a notification callback. The memory of the structure must persist while the notification is registered. | |
[in] | thresholdHigh | High threshold temperature in degrees C |
[in] | thresholdLow | Low threshold temperature in degrees C |
[in] | notifyFxn | Callback function that is called once the chip temperature falls below thresholdLow , or rises above thresholdHigh . |
[in] | clientArg | Application-specified argument |
Temperature_STATUS_SUCCESS | The notification was successfully registered |
Temperature_STATUS_ERROR | There was an error during registration |
int_fast16_t Temperature_unregisterNotify | ( | Temperature_NotifyObj * | notifyObject | ) |
Unregisters a currently registered notification.
This function unregisters a currently registered notification. It should not be called on a notifyObject
that is not currently registered.
notifyObject | Notification to unregister. |
Temperature_STATUS_SUCCESS | The notification was successfully unregistered. |
Temperature_STATUS_ERROR | There was an error during unregistration. |
notifyObject
with Temperature_registerNotifyHigh(), Temperature_registerNotifyLow(), or Temperature_registerNotifyRange() int16_t Temperature_getThresholdHigh | ( | Temperature_NotifyObj * | notifyObject | ) |
Get the high threshold of a notification.
This function should not be called on a notifyObject
registered with Temperature_registerNotifyLow(). The high threshold value returned in that case will be a device-specific invalid temperature.
notifyObject | Notification to get the high threshold of. |
notifyObject
with Temperature_registerNotifyHigh(), or Temperature_registerNotifyRange() int16_t Temperature_getThresholdLow | ( | Temperature_NotifyObj * | notifyObject | ) |
Get the low threshold of a notification.
This function should not be called on a notifyObject
registered with Temperature_registerNotifyHigh(). The low threshold value returned in that case will be a device-specific invalid temperature.
notifyObject | Notification to get the low threshold of. |
notifyObject
with Temperature_registerNotifyLow(), or Temperature_registerNotifyRange() void Temperature_getThresholdRange | ( | Temperature_NotifyObj * | notifyObject, |
int16_t * | thresholdHigh, | ||
int16_t * | thresholdLow | ||
) |
Get the high and low threshold of a notification.
This function should not be called on a notifyObject
registered with Temperature_registerNotifyLow() or Temperature_registerNotifyHigh(). The unconfigured threshold value returned in that case will be a device-specific invalid temperature.
notifyObject | Notification to get the high and low threshold of. | |
[out] | thresholdHigh | High threshold value in degrees C written back by this function. |
[out] | thresholdLow | Low threshold value in degrees C written back by this function. |
notifyObject
with Temperature_registerNotifyRange() uintptr_t Temperature_getClientArg | ( | Temperature_NotifyObj * | notifyObject | ) |
Get the application-provided clientArg of a notification.
notifyObject | Notification to get the clientArg of. |
notifyObject
with Temperature_registerNotifyHigh(), Temperature_registerNotifyLow(), or Temperature_registerNotifyRange() Temperature_NotifyFxn Temperature_getNotifyFxn | ( | Temperature_NotifyObj * | notifyObject | ) |
Get the notifyFxn provided during registration.
notifyObject | Notification to get the notifyFxn of. |
notifyObject
with Temperature_registerNotifyHigh(), Temperature_registerNotifyLow(), or Temperature_registerNotifyRange()