SFBSerial.h

Go to the documentation of this file.

/*                                       -*- mode:C++; fill-column: 100 -*-
  SFBSerial.h - 'Platform-independent' serial port support
  Copyright (C) 2008 The Regents of the University of New Mexico.  All rights reserved.

  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
  version 2.1 of the License, or (at your option) any later version.

  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this library; if not, write to the Free Software
  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
  USA

  $Id$
*/

#ifndef SFBSERIAL_H
#define SFBSERIAL_H

#include "SFBConstants.h"       /* For FACE_COUNT */
#include "SFBAlarm.h"           /* For SFBAlarmIndexType */ 
#include "SFBReactor.h"         /* For PacketHandler, DispatchHandler, Body */ 
#include "SFBHWSerial.h"        /* For hardware-specific serial support */ 
#include "SFBPrint.h"           /* For facePrint* */ 

enum StandardBaudRateCodes {
  SFBAUD300 = 0,                
  SFBAUD1200 = 1,               
  SFBAUD9600 = 2,               
  SFBAUD57600 = 3,              
  SFBAUD115200 = 4,             
  SFBAUD230400 = 5,             
  SFBAUD500000 = 6,             
  SFBAUD1000000 = 7,            
  SFBAUD2000000 = 8,            
  SFBAUD3000000 = 9,            

  SFBAUD_CODE_COUNT = 10,       

  SFBAUD_RENDEZVOUS = 2         





};

extern int getStandardBaudCode(u32 baudCodeOrRate) ;

extern u32 getStandardBaudRate(u32 baudCode) ;

class SFBSerial {

public:

  void begin() ;

  void begin(u32 baud, bool manual = true) ;

  void reserve() ;            

  void end() ;
  /* The endless, hideous print routines.. */
  void print(const char * str) {         facePrint(face,str); } 

  void print(const u8 * str, u32 len) {  facePrint(face,str,len); } 

  void print(int decimal) {              facePrint(face,decimal); }

  void print(unsigned int decimal) {     facePrint(face,decimal); }

  void print(long decimal) {             facePrint(face,decimal); }

  void print(unsigned long decimal) {    facePrint(face,decimal); }

  void print(long decimal, int code) {   facePrint(face,decimal,code); }

  void print(double val) {               facePrint(face,val); }

  void println() {                       facePrintln(face); }

  void println(const char * str) {       facePrintln(face,str); }

  void println(const u8 * str, u32 len) {facePrintln(face,str,len); }

  void println(int decimal) {            facePrintln(face,decimal); }

  void println(unsigned int decimal) {   facePrintln(face,decimal); }

  void println(long decimal) {           facePrintln(face,decimal); }

  void println(unsigned long decimal) {  facePrintln(face,decimal); }

  void println(long decimal, int code) { facePrintln(face,decimal,code); }

  void println(double val) {             facePrintln(face,val); }

  void printlnCheckByte() ;
  bool isInUse() ;  

  bool isManualMode() ; 

  bool isReflexMode() ; 

  bool isConsciousMode() ; 

  void switchToBlocking() ;
  
  u32 getBaud() { return baud; } 

  bool getOddParity() { return flags&FLAG_ODD_PARITY; } 

  u32 getFace() { return face; }  

  bool ready() ;

  u32 inputBufferUsed() ;
  u32 outputBufferUsed() ;
  u32 inputBufferFree() ;
  u32 outputBufferFree() ;
  u32 brokenPackets() { return brokenPacketCount; }
  void incrBrokenPacketCount() { ++brokenPacketCount; }

  SFBHWSerial & getHWSerial() { return hwSerial; }

  bool backgroundProcessingActive() ;


  bool available() ;

  int read();

  int peek();


  u8 * readPacket();


  void setPreferredBaudCode(u8 code, bool renegotiateNow = false) ;

  bool dispatch(DispatchHandler dispatcher = 0, u32 maxPackets = 1) ;

  void suppress(const char type) ;
  void allow(const char type) ;

  void reflex(const char type, PacketHandler pfunc) ;

  void otherwise(PacketHandler pfunc) ;


  void putcInterrupt(u8 byte) ;

  void terpriInterrupt() ;

  void putcBlocking(u8 byte) ;

  void terpriBlocking() ;

  void write(u8 byte) { lowPutc(byte); }
  void write(const char * str) { print(str); }
  void write(u8 * buf, u32 len) { print(buf,len); }

  void flush() ;

  SFBSerial(int face) ; 


  static void startup_initialization() ;

  //XXX
private:

  /* Low-level internal routines so BRN routines can talk before BRN is complete.. */
  void lowPrint(const char * str) ;
  void lowPrintln(const char * str) ;
  void lowPutc(const u8 byte) ;
  void lowTerpri() ;
  void lowPrintOurBRO() ;        /* Print our current baud rate offer */ 

  void maybeBlockForOutput() ;  /* Block until output space available, if we're FLAG_BLOCKING */ 

  static PacketBuffer sharedBuffer;

