Updated documentation

Author: mattairtech

README.md

@@ -1,6 +1,6 @@
 # Arduino Zero Bootloader
 
-## 1- Prerequisites
+## Prerequisites for Building
 
 The project build is based on Makefile system.
 Makefile is present at project root and try to handle multi-platform cases.
@@ -40,30 +40,30 @@ Make is usually available by default.
 Make is available through XCode package.
 
 
-## 2- Makefile Configuration
+## Makefile Configuration
 
 The section between 'Begin Configuration' and 'End Configuration' in the Makefile should be edited.
 Set BOARD_ID and MCU to a chip listed in the comments.
 
-# Boards definitions:
-# MT_D21E_rev_A, MT_D21E_rev_B, MT_D11, MT_D21J
-# arduino_zero, arduino_mkrzero, arduino_mkr1000, genuino_mkr1000, genuino_zero
-# Generic_x21E, Generic_x21G, Generic_x21J, Generic_D11D14AM, Generic_D11D14AS, Generic_D11C14A
+### Boards definitions:
+* MT_D21E_rev_A, MT_D21E_rev_B, MT_D11, MT_D21J
+* arduino_zero, arduino_mkrzero, arduino_mkr1000, genuino_mkr1000, genuino_zero
+* Generic_x21E, Generic_x21G, Generic_x21J, Generic_D11D14AM, Generic_D11D14AS, Generic_D11C14A
 
-# MCU definitions:
-# SAMD21J: SAMD21J18A, SAMD21J17A, SAMD21J16A, SAMD21J15A
-# SAMD21G: SAMD21G18A, SAMD21G17A, SAMD21G16A, SAMD21G15A
-# SAMD21E: SAMD21E18A, SAMD21E17A, SAMD21E16A, SAMD21E15A
-# SAML21J: SAML21J18B, SAML21J17B, SAML21J16B
-# SAML21G: SAML21G18B, SAML21G17B, SAML21G16B
-# SAML21E: SAML21E18B, SAML21E17B, SAML21E16B, SAML21E15B
-# SAMC21J: SAMC21J18A, SAMC21J17A, SAMC21J16A, SAMC21J15A
-# SAMC21G: SAMC21G18A, SAMC21G17A, SAMC21G16A, SAMC21G15A
-# SAMC21E: SAMC21E18A, SAMC21E17A, SAMC21E16A, SAMC21E15A
-# SAMD11:  SAMD11D14AM, SAMD11C14A, SAMD11D14AS
+### MCU definitions:
+* SAMD21J: SAMD21J18A, SAMD21J17A, SAMD21J16A, SAMD21J15A
+* SAMD21G: SAMD21G18A, SAMD21G17A, SAMD21G16A, SAMD21G15A
+* SAMD21E: SAMD21E18A, SAMD21E17A, SAMD21E16A, SAMD21E15A
+* SAML21J: SAML21J18B, SAML21J17B, SAML21J16B
+* SAML21G: SAML21G18B, SAML21G17B, SAML21G16B
+* SAML21E: SAML21E18B, SAML21E17B, SAML21E16B, SAML21E15B
+* SAMC21J: SAMC21J18A, SAMC21J17A, SAMC21J16A, SAMC21J15A
+* SAMC21G: SAMC21G18A, SAMC21G17A, SAMC21G16A, SAMC21G15A
+* SAMC21E: SAMC21E18A, SAMC21E17A, SAMC21E16A, SAMC21E15A
+* SAMD11:  SAMD11D14AM, SAMD11C14A, SAMD11D14AS
 
 
-## 3- Behaviour / Board Configuration
+## Board Configuration
 
 Configuration for each board is available in the board_definitions directory.
 Each board has a file named board_definitions_BOARD_NAME.h, where BOARD_NAME is
@@ -181,7 +181,7 @@ so no crystal is required. No LEDs are defined. BOOT_LOAD_PIN is not
 defined, but BOOT_DOUBLE_TAP_ENABLED is, since it uses the reset pin.
 
 
-## Boot condition test sequence
+## Boot Condition Test Sequence
 First, the start location of the sketch is fetched and checked. If it
 is empty (0xFFFFFFFF), then bootloader execution is resumed. Note that
 when Arduino auto-reset (into bootloader) is initiated, the first flash
@@ -198,7 +198,27 @@ should not be defined. USB_VENDOR_STRINGS_ENABLED also should not be
 defined in most cases, as well as BOOT_LOAD_PIN.
 
 
-## 4- Details
+## Building
+
+If not specified the makefile builds for **MT_D21E_rev_B**:
+
+```
+make
+```
+
+if you want to make a custom bootloader for a derivative board you must supply all the
+necessary information in a `board_definitions_xxx.h` file, and add the corresponding case in
+`board_definitions.h`. For example for the **Generic_x21J** board with a **SAMD21J18A** MCU,
+we use `board_definitions_Generic_x21J.h` and it is build with the following command:
+
+```
+BOARD_ID=Generic_x21J MCU=SAMD21J18A make clean all
+```
+
+which will produce a binary named sam_ba_Generic_x21J_SAMD21J18A.bin
+
+
+## Technical Details
 
 **Pinmap**
 
