Multitasking for the PIC18F258.

• In this article I describe the MultitaskingBasic version which is ideally suited for educational purposes and can even be run on a PIC18F248. The added application will demonstrate timing and simple input/output processing.
• The MultitaskingCAN version will show the application of this system in a network for signalling alarm situations.

1. Introduction
2. Mission
3. New to C-programming?
4. Program elements
   • foreground/background
   • command
   • multitasking
   • timers
   • main data structures
   
5. Implementation
   • initialization
   • command parser
   • runlist
   • timers
6. Get started
   • application
   • add new commands
7. Used product----->
   

Introduction

• the need to manage larger projects.
• sharing intelligence with others.
• customer demand for readable code.
• the need to manage many projects.

• we are not going to use any class but, probably, use a collection of items that, given a particular analysis of the problem your program has to solve, are related to one another, and we will call this a structure.
• we are not going to instantiate anything but, maybe, use several identical collections of items, called structures, with each its own name, only to emphasize its independant use.
• we are not going to subclass anything but, maybe, reuse the source of one of our former projects and adapt its code.
• inheritance means that you probably got your intelligence from the genes of your ancestors and not that the behaviour of your program depends on a library you acquired in the past.

Mission

New to C-programming? NO!

• a structure is made, not only for us, to collect related data-items sensibly so that we can arrange our program in a way that it will be comprehensable to the outside world (including ourself) even after several years, but because C-compiler builders use this model to take us one step higher in abstraction level. The only thing we need to know is that they call the address of this structure a pointer. All data-items within the structure are accessed via the pointer. Use this pointer everywhere you can and they will do the rest.

fifoAlength      equ 128
fifoAstorage     ds  fifoAlength
fifoAstorepoint  db
fifoAgetpoint    db

• the reason why you will not use the term subroutine anymore but function instead is because of the higher abstraction level: you can call a function with one or more parameters and, even better, get a parameter in return. Imagine this parameter being a pointer. Now you will be able to program:

storeCharInFifo(&fifoA,getCharFromFifo(&fifoB));
// or: get a character from fifoB and store it in fifoA

Program elements

Foreground/Background

1. handle watchdog triggering.
2. do system output.
3. when the main high-speed timer ticks: decrement all currently allocated slow-speed timers until their expiration.
4. run the command-parser for all statically defined command structures.
5. the next runlist task.

Command

Multitasking

Timers

Main data structures

1. MACHINE: unites texts to parse and output upon execution as well as Taskdata. i.e.: "catalog\r\n", "Catalog:", &CatalogData
2. TASKDATA: defines type and number of arguments of the command, the functions to call upon entering the command and, once operating as a statemachine in the runlist, the statefunctions.
   i.e.: struct Taskdata CatalogData = {0,HEXARGUMENTS,enterCatalog,taskDelete};
   For clarity reasons the parsertexts are outside of this structure and united in the machine stucture.
3. COMMAND: as a command is given in a "multitasking" way, this structure is responsable of collecting valid command-characters, counting and storing arguments and ultimately delivering this information to the executeCommand function.
4. CHAR_QUEUE: circular buffer, mainly used for isolating foreground and background processing of characters.
5. STACKLINE: contains information about a running task. Stacklines are organized as linked list and every iteration of the backgroundloop executes a task from this list.
6. BYTETIMER only two bytes: the downcounting value and an initial value for restart.
7. BYTETIMERS: structure contains one BYTETIMER and info to enable creating a linked list of BYTETIMERS.

Implementation

Initialization

1. TBLPTRU = 0x00;
2. timer_a is initialized with a value read from eeprom and started.
3. The memoryspace for the list of bytetimers is initialized by setting the free-flag for every timer.
4. The function SysIo() is called to initialize the character queue's for input/output as well as the command structure asyncCommand, used for parsing commands from the async connection.
5. InitializeBoard() defines port i/o, initializes the usart and timer0 and then enables interrupts. The serial input interrupt is enabled after the first (and every) call to system input. At this moment a startupmessage is displayed and timers start ticking.
6. The general purpose command structure runlistCommand, is then used for executing the commands: "power-up" and "start".

#define CHAR_QUEUE struct CHAR_QUEUE
CHAR_QUEUE
{
   struct
   {
      BYTE Length;
      BYTE Storep;
      BYTE Getp;
   } CHAR_QUEUE_POINTERS;
   BYTE *Data;
};

Command parser

#define COMMAND struct Command
COMMAND
{
   BYTE menu_index;               // index to Machine[]
   BYTE argcount;                 // # of arguments entered
   BYTE arguments[MAX_ARGUMENTS]; // the arguments
   BYTE argument_counter;         // # of arguments while collecting
   BYTE no_of_command_chars;      // # of command-characters to enter
   BOOL mute;                     // if TRUE: no system output
   union
   {
      BYTE inputcharacter_counter;
      BYTE hexinputcharacter_counter;
   } charcounters;
   union
   {
      BYTE charinput[PARSER_MAX_COMMAND_CHARS+1];
      BYTE hexinput[HEX_ARGUMENT_CHARS+1];
   } input;
};
.
#define MACHINE struct Machine
MACHINE
{
   ROM char* tekst_to_parse;
   ROM char* tekst_to_display;
   ROM TASKDATA *task_data;
};
.
#define TASKDATA struct Taskdata
TASKDATA
{
   BYTE args;                     // max # of arguments this command may need
   ARGTYPE args_type;             // HEXARGUMENTS or BINARYARGUMENTS
   void (* ROM * ROM enter_func_array)(COMMAND*);
   void (* ROM * ROM task_func_array)(void);
} ;

Runlist