  SFBHWSerial hwSerial;        /* Platform-specific state and methods */

  u32 baud;
  u32 nextTimeout;             /* when we're next to act */ 
  u32 brokenPacketCount;       /* how many inbound packets were dead */ 
  SFBAlarmIndexType alarmNumber; /* Our alarm number, if != 0 */ 
  const u8 face;                 
  u8 flags;
  u8 state;                    /* Current state in BRN state machine */ 
  u8 preferredCode;            /* Our current preferred baud rate code */ 
  u8 selectedCode;             /* negotiated baud rate code */ 
  bool selectedOdd;            /* negotiated odd parity (else none) */ 
  bool haveBufferedByte;       /* for ::available() */ 
  u8 bufferedByte;
  enum {
    STATE_RESET,                /* 0 Entered to send a reset packet */ 
    STATE_INIT,                 /* 1 Initial state */ 
    STATE_LISTEN,               /* 2 Sending/waiting for SIM */ 
    STATE_OFFER,                /* 3 Sent/waiting for SB */ 
    STATE_CONFIRM,              /* 4 Sent/waiting for SS */ 
    STATE_WAIT,                 /* 5 Delay after baud changed */ 
    STATE_DONE,                 /* 6 BRN finished */ 
    STATE_SHOWTIME,             /* 7 Queueing and dispatching packets */ 
    STATE_CHECKIN,              /* 8 SRU sent to request SIM */ 
    MAX_STATES
  };

  enum {
    FLAG_RUNNING =   0x01,     /* Port is in use (on our side.  This doesn't imply a live connection.) */
    FLAG_ODD_PARITY= 0x02,     /* Port is using odd parity (vs no parity) */
    FLAG_CONSCIOUS = 0x04,     /* Port is under conscious control - no BRN or bkgd packets will be sent */
    FLAG_BRN_DONE  = 0x08,     /* Baud rate negotiation has succeeded or is under conscious control */
    FLAG_BLOCKING_BYTES= 0x10, /* Port is running in byte-by-byte mode, with blocking output */
    FLAG_GPIOS     = 0x20,     /* Port pins are in use as non-UART pins, we can't touch them */
    FLAG_CONNECTED = 0x40,     /* We have received data lately on this face; there's something out there */
    FLAG_RSRVD8    = 0x80      /* Reserved */
  };

  void start(u32 baud, u8 startFlags) ;

  void stop() ;

  void setBaudRate(u32 baud, bool isOddParity = false) ;

  void setOddParity(bool isOdd) {
    if (isOdd) flags |= FLAG_ODD_PARITY;
    else flags &= ~FLAG_ODD_PARITY;
  }

  typedef void (*InitHandler)(u8 face);
  static const char backgroundProcessorTypes[];
  static const PacketHandler backgroundProcessorHandlers[];
  static const InitHandler backgroundProcessorInits[];

  void backgroundProcessingInit() ;

  static void stateTimeout(u32 when, void * arg) ;

  void step(u32 when, u8 * spacket) ; /* Step the state machine.  spacket==0 means timeout occurred */

  bool stepInit(u32 when, u8 * spacket) ; /* step in state INIT */
  bool stepListen(u32 when, u8 * spacket) ; /* step in state LISTEN */
  bool stepOffer(u32 when, u8 * spacket) ; /* step in state OFFER */
  bool stepConfirm(u32 when, u8 * spacket) ; /* step in state CONFIRM */
  bool stepWait(u32 when, u8 * spacket) ; /* step in state WAIT */
  bool stepDone(u32 when, u8 * spacket) ; /* step in state DONE */
  bool stepShowtime(u32 when, u8 * spacket) ; /* step in state SHOWTIME */
  bool stepCheckin(u32 when, u8 * spacket) ; /* step in state CHECKIN */

  void setState(u8 newState, u32 aboutHowManyMs) ;

  static void ppacketDispatcher(u8 * packet) ;

  static void rpacketDispatcher(u8 * packet) ;

  static void spacketDispatcher(u8 * packet) ;
  static void spacketInit(u8 face) ;

};
   
/* The one-time serial startup code */
extern void serial_startup_initialization() ;

/* Some utility functions for packet handling */
extern bool zPacketPrefix(u8 * p1, const char * to) ;
extern bool packetPrefix(u8 * p1, const u8 * to, const u32 len) ;

extern SFBSerial Faces[FACE_COUNT]; // Declared here but defined in SFBHWSerial(Board|Host)
#define NorthFace Faces[NORTH]      
#define SouthFace Faces[SOUTH]      
#define EastFace Faces[EAST]        
#define WestFace Faces[WEST]        

/* Make just plain 'Serial' be the same as 'NorthSerial',
 * so that Arduinoish code will have some place to go.
 *
 * Ditto for 'Serial1', etc, so Arduino Mega examples can fly
 */
#define Serial NorthFace        
#define Serial1 SouthFace       
#define Serial2 EastFace        
#define Serial3 WestFace        

#endif  /* SFBSERIAL_H */