Add SD.end() method, including arg to leave SPI up (#5402)

* Add SD.end() method with endSPI flag as arg

* cleanup and fix a default arg

* Fix typo

libraries/SD/src/SD.cpp

@@ -350,6 +350,17 @@ boolean SDClass::begin(uint8_t csPin, uint32_t speed) {
          root.openRoot(volume);
 }
 
+//Warning: see comment in SD.h about possible card corruption.
+void SDClass::end(bool endSPI)
+{
+  if(card.errorCode() == 0 && root.isOpen()) {
+    root.close(); //Warning: this calls sync(), see above comment about corruption.
+  }
+  
+  card.end(endSPI);
+}
+
+
 // this little helper is used to traverse paths
 SdFile SDClass::getParentDir(const char *filepath, int *index) {
   // get parent directory

libraries/SD/src/SD.h

@@ -90,6 +90,24 @@ public:
   // before other methods are used.
   boolean begin(uint8_t csPin = SD_CHIP_SELECT_PIN, uint32_t speed = SPI_HALF_SPEED);
 
+/*
+  In the following sequence:
+  //Insert SD Card A
+  SD.begin()
+  //do operations
+  //remove card A
+  //insert SD card B
+  SD.end()
+
+  It is possible that card A becomes corrupted due to removal before calling SD.end().
+  It is possible that card B becomes corrupted if there were ops pending for card A at the time SD.end() is called.
+
+  Call SD.end() or SD.end(true) to shut everything down.
+  Call SD.end(false) to shut everything but the SPI object down.
+ */
+  void end(bool endSPI = true);
+
+
   // Open the specified file/directory with the supplied mode (e.g. read or
   // write, etc). Returns a File object for interacting with the file.
   // Note that currently only one file can be open at a time.

libraries/SD/src/utility/Sd2Card.cpp

@@ -349,6 +349,24 @@ uint8_t Sd2Card::init(uint8_t sckRateID, uint8_t chipSelectPin) {
   chipSelectHigh();
   return false;
 }
+
+//------------------------------------------------------------------------------
+/**
+ * Shut down Sd2Card, which at this point means end SPI.
+ *
+ * \param[in] endSPI The value true (non-zero) or FALSE (zero).
+
+  Call card.end() or card.end(true) to shut everything down.
+  Call card.end(false) to shut everything but the SPI object down.
+ */
+void Sd2Card::end(bool endSPI)
+{
+  if(endSPI)
+    SPI.end();
+}
+
+
+
 //------------------------------------------------------------------------------
 /**
  * Enable or disable partial block reads.

libraries/SD/src/utility/Sd2Card.h

@@ -200,6 +200,9 @@ class Sd2Card {
   }
   uint8_t init(uint8_t sckRateID, uint8_t chipSelectPin);
   #endif
+
+  void end(bool endSPI = true);
+
   void partialBlockRead(uint8_t value);
   /** Returns the current value, true or false, for partial block read. */
   uint8_t partialBlockRead(void) const {return partialBlockRead_;}