weAut_01 / weAutSys    R 2.2.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Files | Defines | Functions | Variables
System threads
+ + System services (threading, time keeping, communication) + +

Overview

System threads as well as the user / application threads are implemented as protothreads. A system thread runs regularly or event driven and handles basic operation system (OS) tasks and services.

Normally to the user / application software (writer) the system threads are of no concern. As a rule a periodic ("cyclic") system thread is always scheduled before a user thread of the same frequency and it is that system thread that sets or increments the user thread's flag to signal the periodic task is due. So before this due signal all system time keeping and else duties can be assumed done.


Files

file  syst_threads.h
 

weAutSys' system threads


Defines

#define ABSsecADJ   0x80
 absolute date time seconds were adjusted
#define ABSsecSET   0x40
 absolute date time seconds were set
#define exitNotFlaggedThread(thread)
 Exit a not flagged user / application thread.
#define NO_SPMIN_SAMPLE   0
 Do not sample the stack pointer and update its minimal value.
#define resetAppThread(thread)
 Reset respectively initialise an user / application thread.
#define runOutSysInfoThread(parent, pt, toStream)
 Start (spawn) the outSysInfoThreadF thread as child.
#define SAMPLE_MIN_SP(nonc)
 Sample the stack pointer and update its minimal value.
#define scheduleAppThread(thread)
 Unconditionally schedule an user / application thread.
#define scheduleFlgdAppThread(thread)
 Schedule a flagged user / application thread.
#define scheduleRegdAppThread(thread)
 Schedule a registered user / application thread.
#define scheduleYldAppThread(thread)
 Schedule a flagged or yielding user / application thread.
#define SINCsINCR   0x01
 run since seconds were incremented

Functions

uint8_t addr3Here (void)
 Get the upper (bit 16 ...) part of the current address.
uint32_t addrHere (void)
 Get the current address.
void goto_P (void *labelAsValue)
 Go to a label (as value) and stay within the 64Kword page.
void initOutFlashTextThread (outFlashTextThr_data_t *outFlashTextThread, char const *const *theFlashStrings2out, uint8_t noOfFlashStrings2out)
 Initialise the output a flash string array to standard output thread.
void initSetAppThread (struct mThr_data_t *thread, p2ptFun threadF)
 Register and (force) init an user / application thread.
void initThreads (void)
 Initialise the threads.
ptfnct_t outFlashTextThreadF (outFlashTextThr_data_t *outFlashTextThread, FILE *toStream)
 Output a flash string array to standard output thread.
ptfnct_t outSysInfoThreadF (pt_t *pt, FILE *toStream)
 Output some system (version) info, the thread function.
p2ptFun registerAppThread (struct mThr_data_t *thread, p2ptFun threadF)
 Register an user / application thread.
ptfnct_t sys100msThread (void)
 The 100 milliseconds system thread, the function.
void sys1msThread (void)
 The milliseconds system function (or thread)
ptfnct_t sys1sThread (void)
 The 1 second system thread, the function.

Variables

uint16_t minStckP
 Minimal stack pointer value sampled.
struct pt ptSys100msThread
 The 100 milliseconds system thread, the (raw) Protothreads datastructure.
struct pt ptSys1sThread
 The 1 second system thread, the (raw) Protothreads datastructure.
uint8_t sys100msPeriodFlag
 Flag for system 100ms thread.
uint8_t sys1sPeriodFlag
 Flag for system 1s thread.

Define Documentation

#define NO_SPMIN_SAMPLE   0

Do not sample the stack pointer and update its minimal value.

To hinder the sampling the minimal stackpointer define the macro NO_SPMIN_SAMPLE with a value of 1.

#define SAMPLE_MIN_SP (   nonc)

Sample the stack pointer and update its minimal value.

The minimal stackpointer will be updated at the point of calling this, if the macro NO_SPMIN_SAMPLE is undefined or 0.

Parameters:
noncnumber of nested function calls within embedding function
The value should be in the range 0..3.
If the call hierarchy goes deeper or the functions called use local variables those functions called should sample self.
#define runOutSysInfoThread (   parent,
  pt,
  toStream 
)

Start (spawn) the outSysInfoThreadF thread as child.

Parameters:
parent(type pt) the calling parent's thread raw (!) stucture
ptthe thread's to be called raw (!) stucture
toStreamstreams to switch the standard streams to (if not MULL)
Examples:
main.c.
#define resetAppThread (   thread)

Reset respectively initialise an user / application thread.