#define STACKLINE struct STACKLINE
STACKLINE
{
   STACKLINE *next;
   BOOL occupied;
   BYTE stack_data;               // command_list_index
   STATE_THREAD stackline_state;  // task-state
   THREAD_MODE stackline_mode;    // general purpose variable
};
.
.
// RUNMACHINE /////////////////////////////////////////
   if ((running_flag) && (runstack_head))
   {
// command_list_index: function call of current runline-state
      m[current_runline->stack_data].task_data->task_func_array[current_runline->stackline_state]();	

      if (current_runline->next == 0) current_runline = runstack_head;
      else current_runline = current_runline->next;
   }
// END OF RUNMACHINE
.
.

Timers

1. TMR0 enters the interrupt routine at 10 msec intervals. (see intrptlow.c)
2. xtal_timer is incremented in the interrupt routine every 10 msec. This value is used to enable comparing the xtal frequency of different nodes in a network as CAN performance heavily depends on this frequency.
3. timer_a is a maintimer and decremented in the interrupt every 10*(100/TICKS_PER_SECOND) msec. At TICKS_PER_SECOND=50, timer_a is decremented every 20 msec. timer_a is initialized by the command "timer" (see CMDtimer.c) and, normally, this command can be run at power-up with a value of 5. The expiration of timer_a is tested in the background and serves as signal to decrement all acquired slow-speed timers at a pace of 0,1 sec (5*20 msec) when timer-command 5 has been executed.
4. timer_a_counter is incremented at every expiration of timer_a and this value is used in the command "led" (see CMDled.c) to realize some blinking led patterns.
5. bytetimers are slow-speed timers that dynamically can be aquired from a pool. All acquired bytetimers in this pool are decremented at the expiration of timer_a. See command "beep" for an example of a beepercontrol-task with adjustable duty-cycle and # of beeps.

// Timer defines //////////////////////////////////////
#define BYTETIMER struct BYTETIMER
BYTETIMER
{
   TIMEBYTE time;    // time duration
   TIMEBYTE timing;  // time downcounting
.
#define BYTETIMERS struct BYTETIMERS
BYTETIMERS
{
   BYTETIMERS *next;
   BOOL occupied;
   BYTETIMER byteTimer;
};
.
.
BYTETIMER  timer_a;        // timer_a is the maintimer, decremented in the foreground
BYTETIMERS *bytetimers_head;
.
// Timer routine in background loop ///////////////////
// timer_a == 50 ticks/sec; time == 0x05 -> timer_a_counter_VALUE == 5/50 == 1/10 sec
   if (bytetimer_elapsed(&timer_a))
   {
      start_bytetimer(&timer_a);
      timer_a_counter++;
      decrement_bytetimers(&bytetimers_head);
   }
// END OF Timer routine ///////////////////////////////
.
.
// Timer subroutines //////////////////////////////////
void start_bytetimer(BYTETIMER *timer)   {timer->timing = timer->time;}
BOOL bytetimer_elapsed(BYTETIMER *timer) {return !(timer->timing);}
void decrement_bytetimers(BYTETIMERS **headp)
{
   BYTETIMERS *p;
   for (p = *headp; p ; p = p->next)
   {
      if (p->byteTimer.timing) p->byteTimer.timing-- ;
   }
}

Get started:

1. The xtalfrequency used in the hardware need to correspond with the macro: XTAL_xxMC in the file application.h. Only 3 frequency's are predefined. If any other xtal-value is used then a "Find in Project Files..." of this macro can help to determine the places to change timing values. The timers and baudratevalues will be affected by the xtalfrequency.
2. Input/output controlled in the example application comprises 2 inputs for switches and two outputs for a led and a beeper. The addresses are defined in the file in_out.h and must be adapted to the users' hardware. The hardware definitions for the async serial port are also set in this file.
3. When the code is compiled and programmed in the hardware, initially the data-eeprom must be cleared to all ff. Then the default baudrate for the serial port will be 57k. The hardware should start and display a version message and a prompt. The command "cat" will be helpfull in exploring the properties of the software. The first thing to do is to set the maintimer by: "tim05". Commands only need 3 characters and parameters are essentially in hexadecimal notation but must always be entered as two characters and no spaces. The command: "led01" should put itself in the runlist which is started by: "sta". As a result the led should start blinking.
4. To initialize an application, these commands can be put in eeprom and are then executed at power-up. Also some important constants can be put in eeprom. See the file eeprom.h. At a minimum the maintimer value (05) should be put at address MAIN_MASTERTIMER_VALUE_ADDRESS and at MASTER_STARTUP_LIST the initializing commands can be placed. If any command is put here then the start command is executed automatically. The "led01" command is put in eeprom by placing 0d, 01, ff at addresses 40h, 41h, 42h. (see the explanation of the startup command datablock in file eeprom.h) Commands are identified by their label defined in the file MainMachine.h.

Application

1. led: every time timer_a_counter equals the parameter given with the command, a led is set. A parametervalue of 7 deletes this (and other) task.
2. beep needs two parameters for setting the pace and dutycycle of a beeper and the number of beeps to display. A BYTETIMER is dynamically acquired in this task. This task deletes itself after the number of beeps given.
3. watch this task checks an input and displays to the serial port the number of background iterations during setting the input to ground. Only a signed wordcounter is used, so count until 32k...
4. input also checks an input and starts the beep task, upon activation of the input, with a number of beeps given as parameter in this command.

40: 0d 01 ff 0e 14 10 ff 0f ff 10 05 ff ........

Add new commands

1. copy the CMDxxxx-file and add the edited and renamed version to the project.
2. add the command to MACHINE m[] in file MainMachine.c
3. add the commandlabel and adjust the MAIN_MACHINE_SIZE in file MainMachine.h
4. recompile and optionally adjust the MASTER_STARTUP_LIST.

Copyright © CTM - R.G.Logchies