Important Library Features - PalouseRobosub/SUBLIBinal_AVR GitHub Wiki
Library Functionality
This page contains information pertaining to features used throughout the library. Please select the relevant topic from the list below.
Topics
Structure Declaration
When using the library, it is extremely important that structures are initialized to zero. When declaring structure variables, please use the following convention:
Timer_Config timer_configuration = {0};
This will ensure that all variables within the structure are initialized to 0. If structures are not initialized the zero, the library may work improperly. An example of this occurs if the callback function is not declared as NULL and does not point to an actual function. If this is the case, then the program will link to a function that does not exist and normal C execution will break as a result of a dangling reference.
The Callback Function
The callback function is used within almost every structure created by SUBLIBinal. The callback function is what drives interrupt driven designs. A callback function is simply a pointer to a function that will execute when an interrupt occurs. To supply a callback function, simply declare a function and hand a reference to it to the configuration structure. Please see the following example:
#include "sublibinal.h" //include the library header file
void foo() {
//implement functionality that will run when the timer interrupt occurs
}
void main() {
Timer_Config t_con = {0};
//... Fill out portions of the structure
t_con.callback = &foo; //supply a pointer to the function foo
initialize_Timer(t_con);
//...Complete other initialization
while (1) {
//Embedded system loop, implement what you would like in here!
}
}
The callback function provides expandable functionality to the interrupt service routines. The code provided in the callback function will be executed whenever the interrupt is triggered.
Please note: Callback functions will never return any values. Callback function input parameters are typically void. The exception to this is if the peripheral library utilizes a background process. If it does, it will require specific parameters. Please refer to the peripheral library specification to determine which input parameters to use.
The Background Process
The background process is used throughout SUBLIBinal for implementation of more complex designs. The background process is a process that is placed within the embedded system loop to ensure that interrupt driven programs are not routinely interrupted by time-intensive data management tasks. The background processes force all data processing to occur in a non-interrupt environment. This is useful when utilizing time-critical interrupts. The background process functions in removing nodes of data from buffers of information. The background process then takes a callback function from the node and calls the function with some provided parameter from the packet. When a function is called from the background process, it will universally need to accept parameters. Please refer to peripheral library specifications to determine what respective callback function parameters should be.