docs, now with style

1 files changed, 65 insertions, 0 deletions

diff --git a/source/lang/api/volatile.rst b/source/lang/api/volatile.rst
new file mode 100644
index 0000000..276bb6a
--- /dev/null
+++ b/source/lang/api/volatile.rst
@@ -0,0 +1,65 @@
+.. highlight:: cpp
+
+.. _lang-volatile:
+
+``volatile``
+============
+
+The ``volatile`` keyword known is a variable *qualifier*.  It is
+usually used before the datatype of a variable, to modify the way in
+which the compiler treats the variable.
+
+Declaring a variable ``volatile`` is a directive to the compiler. The
+compiler is software which translates your C++ code into the machine
+code, which are the real instructions for the STM32 chip in the
+Maple. (The particular compiler we provide for use with the Maple is a
+version of :ref:`GCC <arm-gcc>`).
+
+Specifically, it directs the compiler to read the variable's value
+fresh every time it is used, rather than "backing up" the value and
+reading from its backup copy. (Compilers often "back up" a variable's
+value in RAM into a storage location called a *register*; this is done
+for efficiency).
+
+A variable should be declared ``volatile`` whenever its value can be
+changed by something beyond the control of the code section in which
+it appears, such as an :ref:`external interrupt
+<external-interrupts>`. On the Maple, the only place that this is
+likely to occur is in sections of code associated with interrupts.
+
+Example
+-------
+
+::
+
+    // toggles LED when interrupt pin changes state
+
+    int pin = 13;
+    volatile int state = LOW;
+
+    void setup() {
+      pinMode(pin, OUTPUT);
+      attachInterrupt(0, blink, CHANGE);
+    }
+
+    void loop() {
+      digitalWrite(pin, state);
+    }
+
+    void blink() {
+      if (state == HIGH) {
+        state = LOW;
+      } else {
+        // state must be HIGH
+        state = HIGH;
+      }
+    }
+
+See also
+--------
+
+- :ref:`External Interrupts <external-interrupts>`
+- :ref:`lang-attachinterrupt`
+- :ref:`lang-detachinterrupt`
+
+.. include:: cc-attribution.txt