@@ -228,23 +248,3 @@ of the system stack. The applet in this case is a very simple word copy function
 1KB is reserved for the applet, and there are two 64 byte data buffers placed after it. The
 applet has its own stack at the top of RAM, but the word copy applet uses little/none of this.
 The bossac tool is responsible for loading the applet. See Devices.h from the Bossa source.
-
-
-## 5- How to build
-
-If not specified the makefile builds for **MT_D21E_rev_B**:
-
-```
-make
-```
-
-if you want to make a custom bootloader for a derivative board you must supply all the
-necessary information in a `board_definitions_xxx.h` file, and add the corresponding case in
-`board_definitions.h`. For example for the **Generic_x21J** board with a **SAMD21J18A** MCU,
-we use `board_definitions_Generic_x21J.h` and it is build with the following command:
-
-```
-BOARD_ID=Generic_x21J MCU=SAMD21J18A make clean all
-```
-
-which will produce a binary named sam_ba_Generic_x21J_SAMD21J18A.bin

bootloaders/zero/README.md

@@ -28,8 +28,10 @@ SWDCLK  TX1/MISO*              30 | A30           A31 | 31   *            RX1/SS
 ```
 
 
-# Pins descriptions for Generic ATsamD11C14A
-## PIN_MAP_STANDARD
+## Pins descriptions for Generic ATsamD11C14A
+
+### PIN_MAP_STANDARD
+```
 ====================================================================================================================================
 Arduino	| Port	| Alternate Function	| Comments (! means not used with this peripheral assignment)
 --------|-------|-----------------------|-------------------------------------------------------------------------------------------