This is a macro: Do set the parameter as name (i.e. the_thread) and not as a pointer to resp. address of (not &the_thread).

Parameters:
thread(type mThr_data_t) the thread to reset.
#define scheduleRegdAppThread (   thread)

Schedule a registered user / application thread.

This macro will schedule the thread provided as parameter if it has a thread-function registered.

Besides checking this condition its like scheduleAppThread(thread).

Parameters:
thread(type mThr_data_t) the thread to schedule; must not be NULL.
#define scheduleAppThread (   thread)

Unconditionally schedule an user / application thread.

This macro will schedule the thread provided as parameter. As this is done unconditionally the caller is responsible for two hard pre-conditions

  1. thread must not be NULL
  2. thread.regd must be true

This is a macro, set the parameter as name (thread) and not as pointer to / address of. (That means not use &thread)

Parameters:
threadthe thread to reset; must not be NULL.
#define scheduleFlgdAppThread (   thread)

Schedule a flagged user / application thread.

This macro will schedule the thread provided as parameter if its flag is set (and it has a thread-function registered).

Besides checking this condition its like scheduleRegdAppThread(thread).

Parameters:
threadthe thread to schedule; must not be NULL.
#define scheduleYldAppThread (   thread)

Schedule a flagged or yielding user / application thread.

This macro will schedule the thread provided as parameter if its flag is set or it has ended by yielding or waiting on its last schedule.

Besides checking this ORed run conditions its like scheduleFlgdAppThread(thread).

Parameters:
thread(type mThr_data_t) the thread to schedule; must not be NULL.
#define exitNotFlaggedThread (   thread)

Exit a not flagged user / application thread.

This macro will exit the thread provided as parameter if its flag is not set.

See also:
PT_EXIT
PT_EXITED
Parameters:
thread(state type mThr_data_t) the thread to conditionally exit; must not be NULL.
Examples:
main.c.

Function Documentation

void goto_P ( void *  labelAsValue)

Go to a label (as value) and stay within the 64Kword page.

This procedure is a helper to implement Adam Dunkels' Protothreads with labels as values on large ATmegas with more than 128K flash.

Hint / Warning: This does only work (respectively has to be used) as long as a) there are no 24 bit void pointers and b) the trampolin (+ linker relaxation) hack is not in effect. As of January 2014 both a) and b) are true for arv-gcc — hence do not use this (see TRAMPOLIN_USE).

Parameters:
labelAsValuethe target (jump) address' lower 16 bit
Returns:
byte 3 of return address or 0
uint8_t addr3Here ( void  )

Get the upper (bit 16 ...) part of the current address.

This function is a helper to implement Adam Dunkels' Protothreads with labels as values on large ATmegas with more than 128K flash.

Returns:
byte 3 of return address or 0
See also:
goto_P
addrHere
uint32_t addrHere ( void  )

Get the current address.

This function returns the address from where it was called — or to be exact, the flash address behind the instruction calling this function.

Returns:
calling address +2; the number of relevant bits depends on the flash size
void sys1msThread ( void  )

The milliseconds system function (or thread)

This thread is scheduled by the runtime very often (high priority). It does work on the condition that one or more ms-ticks occurred since its last schedule. Otherwise it returns / yields at once.

This thread function does

  • the basic time keeping for the timed scheduling of other system and user threads,
  • the handling of timers with milliseconds resolution,
  • the basic process digital / analougue input (DI / AI) handling and filtering,
  • some time critical flow / overload control on communication links as well as
  • the main polling of the Ethernet driver ENC28J60 every 10 ms.

In normal operation this function should be called at least twice every ms. But if other processor tasks inhibit this it is quite capable to handle several events (= ms ticks) at once. Nevertheless, in case of more than 10 resp. 100 collected ticks the scheduling of user and system threads might come offbeat as well as the sequence of effects of lapsed timers.

In case of more than 250 collected ticks, all might go wrong.

Internal remark: This function is (still) called "...Thread" as it could as well organised as one (as it once was). On the other hand the system 1ms actions have to be handled in one optimised compact action without yielding and blocking. So the (small) Protothreads overhead is skimped at the moment.

The 100 milliseconds system thread, the function.

This thread is scheduled quite often (high priority). It yields internally until sys100msPeriodFlag is set.

This system thread handles the watchdog and does all periodic timing for the Ethernet stack uIP.

See also:
ptSys100msThread
ptfnct_t sys1sThread ( void  )

The 1 second system thread, the function.

