Make blocking behaviour of HardwareSerial::write optional

This introduces two new methods, Serial.setBlocking() and
Serial.getBlocking(), which can be used to enable or disable blocking.

References: arduino#672

---
TODO: This commit is probably not ready to merge, I'm not sure what the proper
API for this feature would be (the current enum approach requires
qualifying the constants with HardwareSerial:: for example). I'm also
not sure where and how to add the new function to a keywords.txt file.

Author: matthijskooijman

Diff for: hardware/arduino/cores/arduino/HardwareSerial.cpp

@@ -253,6 +253,7 @@ HardwareSerial::HardwareSerial(
   _ucsrb = ucsrb;
   _ucsrc = ucsrc;
   _udr = udr;
+  _blocking = SERIAL_BLOCK_ALWAYS;
 }
 
 // Public Methods //////////////////////////////////////////////////////////////
@@ -312,6 +313,16 @@ void HardwareSerial::end()
   _rx_buffer_head = _rx_buffer_tail;
 }
 
+void HardwareSerial::setBlocking(blocking_behaviour when)
+{
+  _blocking = when;
+}
+
+HardwareSerial::blocking_behaviour HardwareSerial::getBlocking()
+{
+  return _blocking;
+}
+
 int HardwareSerial::available(void)
 {
   ATOMIC_BLOCK(ATOMIC_RESTORESTATE) {
@@ -374,6 +385,8 @@ size_t HardwareSerial::write(uint8_t c)
     // wait for the interrupt handler to empty it a bit
     while (i == _tx_buffer_tail) {
       if (!interrupts_enabled) {
+	if (!(_blocking & SERIAL_BLOCK_NON_INTERRUPTIBLE))
+	  return 0;
 	// Interrupts were disabled at the start of this function, so we
 	// can't just enable them (that would allow other interrupts to
 	// trigger as well!). We'll have to poll the data register empty
@@ -382,6 +395,8 @@ size_t HardwareSerial::write(uint8_t c)
 	if(bit_is_set(*_ucsra, UDRE0))
 	  _tx_udr_empty_irq();
       } else {
+	if (!(_blocking & SERIAL_BLOCK_INTERRUPTIBLE))
+	  return 0;
 	// Interrupts were enabled, so we can temporarily enable them so
 	// our tx interrupt can fire and free up some space. Note that we
 	// can't just use the UDRE polling approach here instead of

Diff for: hardware/arduino/cores/arduino/HardwareSerial.h

@@ -39,6 +39,19 @@
 
 class HardwareSerial : public Stream
 {
+  public:
+    // Describes the blocking behaviour for writing (note that flushing
+    // will _always_ block until the transmission is complete).
+    enum blocking_behaviour {
+      // Never block, discard data when buffer is full
+      SERIAL_BLOCK_NEVER = 0,
+      // Block only when interrupts are enabled
+      SERIAL_BLOCK_INTERRUPTIBLE = 1 << 0,
+      // Block only when interrupts are disabled
+      SERIAL_BLOCK_NON_INTERRUPTIBLE = 1 << 1,
+      // Always block, never discard data
+      SERIAL_BLOCK_ALWAYS = SERIAL_BLOCK_INTERRUPTIBLE | SERIAL_BLOCK_NON_INTERRUPTIBLE,
+    };
   protected:
     volatile uint8_t *_ubrrh;
     volatile uint8_t *_ubrrl;
@@ -48,6 +61,7 @@ class HardwareSerial : public Stream
     volatile uint8_t *_udr;
     // Has any byte been written to the UART since begin()
     bool _written;
+    blocking_behaviour _blocking;
 
     volatile uint8_t _rx_buffer_head;
     volatile uint8_t _rx_buffer_tail;
@@ -68,6 +82,8 @@ class HardwareSerial : public Stream
     void begin(unsigned long);
     void begin(unsigned long, uint8_t);
     void end();
+    void setBlocking(blocking_behaviour when);
+    blocking_behaviour getBlocking();
     virtual int available(void);
     virtual int peek(void);
     virtual int read(void);