Doc fixes

Author: SpenceKonde

.gitignore

@@ -2,3 +2,31 @@ megaavr/tools/python3/*
 *.pyc
 *.pyc
 .DS_Store
+megaavr/python3/_contextvars.pyd
+megaavr/python3/_ctypes.pyd
+megaavr/python3/_decimal.pyd
+megaavr/python3/_elementtree.pyd
+megaavr/python3/_hashlib.pyd
+megaavr/python3/_lzma.pyd
+megaavr/python3/_msi.pyd
+megaavr/python3/_multiprocessing.pyd
+megaavr/python3/_overlapped.pyd
+megaavr/python3/_queue.pyd
+megaavr/python3/_socket.pyd
+megaavr/python3/_sqlite3.pyd
+megaavr/python3/_ssl.pyd
+megaavr/python3/libcrypto-1_1.dll
+megaavr/python3/libssl-1_1.dll
+megaavr/python3/pyexpat.pyd
+megaavr/python3/python.exe
+megaavr/python3/python3.dll
+megaavr/python3/python3.exe
+megaavr/python3/python37._pth
+megaavr/python3/python37.dll
+megaavr/python3/python37.zip
+megaavr/python3/pythonw.exe
+megaavr/python3/select.pyd
+megaavr/python3/sqlite3.dll
+megaavr/python3/unicodedata.pyd
+megaavr/python3/vcruntime140.dll
+*.pyd

ChangeLog.md

@@ -1,5 +1,5 @@
 # Changelog
-This page documents (nearly) all bugfixes and enhancements that produce visible changes in behavior throughout the history of megaTinyCore. Note that this document is maintained by a human, who is - by nature - imperfect (this is also why there are so many bugs to fix); sometimes the changelog may not be updated at the same time as the changes go in, and occasionally a change is missed entirely in the changelog, though this is rare. Change descriptions may be incomplete or unclear; this is not meant to be an indepth reference.
+This page documents (nearly) all bugfixes and enhancements that produce visible changes in behavior throughout the history of megaTinyCore. Note that this document is maintained by a human, who is - by nature - imperfect (this is also why there are so many bugs to fix); sometimes the changelog may not be updated at the same time as the changes go in, and occasionally a change is missed entirely in the changelog, though this is rare. Change descriptions may be incomplete or unclear; this is not meant to be an indepth reference. Versions that have been ~struck through~ are versions that are known to be no good and should not be used
 
 ## Planned changes not yet implemented
 These items are in addition to what was listed under changes already in release.
@@ -23,13 +23,16 @@ These items are in addition to what was listed under changes already in release.
 Changes listed here are checked in to GitHub ("master" branch unless specifically noted; this is only done when a change involves a large amount of work and breaks the core in the interim, or where the change is considered very high risk, and needs testing by others prior to merging the changes with master - everything else goes straight into master). These changes are not yet in any "release" nor can they be installed through board manager, only downloading latest code from github will work. These changes will be included in the listed version, though planned version numbers may change without notice - critical fixes may be inserted before a planned release and the planned release bumped up a version, or versions may go from patch to minor version depending on the scale of changes
 
 ### Planned 2.6.11
+* Correct bug with Comparator (#1236)
 * Correct numerous issues with the microchip board defs. Clearly nobody is using them - since 2 of them didn't compile, and none of the optiboot ones would ever be able to successfully be programmed over the bootloader because selfprogramming wasn't enabled (BOOTEND = 0).
 * Major Bugfix: Correct issue #1164 thanks to John Vasileff. This would cause Serial.flush to hang in one-wire mode.
 * Major Bugfix: Correct buffered PWM on all parts.
 * Major Bugfix: Correct PWM on non-default pins on all parts; digitalPinHasPWM.
 * Fix bug with CCL clock source.
 * Fix bug with Comparator
-* Enhance error messages from wrong-part on upload (pending - currently it just crashes instead of giving a cryptic error, and in prvious releases, the error has been causing confusion.
+* Enhance documentation
+* Removed example of exactly the sort of boneheaded and strictly-worse in a trivial part of Wire. While it was merely a bad example at the time it was written, it is now known to be a bad, dangerous example, because it featured code that demonstrated Strictly Worse access to registers, by loading a vport register to a pointer register, and using that - not only is it stupid and just a less-featureful PORT when accessed that way, avoiding pointer access to the I/O space (64 addresses, - 28 VPORTs and 4 GPIORs in low I/O and SP, RAMPZ (if applicable), CCP (the register used for `__PROTECTED_WRITE()`}), and of course the SREG. And indeed, none of those are registers that anyone should ever acccess using a pointer, even if it didn't wasn't safe against an incredibly scary bug - the low I/O is all about the bitwise instructions, which need both the register and bit compile time known. `VPORT_t*` is not a type you should ever declare - if you have had to declare it, *you get no benefit* from faster access to it (like you do if you use the compile-time known VPORT's amd access them without pointing. )
+* Enhance error messages from wrong-part on upload.
 
 ## Released Versions
 

README.md

@@ -643,6 +643,7 @@ The bible of the AVR instruction set. Like any such tome, it is a lengthy docume
 
 #### See also the recently written ones listed in [the analog reference](https://github.com/SpenceKonde/megaTinyCore/blob/master/megaavr/extras/Ref_Analog.md)
 As promised, a bunch of additional information was released; Unfortunately it leaves some of the key questions unanswered.
+
 ## List of Tools sub-menus
 * Tools -> Chip - sets the specific part within a selected family to compile for and upload to.
 * Tools -> Clock - sets the clock speed. You must burn bootloader after changing between 16/8/4/1MHz and 20/10/5MHz to apply the changes (ie, changing from 20MHz to 10MHz does not require burning bootloader, changing from 20MHz to 16MHz does). A virgin chip will be set to use the 20MHz internal oscillator as its base clock source, so 20/10/5MHz clock speed options should work without an initial "burn bootloader" - though we still recommend it to ensure that all other fuses are set to the values you expect.
@@ -668,8 +669,25 @@ As promised, a bunch of additional information was released; Unfortunately it le
 ## Warnings and Caveats
 There are however a few cautions warranted regarding megaTinyCore - either areas where the core is different from official cores, or where the behavior is the same, but not as well known.
 
+### Linker sometimes fails on 8k parts due to an apparent compiler bug.
+It doesn't seem to know it can wrap around with rjmp, and if would have to, it fails to link. This is only relevant on 8k parts. All I can advise is to not use those parts. Considering that 16k parts arent't much more expensive..
+
+
 ### Direct Register Manipulation
-If you are manually manipulating registers controlling a peripheral, except as specifically noted in relevant reference pages, the stated behavior of API functions can no longer be assured. It may work like you hope, it may not, and it is not a bug if it does not, and you should not assume that calling said API functions will not adversely impact the rest of your application. For example, if you "take over" TCA0, you should not expect that using `analogWrite()` - except on the two pins on the 20/24-pin parts controlled by TCD0 - will work for generating PWM. If you reconfigure TCA0 except as noted in Ref_Timers, without calling `takeOverTCA0`, both `analogWrite()` and `digitalWrite()` on a PWM pin may disrupt your changed configuration.
+If you are manually manipulating registers controlling a peripheral, except as specifically noted in relevant reference pages, the stated behavior of API functions can no longer be assured. It may work like you hope, it may not, and it is not a bug if it does not, and you should not assume that calling said API functions will not adversely impact the rest of your application. For example, if you "take over" TCA0, you should not expect that using `analogWrite()` on a TCA pin will work, nor that `digitalWrite()` will turn off the PWM if it's coming from the TCA. Similarly, if you reconfigure TCA0, but fail to call takeOverTCA0() first, you should expect that using analogWrite() or digitalWrite() on any pin that is or can be controlled by the TCA may result in unspecified behavior. In this case, it might take the form of a digitalWrite or library that makes use of that, on a different pin than the one you're currently getting PWM from turning the PWM off unexpectedly, or writing writing incorrect duty cycle values over the ones you'd set, and so on.
+
+Therefor:
+* Before reconfiguring any timer by writing to registers - with THE EXCEPTION OF A TCB, you must be certain that one of the following is true:
+  * takeOverTCxn() has been called (resumeTCxn() to reverse this and reinitialize the timer to restore the functionality is available on DxCore, but I question the value of it and have not ported it).
+    * If present, since resume reverses takeOver and reinitializes the timer for analogWrite PWM, you must not call it between when you called takeOver and when you write to register
+  * You are changing only registers described in the relevant core documentation for that timer as being safe to modify without calling takeOverTCxn().
+    * The more complicated the timer, logically, the more likely it is that someone will be able to comprehend register manipulation relevant to their application without understanding the rest of the chapter (of datasheet) well enough to take full control as with a takeOver. In recognition of that (as well as the empirical observation that strange reconfiguration of the TCA is extremely common, as were questions about that prior to the introducution of relevant examples), we concluded that unlike the TCA, which is a well-behaved, very mundanetimer that is familiar, conceptually, to anyone who's useda classic AVR's TIMER1, the TCD is niether cooperative nor familiar, and few users are likely to be able to reconfigure it fully themselves, so while takeOverTCD0() is offered on partswith a TCD, we also put further effort into ensuring that as many options as possiblethat might plausibly be used with PWM could be altered while still using analogWrite(). These were documented in [the TCD reference](/megaavr/extras/REF_TCD.md).
+    * The much shorter list for TCA remains in the [timer reference](/egaavr/extras/REF_Timers.md), as TCA has few relevant options not already controlled by analogWrite which are relevant when takeOverTCA0() is not called.
+  * You do not use any builtin functions that directly or indirectly call analogWrite(), turnOffPWM() or digitalWrite()
+* Reconfiguring the millis timer will break timekeeping very badly. If you need to reconfigure all the timers, such that you can't use the tools menu to put millis on a timer you don't need to reconfigure (ex, you need to use Servo and tone(), and reconfigure TCA for custom PWM on a tinyAVR 2), disable millis from the menu, whi
+
+
+
 ## Differences in Behavior between DxCore and Official Cores
 While we generally make an effort to emulate the official Arduino core, there are a few cases where the decision was made to have different behavior to avoid compromising the overall functionality; the official core is disappointing on many levels. The following is a (hopefully nearly complete) list of these cases.