Libraries
Background
tollos.c – core code for Tollos
This module comprises the core functions for Tollos, including system startup, interrupt vector table management, timing, and the main scheduler that calls the application init() and tick() functions.
| Functions | |
|---|---|
| sysPause | delay for a number of milliseconds |
| sysQuery | query a system item |
| sysSet | set a system item |
| sysStartup | first function called after reset |
| sysTime | return timestamp |
| sysVector | set an interrupt vector address |
sysPause – delay for a number of milliseconds
void sysPause(uint ms);
ms – milliseconds to pause for (may be 0)
If ms is 0, sysPause returns immediately. Otherwise, it waits for an interval of at least ms−1 milliseconds and no more than ms milliseconds. If possible the processor will sleep while waiting (interrupts will be handled).
sysPause may be used in init() or later, but note that it does not extend the tick period, so if called within tick() the pause time should be less than the tick period.
sysQuery – query a system item
int sysQuery(uint item);
item – a constant listed in tollos.h
returns current value of the item, or −1 if the item is unknown
Valid items are all items valid for sysSet, and also:
SYS_CLOCK – processor clock speed, Hz
SYS_RESET – cause of last reset: 0=normal (POR or Reset pin), 1=unusual (Watchdog or Brownout)
SYS_STACKSIZE – total RAM available for stack, bytes
SYS_STACKUSED – maximum stack used since startup, bytes
SYS_TICKLAST – time used for last tick() call, microseconds (maximum 1000s)
sysSet – set a system item
int sysSet(uint item, int value);
item – a constant listed in tollos.h
value – value to set the item to
returns previous value of the item, or a negative number if the item is unknown or a bad value is given
Valid items are:
SYS_TICKMAX – maximum recorded tick() time, microseconds [0<=value]
SYS_TICKTIME – tick() call interval, microseconds [0<value]
SYS_WATCHDOG – watchdog interval, milliseconds [0<value<=10s]
SYS_TICKMAX can be set to any non-negative value, but typically only a value of 0 is used (to reset the ‘high water mark’). The maximum value for SYS_TICKMAX is clamped to 1000 seconds.
SYS_TICKTIME should be a multiple of the internal SysTick (currently 100us) for accurate tick timing.
Depending on the processor, SYS_WATCHDOG may be rounded up, possibly to a multiple of 4ms.
sysStartup – first function called after reset
void sysStartup(void);
This function sets up the hardware and runs the application as follows:
- initialize C statics
- initialize Interrupt Vector table in RAM
- initialize stack footprints (used for reporting stack usage)
- initialize processor clocks, PLL, etc.
- set up the default tick time (40 ms = 25 Hz)
- invoke the application init() function (if any)
- thereafter invoke the application tick() function (if any) at the appropriate interval.
This could be called explicitly to restart the processor and software, but note that peripherals will not receive a hardware reset.
sysTime – return timestamp
void sysTime(uint *seconds, uint *micros);
seconds – receives seconds since Tollos started
micros – receives microseconds in current second
Seconds and micros are set to the number of seconds and microseconds since the Tollos was started, rounded to the latest internal Tollos sysTick. The interval between internal sysTicks is 1000 microseconds (1ms), so micros will be a multiple of 1000.
The seconds counter will wrap approximately every 136.1 years.
sysVector – set an interrupt vector address
int sysVector(uint index, vector addr, uint level);
index – item # in vectors list (e.g., Watchdog is 0)
addr – address to set, or NULL to cancel handler
level – priority level; 0=highest, 15=lowest [all preempt]
returns 0 if the handler was changed to the new handle, or cancelled, successfully; 1 if the handler was already set as requested; −1 if the vector is already in use with a different handler and addr is not NULL; −2 if item is too large; −3 if the priority level is too large
Note that index is the vector number excluding the first 16 slots.
Setting an address automatically enables interrupts for that item, and cancelling it (with NULL) disables interrupts.
When enabling, the priority level of the interrupt is also set; a higher priority interrupt (smaller value for level) will preempt a lower priority.
The error checking here protects against attempted use of the same vector by two different handlers. It is not an error to replace a handler by itself (hence it is safe to always set a handler when needed), and the return code will indicate whether this was the first time it was set.