This thread is scheduled repeatedly (medium priority). It yields internally or exits until sys1sPeriodFlag is set.

It does all date / time and timer with seconds resolution handling.

See also:
ptSys1sThread;
void initThreads ( void  )

Initialise the threads.

Besides some other initialisations this will de-register all user / application threads.

See also:
pt.h
ptfnct_t outSysInfoThreadF ( pt_t pt,
FILE *  toStream 
)

Output some system (version) info, the thread function.

This thread will output some system info, like
name, version, copyright, build and so on to the standard output. This is meant for system start respectively welcome info. This thread will usually started as child thread (of pt) by the macro runOutSysInfoThread(parent, pt, toStream) .

As the multi-line output may be longer than toStream's output buffer this thread will repeatedly yield until buffer space is available. If started as child thread the parent thread will "inherit" these blocks or waits.

Parameters:
ptthe thread state (pointer to raw structure; not NULL)
toStreamstreams to switch the standard streams to (if not MULL)
Returns:
PT_YIELDED if waiting for conditions that may become automatically true; PT_WAITING if blocked by conditions that other's action may set true; PT_EXITED if stopped by conditions that never will become true (sorry, not all work done and never will; PT_ENDED if ready with all work
ptfnct_t outFlashTextThreadF ( outFlashTextThr_data_t outFlashTextThread,
FILE *  toStream 
)

Output a flash string array to standard output thread.

This thread will output a number of strings in flash memory given as an array of pointers to them by initialising the thread with initOutFlashTextThread.
The initialising must be done before starting the thread.

This thread will block (multiple times) until the output buffer has enough space.
If started as child thread the parent thread will "inherit" these blocks or waits as yields.

Parameters:
outFlashTextThreadthe thread state data
toStreamstreams to switch the standard streams to (if not MULL)
Returns:
PT_YIELDED if waiting for conditions that may become automatically true; PT_WAITING if blocked by conditions that other's action may set true; PT_EXITED if stopped by conditions that never will become true (sorry, not all work done and never will; PT_ENDED if ready with all work
void initOutFlashTextThread ( outFlashTextThr_data_t outFlashTextThread,
char const *const *  theFlashStrings2out,
uint8_t  noOfFlashStrings2out 
)

Initialise the output a flash string array to standard output thread.

After this call the thread outFlashTextThreadF() will (block and) work until noOfFlashStrings2out strings were output or a NULL is found in theFlashStrings2out which is considered as end of the array.

Parameters:
outFlashTextThreadthe thread state data
theFlashStrings2outpointer to (flash) array of (flash) strings to be output
noOfFlashStrings2outnumber of (flash) strings to be output
p2ptFun registerAppThread ( struct mThr_data_t thread,
p2ptFun  threadF 
)

Register an user / application thread.

Parameters:
threadthe thread to register to; must not be NULL.
threadFthe thread function to be registered; NULL means de-register the thread
Returns:
the previously registered thread function; NULL if there was none
See also:
initSetAppThread(struct mThr_data_t *, p2ptFun);
Examples:
main.c.
void initSetAppThread ( struct mThr_data_t thread,
p2ptFun  threadF 
)

Register and (force) init an user / application thread.

This function will register threadF with thread unconditionally and init / reset all. It is meant for first initialisation.

Note:
Never call more than once with the same parameters and never call on a started thread. The results may be unwelcome to put it very mildly. If the situation is unclear in that respect, use registerAppThread(mThr_data_t, p2ptFun) instead.
Parameters:
threadthe thread to register to; must not be NULL.
threadFthe thread function to be registered; NULL means de-register the thread
See also:
registerAppThread(struct mThr_data_t *, p2ptFun )

Variable Documentation

uint16_t minStckP

Minimal stack pointer value sampled.

System and application software might sample the stackpointer at due points and set this variable to it if larger. A value of 0xFFFF means no (new) samples taken as yet. The recipe to sample the stackpointer SP and update its minimal value is

    uint16_t value = SP;
    if (value < minStckP) minStckP = value; // sample stackpointer 

Flag for system 100ms thread.

This flag will be set by (the time keeping part of) the 1ms thread sys1MsThread.

uint8_t sys1sPeriodFlag

Flag for system 1s thread.

This flag will be set by (the time keeping part of) the 1ms thread sys1msThread.
Bit 0: "run since" seconds were incremented
Bit 7: "absolute date time" seconds were incremented / adjusted
Bit 6: "absolute date time" seconds were set (heavily changed)