@@ -66,8 +68,11 @@ Arduino	| Port	| Alternate Function	| Comments (! means not used with this perip
 30	| PA30	| MISO / SWD CLK	| !EIC/EXTINT[2] SERCOM1/PAD[0] !SERCOM1/PAD[2] !TC2/WO[0] !TCC0/WO[2] SWD CLK, leave floating during boot
 31	| PA31	| SS / SWD IO		| EIC/EXTINT[3] SERCOM1/PAD[1] !SERCOM1/PAD[3] !TC2/WO[1] !TCC0/WO[3] SWD IO
 ====================================================================================================================================
+```
+
 
-## PIN_MAP_COMPACT
+### PIN_MAP_COMPACT
+```
 ====================================================================================================================================
 Arduino	| Port	| Alternate Function	| Comments (! means not used with this peripheral assignment)
 --------|-------|-----------------------|-------------------------------------------------------------------------------------------
@@ -96,68 +101,57 @@ Arduino	| Port	| Alternate Function	| Comments (! means not used with this perip
 * When using ONE_UART_NO_WIRE_ONE_SPI, Serial1 refers to TX2/RX2 instead of TX1/RX1.
 * Leave pin A30 floating (or use external pullup) during reset.
 * SERCOM2 does not exist on the D11C14A.
+```
 
 
-# Board Configuration Notes
-
-TODO: Update this for Generic D11C14A
+## Board Configuration Notes
 
-* Either the 32.768KHz crystal or the 16MHz crystal can be used.
-* The bootloader does not use an external crystal by default. Double-tap the reset button to enter.
+* **Crystals**
+  * Either a 32.768KHz crystal or a high speed crystal can be used.
+  * The bootloader does not use an external crystal by default. Double-tap the reset button to enter manually.
 
-* **Digital: All pins can be used for general purpose I/O** 
-  * Supports INPUT, OUTPUT, INPUT_PULLUP, and INPUT_PULLDOWN.
-  * Each pin can source or sink a maximum of 7 mA (when PER_ATTR_DRIVE_STRONG is set for the pin).
+* **GPIO** 
+  * All pins (including analog) support INPUT, OUTPUT, INPUT_PULLUP, and INPUT_PULLDOWN.
+  * Each pin can source or sink a maximum of 7 mA (when PER_ATTR_DRIVE_STRONG is set for the pin, enabled by default).
   * Internal pull-up and pull-down resistors of 20-60 Kohms (40Kohm typ., disconnected by default).
-  * Use the pinMode(), digitalWrite(), and digitalRead() functions.
-* **Analog Inputs: 10 pins can be configured as ADC analog inputs.**
-  * These are available using the analogRead() function.
-  * All pins can be used for GPIO and some pins can be used for other digital functions (ie. pwm or serial).
+
+* **Analog Inputs**
+  * 5 pins can be configured as ADC analog inputs.
+  * Each pin measures from ground to 3.3 volts by default.
   * Each pin provides 10 bits of resolution (1024 values) by default.
   * 12-bit resolution supported by using the analogReadResolution() function.
-  * Each pin measures from ground to 3.3 volts.
-  * The upper end of the measurement range can be changed using the AREF pin and the analogReference() function.
-* **DAC: One analog output is available on pin 2.**
+  * The upper end of the measurement range can be changed using the analogReference() function.
+  * A reference voltage can be connected to REF.
+
+* **DAC**
+  * One analog output is available on pin 2.
   * Provides a 10-bit voltage output with the analogWrite() function.
-* **PWM: 12 pins (MT-D21E) or 8 pins (MT-D11) can be configured as PWM outputs.**
-  * Available using the analogWrite() function.
+
+* **PWM**
+  * 6 pins can be configured as PWM outputs.
   * Each pin provides 8 bits of resolution (256 values) by default.
   * 12-bit resolution supported by using the analogWriteResolution() function.
-* **External Interrupts: 15 pins (MT-D21E) or 9 pins (MT-D11) can be configured with external interrupts.**
-  * Available using the attachInterrupt() function.
-* **Serial: 2 pairs of pins (MT-D21E) or 1 pair (MT-D11) can be configured for TTL serial I/O.**
-  * MT-D21E: Serial1: pin 11 (RX) and pin 10 (TX). Serial2: pin 15 (RX) and pin 14 (TX).
-  * MT-D11: Serial1: pin 31 (RX) and pin 30 (TX).
-* **SPI: 3 or 4 pins can be configured for SPI I/O (SPI).**
-  * MT-D21E: Pin 18 (MOSI), pin 19 (SCK), pin 22 (MISO), and optionally pin 23 (SS, not currently used).
-  * MT-D11: Pin 10 (MOSI), pin 11 (SCK), pin 14 (MISO), and optionally pin 15 (SS, not currently used).
-  * SPI communication using the SPI library.
-  * Note that the SPI library will set SS as an output.
-  * On the MT-D11, the button must be configured as reset (default) when using SPI.
-* **TWI (I2C): 2 pins can be configured for TWI I/O (Wire).**
-  * MT-D21E: Pin 16 (SDA) and pin 17 (SCL).
-  * MT-D11: Pin 22 (SDA) and pin 23 (SCL).
-  * TWI communication using the Wire library.
-* **LED: One pin can be configured to light the onboard LED (LED_BUILTIN).**
-  * Pin 28 (MT-D21E) or pin 16 (MT-D11). Bring the pin HIGH to turn the LED on. The pullup is disabled on this pin.
-* **Button: One pin can be configured to read the onboard Button A (BUTTON_BUILTIN).**
-  * Pin 27 (MT-D21E) or pin 15 (MT-D11). Pressing the button will bring the pin LOW. The pullup must be enabled first.
-  * If the debouncing capacitor is connected, delay reading the pin at least 6ms after turning on the pullup.
-* **AREF: One pin can be configured as an AREF analog input.**
-  * The upper end of the analog measurement range can be changed using the analogReference() function.
-* **Reset: Bring this line LOW to reset the microcontroller.**
-
-
-
-# PinDescription table format
-
-## Note that a new column (GCLKCCL) was added for 1.6.8-beta-b0.
+
+* **External Interrupts**
+  * 7 pins can be configured with external interrupts.
+
+* **SERCOM**
+  * 2 SERCOM are available.
+  * Up to 2 UART instances
+  * 1 SPI instance
+  * 1 WIRE (I2C) instance
+
+
+
+## PinDescription table format
+
+### Note that a new column (GCLKCCL) was added for 1.6.8-beta-b0.
 MATTAIRTECH_ARDUINO_SAMD_VARIANT_COMPLIANCE in variant.h is used to track versions.
 If using board variant files with the old format, the new core will still read the
 table the old way, losing any new features introduced by the new column. Additionally,
 new definitions have been added for L21 and C21 support.
 
-## Each pin can have multiple functions.
+### Each pin can have multiple functions.
 The PinDescription table describes how each of the pins can be used by the Arduino
 core. Each pin can have multiple functions (ie: ADC input, digital output, PWM,
 communications, etc.), and the PinDescription table configures which functions can
@@ -168,7 +162,7 @@ analogReference(), attachInterrupt(), and pinMode() all call pinPeripheral() to
 verify that the pin can perform the function requested, and to configure the pin for
 that function. Most of the contents of pinMode() are now in pinPeripheral().
 
-## Pin Mapping
+### Pin Mapping
 There are different ways that pins can be mapped. Typically, there is no relation
 between the arduino pin number used, and the actual port pin designator. Thus, the 
 pcb must be printed with the arduino numbering, otherwise, if the port pin is printed,
@@ -184,15 +178,15 @@ designators from both PORTA and PORTB for arduino numbers 0-31 (ie: B1=1, A2=2),
 using arduino numbering only above 31. For 0-31 only one pin from PORTA or PORTB can be
 used, leaving the other pin for some number above 31.
 
-## See WVariant.h in cores/arduino for the definitions used in the table.
+**See [WVariant.h](https://github.com/mattairtech/ArduinoCore-samd/tree/master/cores/arduino/WVariant.h) for the definitions used in the table.**
 
-### Port:
+### Port
 This is the port (ie: PORTA).
 
-### Pin:
+### Pin
 This is the pin (bit) within the port. Valid values are 0-31.
 
-### PinType:
+### PinType
 This indicates what peripheral function the pin can be attached to. In most cases,
 this is PIO_MULTI, which means that the pin can be anything listed in the PinAttribute
 field. It can also be set to a specific peripheral. In this case, any attempt to