A bit of docs tidying and changelog/platform.txt update for 1.5.4

ChangeLog.md

@@ -12,6 +12,7 @@ These are typically planned for release in a future version (usually the next on
 
 ### 1.5.4
 * **Critical (per Microchip) Bugfix** Correct an issue that someone with a Microchip logo as their avatar called critical (I defer to Microchip's wisdom regarding it's criticality), which would cause a crash when the old attach interrupt mode is used for pins on PORTC due to a copy/paste error from tinyAVR. This issue has been present since 1.4.x versions somewhere.
+* Linting and small amounts of tidying in docs. This was mostly about the bugfix above.
 
 ### 1.5.3
 * **Critical Bugfix** Correct critical issue #384 where burn bootloader would disable UPDI on AVR DD-series parts.

megaavr/extras/Comparison.md

@@ -1,15 +1,22 @@
 # Dx-series peripherals vs other modern AVRs
-Based on notes from initial reading of datasheets for DA, DB-series parts. Much was unchanged, and essentially all of the changes were welcome.
+Based on notes from the Dx-series and Ex-series datasheets.
+
+## Errata
+Very few issues were fixed on the DA-series, and numerous new ones were added. The DD series has improved dramatically. Unfortunately, they have not been giving us the promised die revisions.
 
 ## NVMCTRL
-Dramatic changes. 0/1-series parts erase and write with page-granularity. Dx-series erases with page granularity but writes with word-granularity. The flash protection mechanism now only requires the instruction that results in the actual write or erase (an SPM or ST instruction with NVMCTRL.CTRLA set appropriately) to execute from bootloader section.
+* Dramatic changes. 0/1-series parts erase and write with page-granularity. Dx-series erases with page granularity but writes with word-granularity. The flash protection mechanism now only requires the instruction that results in the actual write or erase (an SPM or ST instruction with NVMCTRL.CTRLA set appropriately) to execute from bootloader section.
+* On the Ex-series, this has reverted to more tiny-like behavior, but with the addition of RWW/NRWW sections.
 
 ## CLKCTRL
 Major differences from 0/1-series, and further changes for DB-series.
 * For internal oscillator, you just set the frequency: Options are 1/2/3/4 MHz, then increments of 4. Datasheet stops at 24. Part still works if you keep incrementing it up to 28, 32. Then it repeats 20-32 again.
-* There's also a PLL, rated for operation with input frequency between 16 and 24 MHz (very conservative, it turns out) and an output frequency 2 or 3 times that (or 4x - known from the earliest I/O headers, but not otherwise documented), but all it can do is clock the type D timer. It also
+* There's also a PLL, rated for operation with input frequency between 16 and 24 MHz (very conservative, it turns out) and an output frequency 2 or 3 times that (or 4x - known from the earliest I/O headers, but not otherwise documented), but all it can do is clock the type D timer.
+* Both the system clock and PLL can be overclocked to an almost unbelievable degree, particularly on extended temperature range parts when used at room temperature. 2x the rated system clock with an external oscillator on a DB with extended temp range is possible. The PLL seems able to do at least than 2.67 times what it is rated for, though 3.33 is apparently asking too much.
 * You can enable "AutoTuning" from a watch crystal.
-* The DB and DD-series also support using an external crystal and have clock failure detection.
+* The DB and DD-series also support using an external crystal and have clock failure detection which does not work all that well.
+* No significant changes between DB and DD.
+* All announced Ex-series parts appear to return to a more tiny-avr like clock subsystem, only with the addition of autotune.
 
 ## TCA
 Second event channel, EVACTB added. Otherwise, appears identical, complete with the wonky CTRLExxx CMDEN bits in split mode, with values of NONE (0b00) and BOTH (0b11), but the other two marked reserved.
@@ -28,35 +35,49 @@ tinyAVR 2-series also got the new version (without the TCA1 clock option of cour
 ## TCD0
 Only difference appears to be the addition of the PLL as a clock source. It looks like in general everyone ignored the TCD until the Dx-series came out - there was hardly any errata listed for it until the year following the Dx-series release, but it has now grown significantly, with the same bugs appearing both here and for Dx-series.
 
+## TCE and TCF
+Two new timers appear on the AVR EB-series parts. Very little is known about them other than that TCE has something called a Waveform Extension (WEX), is 16-bit, and lists pin mappings with 8 waveform outputs. TCF is 24-bit and has two compare channels. The EB-series has one of each.
+
 ## EVSYS
-Largely unchanged aside from basics needed to adjust for the larger number of channels.
+* Largely unchanged from megaAVR 0-series or tinyAVR 2-series.
+* Major changes from tinyAVR 0/1-series: Now the user channels are named, not numbered, and all event channels work for both synchronous and asynchronous inputs and outputs.
+
+* Ex-series brings a major change. All generator channels get two options for each port on the device, as well as two options for the RTC. These are channels 0 and 1 and are configured by the new EVGENCTRL register found on the ports and the RTC. This means *all generator channels are created equal*.
 
 ## VREF
-Reference voltages are 1.024, 2.048, and 4.096V, as well as 2.5V, Vdd, and external clock. Works the same for AC, DAC, and ADC. The first three are clearly meant to make life easier for people using the ADC - With 12-bit resolution, and 4.096V, 1 LSB is 1mV - It doesn't get any easier than that!
+* Reference voltages are 1.024, 2.048, and 4.096V, as well as 2.5V, Vdd, and external clock. Works the same for AC, DAC, and ADC. The first three are clearly meant to make life easier for people using the ADC - With 12-bit resolution, and 4.096V, 1 LSB is 1mV - It doesn't get any easier than that!
 This means Vdd can be used for DAC reference voltage.
 
 ## DAC
 Only significant difference is that it's 10 bit... and the DATA register is left-adjusted, so if you just want 8 bits, you can just write the one register. DAC vref can also now be set to Vdd so you can get rail to rail output.
 
 ## ADC
-RESSEL now chooses between 10 and 12 bits, differential ADC (but measured voltage still must not exceed VRef for correct results - no high side current sense using the smallest reference voltage, that will have to wait until 2-series/EA-series parts), and slightly higher maximum accumulation option, much higher maximum sample duration. Specs permit slightly faster ADC clock.
+* RESSEL now chooses between 10 and 12 bits, differential ADC (but measured voltage still must not exceed VRef for correct results - no high side current sense using the smallest reference voltage, that will have to wait until 2-series/EA-series parts), and slightly higher maximum accumulation option, much higher maximum sample duration. Specs permit slightly faster ADC clock.
 
-Note that the 2-series tinyAVR has a completely reworked ADC, which will also be featured on the EA-series.
+* The 2-series tinyAVR has a completely reworked ADC, which will also be featured on the EA-series with small changes. The ADC clock can be significantly higher, accumulation of up to 1024 samples is supported. They now feature a programmable gain amplifier (1-16x), and the differential mode does not require that all inputs be less than VREF (this is required on the Dx-series and kills many of the applications of the differential ADC).
 
 ## AC
-General layout of megaAVR 0-series, with ACn.DACREF, instead of additional DACn peripherals with no output buffer and DAC0 being shared with AC0's DACREF, and the windowed mode configuration like the "golden" tinyAVR 1-series.
+* General layout of megaAVR 0-series, with ACn.DACREF, instead of additional DACn peripherals with no output buffer and DAC0 being shared with AC0's DACREF, and the windowed mode configuration like the "golden" tinyAVR 1-series.
 
 ## TWI
-No changes from megaAVR 0-series.
+* No changes from megaAVR 0-series aside from the pin mapping options, and the addition of the SMBus logic level option.
 
 ## SPI
-No changes.
+* No changes aside from the pin mapping options.
 
 ## USART
-Largely unchanged, except that one of the RS-485 modes, which was poorly described in the 1-series datasheets, appears to be gone entirely.
+* Largely unchanged, except that one of the RS-485 modes, which was poorly described in the 1-series datasheets, appears to be gone entirely.
 
 ## CCL
-D-latch works.
+* D-latch works.
+* The input list has been adjusted somewhat.
+* Interrupts, not supported on tinyAVR 0/1-series, are supported on Dx-series and Ex-series.
+
+## PORT
+* Dx and Ex-series parts feature a facility for mass-configuration of PINnCTRL registers not found on tinyAVR.
+* Ex-series add an EVGENCTRL register to each port. Each nybble, independently sets which pin within the port is used for each port's two event generation channels.
+* Starting from the DD-series, it seems that now all pins will be fully async instead 2 fully async and 6 partially async pins per port.
 
 ## RTC
-Same as megaAVR 0-series. Free of the bugs that afflicted the tinyAVR 0/1-series.
+* Same as megaAVR 0-series. Free of the bugs that afflicted the tinyAVR 0/1-series.
+* Ex-series add an EVGENCTRL. Each nybble, independently sets which division factor to use for the RTC's two event generation channels.

megaavr/extras/Ref_Digital.md

@@ -2,12 +2,13 @@
 This core includes a number of features to provide more control or performance when doing digital I/O. This page describes how to use them. All of the options that can be configured for a pin are exposed. The only things that aren't exposed are the slew rate limiting feature, and the multi-pin configuration facilities. The slew rate limiting is can only be configured on a per port basis; turning it on and off is so simple (see below) that it needs no wrapper. The multi-pin configuration system does not have an obvious "right way" to expose it and should be handled directly by the sketch - it is very flexible and no wrapper around it would be able to preserve it's virtues while being much of a wrapper.
 
 ## First, an important note about digital output on Dx-series
-Classic AVRs had symmetric pin drive. The pin driver was equally good at driving a pin high or low. 
+Classic AVRs had symmetric pin drive. The pin driver was equally good at driving a pin high or low.
 
-So did the modern tinyAVR parts (not exactly, but very close to it. 
+So did the modern tinyAVR parts (not exactly, but very close to it.
 
-This is NOT the case on the AVR Dx-series (nor is is true of most I/O pins on microcontrollers or other ICs). As is typical of CMOS technology, pins are better at sinking current than sourcing it. This can be seen by measuring the voltage of an output pin where the pin is configured to drive HIGH or LOW, while a resistor is connected to the opposite power rail. A resistor of 250 ohms or more is appropriate at 5v as even perfect pin drivers would not be able to exceed 20mA. On the AVR Dx-series, the high-side drivers are about half the strength of the low-side drivers. Usually you don't care, and the pin drivers are quite beefy compared to most microcontrollers, but this occasionally makes a difference. 
-For example, consider the practice of using PWM and an RC filter as a really ghetto DAC (we have a real DAC on Dx, though only one, so you're not as likely to be doing this). This method depends on two assumptions; first, an ideal capacitor with no leakage is assumed, even though no such thing exists - though often the impact is small. And second, that the drive is symmetric. If you imagine a 50% duty cycle PWM pin, going through a 250 ohm resistor and then to a capacitor, in order to actually get the expected 2.5V, when the pin is at 2.5V, the current sourced during the high half of the cycle must be the same as the current sunk during the low half of the cycle. 250 ohms would make this current about 10mA. This would result in a drop of approximately .25V on the low side, and .5V on the high side, Hence the current flowing would be 8mA while HIGH and 9mA while low if the cap was at 2.5V (approximately - since voltage drop depends on the current, but the current depends on the voltage drop, this effect is slightly smaller in reality; obviously it's obnoxious to calculate, since the current depends on the voltage drop which depends on the current, and both of them depend on the output voltage as well as the duty cycle, but the output voltage depends on the both currents. In reality, you will find that the voltage on that capacitor will be lower than 2.5V, though not that much lower. Closer to 2.25V on a first order approximation. 
+This is NOT the case on the AVR Dx-series (nor is is true of most I/O pins on microcontrollers or other ICs). As is typical of CMOS technology, pins are better at sinking current than sourcing it. This can be seen by measuring the voltage of an output pin where the pin is configured to drive HIGH or LOW, while a resistor is connected to the opposite power rail. A resistor of 250 ohms or more is appropriate at 5v as even perfect pin drivers would not be able to exceed 20mA. On the AVR Dx-series, the high-side drivers are about half the strength of the low-side drivers. Usually you don't care, and the pin drivers are quite beefy compared to most microcontrollers, but this occasionally makes a difference.
+
+For example, consider the practice of using PWM and an RC filter as a really ghetto DAC (we have a real DAC on Dx, though only one, so you're not as likely to be doing this). This method depends on two assumptions; first, an ideal capacitor with no leakage is assumed, even though no such thing exists - though often the impact is small. And second, that the drive is symmetric. If you imagine a 50% duty cycle PWM pin, going through a 250 ohm resistor and then to a capacitor, in order to actually get the expected 2.5V, when the pin is at 2.5V, the current sourced during the high half of the cycle must be the same as the current sunk during the low half of the cycle. 250 ohms would make this current about 10mA. This would result in a drop of approximately .25V on the low side, and .5V on the high side, Hence the current flowing would be 8mA while HIGH and 9mA while low if the cap was at 2.5V (approximately - since voltage drop depends on the current, but the current depends on the voltage drop, this effect is slightly smaller in reality; obviously it's obnoxious to calculate, since the current depends on the voltage drop which depends on the current, and both of them depend on the output voltage as well as the duty cycle, but the output voltage depends on the both currents. In reality, you will find that the voltage on that capacitor will be lower than 2.5V, though not that much lower. Closer to 2.25V on a first order approximation.
 
 It remains to be seen what the pin drive strength will be like on the Ex-series or any other future part, and until the IO pin output current is added to the characteristics graphs section of the datasheet, you don't really have much information; preliminary datasheets typically omit this sort of data, because these properties have not yet been characterized (I'm not sure how they manage that. Automating that testing, while not trivial, shouldn't be a challenge to microcontroller experts. I'm pretty sure there are a considerable number of such persons employed by Microchip.
 

megaavr/platform.txt

@@ -7,7 +7,7 @@
 name=DxCore
 versionnum.major=1
 versionnum.minor=5
-versionnum.patch=3
+versionnum.patch=4
 versionnum.postfix=
 versionnum.released=1