hostside/safety.h

   1 /**/
   2
   3 #ifndef SAFETY_H
   4 #define SAFETY_H
   5
   6 /*========== basic types etc. ==========*/
   7
   8 typedef unsigned short TrainNum;
   9 typedef unsigned short SegmentNum;
  10 typedef unsigned short LocationNum;
  11 typedef unsigned short MovPosComb;
  12 typedef unsigned char Small;
  13 typedef short TimeInterval;
  14 typedef short Distance;
  15 typedef char Speed; /* non-negative, units of 4mm/s */
  16
  17 /*========== state of the layout ==========*/
  18
  19 typedef struct {
  20   SegmentNum foredetect;   /* train's detectable part is at most maxinto   */
  21   Distance maxinto, uncertainty;   /*   into foredetect but train may be   */
  22   unsigned                         /*   uncertainty less far advanced      */
  23     backwards:1; /* train is moving backwards wrt its own front and back */
  24   Speed speed;
  25 } TrainState;
  26
  27 typedef struct {
  28   unsigned
  29     owned:1, /* this track segment is reserved for a train */
  30     tr_backwards:1, /* train's motion is (would be) backwards wrt track */
  31     movfeat_moving:1, /* feature(s) have been told to change to movposcomb */
  32     cm_autostop:1, /* train should stop on detection */
  33     seg_inverted:1, /* polarity is inverted */
  34     tr_updated:1; /* for use by safety.c:lay_train etc.; otherwise 0 */
  35   TimeInterval until_here, /* ) nonnegative; */  /* ) always valid but */
  36     until_detect;          /* ) 0 if already */  /* )  only meaningful */
  37   TrainNum owner;                                /* )  iff owned       */
  38   MovPosComb movposcomb;
  39   /*polarity?*/
  40 } SegmentState;
  41
  42 typedef struct {
  43   unsigned next_backwards:1;
  44   SegmentNum next;
  45 } SegmentLinkInfo;
  46
  47 typedef struct {
  48   const char *pname;
  49   Small posns;
  50   MovPosComb weight;
  51 } MovFeatInfo;
  52
  53 typedef struct {
  54   const char *pname;
  55   SegmentLinkInfo backwards, forwards;
  56   Distance dist;
  57 } SegPosCombInfo;
  58
  59 typedef struct {
  60   const char *pname;
  61   unsigned invertible:1;
  62   Small n_movfeats;
  63   const MovFeatInfo *movfeats;
  64   MovPosComb n_poscombs;
  65   const SegPosCombInfo *poscombs;
  66   Small board, object;
  67 } SegmentInfo;
  68
  69 typedef struct {
  70   Speed maxspeed;
  71   Distance tail, detectable, head;
  72   const char *pname;
  73 } TrainInfo;
  74
  75 extern const TrainInfo info_trains[NUM_TRAINS];
  76 extern const SegmentInfo info_segments[NUM_SEGMENTS];
  77
  78 typedef struct {
  79   TrainState trains[NUM_TRAINS];
  80   SegmentState segments[NUM_SEGMENTS];
  81 } State;
  82
  83 extern State s;
  84
  85 /*========== safety.c ==========*/
  86 /*
  87  * safety.c is responsible for ensuring that things don't go
  88  * physically wrong (eg, collisions, derailments, short circuits,
  89  * etc.).
  90  */
  91
  92 void safety_emergencystop(TranNum);
  93   /* Callable directly in response to application command. */
  94
  95 void safety_requestspeed(TrainNum tran, long newspeed);
  96   /* To be called only by the speed manager, thus indirectly from
  97    * user request.
  98    * Will result in a call to speedmanager_speedchange_notify (and of
  99    * course to actual_setspeed.  Speed manager must apply accel/decel
 100    * curve so that if safety.c agrees the command, the actual speed of
 101    * the train changes straight away (at least for decel).
 102    */
 103
 104 void safety_notify_detection(SegmentNum segn);
 105   /* To be called by actual.c when new train detection occurs. */
 106
 107 /*========== speedmgr.c ==========*/
 108
 109 void speedmanager_speedchange_notify(TrainNum tran);
 110   /* To be called only by safety.c, whenever speed is actually set.
 111    * New speed has already been recorded in State. */
 112
 113 /*========== actual.c ==========*/
 114 /* actual.c should only be called from safety.c.
 115  * It is responsible for communicating with the PICs, including
 116  * repeating the NMRA commands and redacting detection information.
 117  *
 118  * In general, when State information is shared between actual.c
 119  * and safety.c, actual.c is responsible for modifying State, and
 120  * will then call an actual_... function to notify the change.
 121  */
 122
 123 void actual_setspeed(TrainNum tran);
 124
 125 void actual_inversions_start(void);
 126 void actual_inversions_segment(SegmentNum);
 127 void actual_inversions_done(void);
 128   /* safety.c will call these in this order: first start, then segment
 129    * for 0 or more segments (whose inversion may or may not have
 130    * changed), and finally done.  At done, the PICs should be told to
 131    * (de)invert the segments as specified.
 132    */
 133
 134 /*
 135  *
 136  * Entrypoints are:                  Called from, and as a result of:
 137  *   actual_setspeed                    safety.c
 138  *   actual_emergencystop               safety.c
 139
 140
 141 /*========== utils.c ==========*/
 142
 143 typedef struct TrackLocation TrackLocation;
 144 struct TrackLocation { /* transparent, and manipulable by trackloc_... fns */
 145   SegmentNum segn; /* current segment */
 146   long into; /* distance from start of segment */
 147   unsigned backwards:1; /* if 1, into is positive and measured from end */
 148 };
 149
 150 long trackloc_remaininseg(const TrackLocation *tloc);
 151   /* Returns dist that tloc can advance before it goes into next segment. */
 152
 153 void trackloc_further(TrackLocation *tloc, long *remain_io);
 154   /* Advances tloc, decrementing *remain_io, until either
 155    * *remain_io becomes zero, or tloc->segn changes. */
 156
 157 void trackloc_reverse(TrackLocation *tloc);
 158   /* Reverses tloc without changing its actual location. */
 159
 160 const SegmentLinkInfo *trackloc_segmentlink_near(const TrackLocation *tloc);
 161 const SegmentLinkInfo *trackloc_segmentlink_far(const TrackLocation *tloc);
 162
 163 #endif /*SAFETY_H*/