
			    README


    RTAI Watchdog module
    DM <davor.munda@kopica-sp.si>
    
    
    This Watchdog module is derived from original RTAI Watchdog module.
 Derivation is made to meet wishes by Iskra SISTEMI. To work properly,
 this module needs patched RTAI UP Scheduler running (rtai_sched_up).
 Scheduler patch is made by DM to compute spent processor time for every
 task. WD module also needs running RTAI timer (we start timer in the
 rtx_rtai module).
 
    Watchdog policy is "SUSPEND". This means that on error in RT processing
 all (ALL!) RT tasks are suspended (Watchdog task stays running). Watchdog 
 module has the highest RTAI priority.
 
    Watchdog error occurs when :
 - Periodic task could not meet his period for two times
 - Idle (Linux) task reaches less than 20% processor time in the last one second
 - In the system is task with the same priority as WD priority 
   
    There are implemented two RT FIFO interfaces (rtf0 and rtf1) for 
 communication with User Space application. Known user commands are :

 - read_rtstatus() : answer is WD_RUN_STATUS RT tasks are running 
                               WD_SUSPEND_STATUS RT tasks are suspended
			       WD_READSTATUS_ERR interface error

 - reset_uptimes() : result is WD_RESETTIME_OK all tasks processor times 
                                               are reseted to 0
			       WD_RESETTIME_ERR interface error

 - read_data(&no_tasks,&data,space_records) : 
    result is WD_READ_DATA_OK we have all requested tasks data
              WD_READ_DATA_MORE our data buffer is too small for all tasks data
	      WD_READ_DATA_ERR interface error;
    parameters are : &no_tasks - reference to number of all RT tasks 
                                 (Linux and WD are included)
		     &data - reference to the data buffer, data records contain
		             eight char name string
			     unsigned long task handle
			     long seconds of processor time from WD start/reset
			     long nano seconds of processor time remainder
		     space_records - no records space in the data buffer.
    We can get four different names : WD_LINUX_TASKNAME - Idle (Linux) task
                                      WD_SELF_TASKNAME - WD task
				      WD_OTHER_TASKNAME - for all other RT tasks
				      WD_OVERFLOW_TASKNAME - we have too many
				                             RT tasks in the 
							     system.
			
    Commands are implemented as C++ wd_class class methodes (file wd.hpp).
                                      

    We can not use Watchdog module with rtai_lxrt module. Before inserting 
 rtai_watchdog must remove rtai_lxrt (on the Arm target we don't use LXRT).
 
 
 ! Note: Edit Makefile to meet your environment
 

    Usage sample:
    
 - for OneShot system timer with WD period 500 micro seconds
 # insmod rtai_watchdog.o TickPeriod=500000
 
 - for Periodic system timer with WD period 1 milli second
 # insmod rtai_watchdog.o OneShot=0 TickPeriod=1000000
 
 
 ! Note that we must provide system timer earlier than WD module insertion 
   (insert rtx_rtai module before WD - we use Periodic timer) !
 
 ! Note that we must use patched UP Scheduler (patched rtai_sched_up module) !
 

