ATmegaxxxx - generalised support

[feilipu]

ATmegaxxxx

Port for generalised Microchip ATmega architecture

Description

This port provides a basis for supporting all modern ATmega devices using either the Enhanced Watchdog Timer, or Timer0 (an 8-bit Timer generally available across the whole range).

This initial commit contains the information required to build with System Tick being generated by either the:

• Watchdog Timer, or
• Timer0 - an 8-bit Timer

Further commits can add support for 16-bit Timers available on many relevant devices. The availability of these 16-bit Timers is somewhat device specific, and these complex and highly configurable Timers are often used to generate phase correct PWM timing (for example) and they would be wasted as a simple System Tick.

The port also provides support for the 3 byte program counter devices ATmega2560 and ATmega2561. Specific to these two devices the RAMPZ and EIND registers need to be preserved during a context switch. Also, due to a limitation in GCC, the scheduler needs to reside in the lower 128kB of flash for both of these devices. This is achieved by adding the .lowtext section attribute to the function prototype.

The ATmega808/809/1608/1609/3208/3209/4808/4809 megaAVR family is a substantial revision of the ATmega platform, and is currently not supported by avr-libc. Therefore the megaAVR 0-series is not supported by this port.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[feilipu]

To build generic Microchip (AVR) ATmega support the similarities across the family must be considered, and differences respected. Some comments on the strategy.

System Tick

The Microchip (AVR) ATmega family has limited Timer and Pin capabilities, and is designed to be used in physical applications, controlling hardware with PWM and recognising level and edge voltage changes. It does this mainly through the use of 16-bit Timers (for generating phase correct PWM by up/down counting), and Pins attached to Interrupts. The 8-bit Timers are also attached to Pins, and they can be used for more simple timing tasks, requiring only a single counting direction.

The Timers not attached to Pins (and therefore not impacting the application of the device) are an additional 16-bit Timer (very device dependent, eg Timer3 on 1284p), and the Watch Dog Timer.

The Watch Dog Timer is configured identically across the entire range of ATmega devices. It comes in two variants. 1. Old style (eg ATmega32) which does not have an Interrupt capability, and hence on these old devices cannot be used as the System Tick. and 2. New style enhanced WDT, which can generate an Interrupt, and is available on every relevant device.

Using the Watch Dog Timer (WDT) to generate the System Tick does not impact its use as a watch dog. It can be configured to generate a System Tick interrupt, and then one period later to Reset the device if the interrupt is not serviced.

Configuration and usage of the WDT is covered in <avr/wdt.h> which was revised in avr-libc 2.0.0.

Two additional WDT functions are provided in port.c, which extend avr-libc functions to enable the WDT Interrupt without enabling Reset wdt_interrupt_enable(), and to enable both the Interrupt and the Reset wdt_interrupt_reset_enable().

3 Byte PC Devices

The ATtiny, ATmega, ATxmega families can optionally support both 3 byte PC and 3 byte RAM addresses. However, focusing on just the ATmega family only two devices have a large Flash requiring them to use 3 byte PC. These are the ATmega2560 and ATmega2561. This PR provides support for these two devices in two ways.

• providing portSAVE_CONTEXT() and portRESTORE_CONTEXT() saving both the RAMPZ and EIND registers.
• providing a portTASK_FUNCTION_PROTO() with the linker attribute .lowtext which is used to ensure that the scheduler and relevant functions remain in the lower 128kB of Flash.

Interrupt Nesting

The ATmega family does not support interrupt nesting, having only one interrupt priority. This means that when the Scheduler is running, interrupts are normally disabled.

When a very time critical process is running, based on microsecond timing generated by one of the Timers, it is important to re-enable interrupts as early as possible in processing a Yield. Fortunately, this is supported through the use of the NO_BLOCK decorator when defining the Interrupt Service Routine.

The NO_BLOCK decorator will enable the global interrupt early in the handling of an ISR (in this case for the Scheduler), and enable interrupts to be nested. Using this method, I've been able to successfully implement an Audio Synthesiser with less than 83 microseconds for each cycle, whilst still running the Scheduler to handle display and input.

Using NO_BLOCK is optional, and should only be done if a critical Timer should interrupt the Scheduler.

Extension proposals for PR

From the basis of this PR, following further commits could be made. But, before doing this work I'd like confirmation to proceed.

• Identify which "in production" ATmega devices are "old style" devices without WDT Interrupt capability, and configure them to automatically use the 8-bit Timer0 as the System Tick. EDIT identification done, below.

• Add option to use a number of alternate 16-bit Timers with further configuration. As already noted, these 16-bit Timers are not configured consistently across all devices (or even across different Timers within one device) so providing them as a generalised solution is challenging.

Please comment and provide direction as needed.

[feilipu]

Heap Management

Most users of FreeRTOS will choose to manage their own heap using one of the pre-allocated heap management algorithms, but for those that choose to use heap_3.c, the wrappered malloc() method, there is an issue that needs to be addressed.

The avr-libc library assumes that the stack will always be above the heap, and does a check for this when responding to a malloc() request. This is not the case when Tasks are running, as their stack is located in the early allocated heap address ranges which will be below free heap memory, and so the malloc() request will fail even though heap space is available.

To avoid this issue causing pvPort_Malloc() to fail, the user needs to issue this tuning statement BEFORE they use the heap, or use the xTaskCreate() API.

if( __malloc_heap_end == 0 )
    __malloc_heap_end = (char *)(RAMEND - __malloc_margin);

Unfortunately in the repository there is nowhere sensible to include this statement, as it should be included early in the main() function.

[feilipu]

ATmega devices with ENHANCED WDT Interrupt capability - will use WDT.

• ATmega8U2/16U2/32U2 -> 2kB RAM
• ATmega16U4/32U4 - Arduino Leonardo -> 2.5kB RAM
• ATmega48PB/88PB/168PB/328PB - Arduino Uno -> 2kB RAM
• ATmega164PA/324PA/644PA/1284P - Goldilocks -> 16kB RAM
• ATmega324PB -> 2kB RAM
• ATmega640/1280/2560/1281/2561 - Arduino Mega -> 8kB RAM + XRAM

ATmega devices without enhanced WDT Interrupt capability - will use Timer0.

• ATmega8A/16A/32A/64A/128A -> 4kB RAM
• ATmega165A/165PA/325A/325PA/3250A/3250PA/645A/645P/6450A/6450P -> 4kB RAM
• ATmega169A/169PA/329A/329PA/3290A/3290PA/649A/649P/6490A/6490P -> 4kB RAM

ATmega devices without avr-libc support - unsupported at this stage.

• ATmega808/809/1608/1609/3208/3209/4808/4809 - megaAVR 0-Series -> 6kB RAM

[yuhui-zheng]

Did not finish review, sending preliminary feedback.

A couple details I would like to check after this round of review:

• watchdog timer related code path.
• timer setup. (It visually looks different since we are using 8-bit timer. I'd like to double check.)
• register names etc.

And, internal discussion is also going on in parallel. Will keep posting review feedback.

[yuhui-zheng]

I saw you have something in readme.md, about .lowtext --

Also, due to a limitation in GCC, the scheduler needs to reside in the lower 128kB of flash for both of these devices. This is achieved by adding the .lowtext section attribute to the function prototype.

Would like to get some more details on the "limitation of GCC" just to help understanding.

[feilipu]

The original conversation was in 2008, by stu_san on AVR Freaks. I won't paraphrase the details here.

My comment from 2012 showed I addressed the issue by adding a new section into the avr6.x linker script called .task. And more discussion here on my post from 2011 and specifically to the ATmega2560 here.

From avrlibc 1.8.0 (January 2014) there was a .lowtext section that was implemented in avr6.x, so I adjusted my repository to use that new section name, which also made modifying the default linker script unnecessary.

[yuhui-zheng]

I'll add TIMSK0 register bit map to this section. As per a former Microchip engineer, bit map may change on newer devices. Not a blocker for this PR.

[feilipu]

If you would like to add 16-bit Timer capability into this PR, I can do that too.

But, I'm not totally sure how to do it generally for all ATmega devices.
My experience is limited to these devices.

• ATmega8U2/16U2/32U2 -> 2kB RAM
• ATmega16U4/32U4 - Arduino Leonardo -> 2.5kB RAM
• ATmega48PB/88PB/168PB/328PB - Arduino Uno -> 2kB RAM
• ATmega164PA/324PA/644PA/1284P - Goldilocks -> 16kB RAM
• ATmega640/1280/2560/1281/2561 - Arduino Mega -> 8kB RAM + XRAM

But, let's get the WDT and 8-bit Timer0 done first.

[yuhui-zheng]

I agree. And I think 8-bit is sufficient for tick clock. Will check other's opinion on this.

[RichardBarry]

This port has needed a refresh for a long time! Some comments in the header file also apply to the C file.

[RichardBarry]

A couple of things that would be great here:

1. To provide a timer implementation that will work on all chips.
2. To have a backward compatibility option that uses the 16-bit timer as per the legacy port (to prevent breaking existing projects).
3. To enable users to use any clock they like by, for example, making prvSetupTimerInterrupt() a weakly defined symbol vPortSetupTimerInterrupt() allowing it to be instead be defined as part of the application (this is done in other FreeRTOS kernel ports for maximum flexibility and would bring this port up to date with the latest conventions).

[feilipu]

To 1. that is exactly the purpose of this path. The Enhanced Watchdog Timer (WDT) is available on all commonly used ATmega devices. It is configured simply and can be detected by the availability of the Watchdog Interrupt Enable (WDIE), and Watchdog Interrupt Flag (WDIF) provided by avr-libc. These flags are also configured consistently across all MCUs.

To 2. it becomes more challenging, as the numbering for the 16-bit Timers changes from MCU to MCU, as does their configuration and availability. It would be possible to provide a configuration for the ATmega32 (a legacy product), but this wouldn't be applicable to modern ATmega MCU. I've built a matrix of Timers vs MCU for a number of the common MCU types, but it is relatively complex and, as @yuhui-zheng pointed out, reserved bits are masked differently depending on the MCU too.

Happy to add 16-bit Timers as an example, but probably best to be left to the user to do final configuration.

To 3. I'd seek advice on how to best achieve that outcome. Perhaps reviewer edits?

[RichardBarry]

I presume these parts are singled out (doubled out?) because they have larger memory space. In general preference is not to have chip (as opposed to architecture) specifics in a port layer, especially if it puts a burden on the user to get the compile time options right, or the target chip family is likely to change in the future. So a couple of questions - is there a catch-all definition that can be use for all devices for which this special use case applies, or alternatively, can we just have this special use case apply to all chips no matter if they need it or not? [either way, the code as you have it now is better than the legacy code, which was very chip family specific.]

Is .lowtext something that always exists, or something the user will potentially trip up on if they don't have the correct linker script. If the latter is true then please update the comment to tell users how to fix any potential linker errors. (can just be a link to a forum post somewhere that tells people how to fix).

[feilipu]

The two parts ATmega2560 and ATmega2561 are the only two parts in common usage (and for the past 12 years at least) that need the 3 Byte PC solution.

Potentially they could also be differentiated by architecture by using the these options and providing the below.

#if defined(__AVR_3_BYTE_PC__)

This is more generic, so I'll fix it. EDIT fixed.

The .lowtext section is provided by the linker script in avr6.x. If the user has correctly nominated their device type in the compile line -mmcu=atmegaxxxx, then the correct linker script will be selected. It is automatic.

[feilipu]

There is an additional twist to this story in that two devices have both 256kB of Flash and needs __AVR_3_BYTE_PC__ and can address XRAM beyond 64kB and so has the __AVR_HAVE_RAMPZ__ register. These devices are the ATmega2560 and Atmega2561.

To cater for the ATmega1280 and ATmega1281, which have XRAM capability and the __AVR_HAVE_RAMPZ__ register, but don't have a 3 Byte PC, another option for portSAVE_CONTEXT() needs to be provided.

EDIT done.

[TintuVayalattu]

ATmega808/809/1608/1609/3208/3209/4808/4809 series is comparatively new.
It doesn't have a dedicated 8 bit timer Timer0. It has only 16 bit timers named TCA and TCB. These can be used in split-mode to create 8 bit timers if required. Also, TCA and TCB have completely different set of registers and bitmaps than that of legacy mega devices such as mega48PB/mega328PB. I think, with Timer0, this PR can't serve ATmega808/809/1608/1609/3208/3209/4808/4809. What do you think?

[feilipu]

Grrr. Yes. It is a totally different beast from the Timer point of view.

Looking at the data sheet, the best option seems to use the RTC with the internal 32kHz Oscillator in the Periodic Interrupt Timer (PIT) mode as the System Tick.

Using the same clock source as the RTC function, the PIT can request an interrupt or trigger an output event on every nth clock period. n can be selected from {4, 8, 16,.. 32768} for interrupts, and from {64, 128, 256,... 8192} for events.

The ATmega808/809/1608/1609/3208/3209/4808/4809 WDT doesn't have any interrupt capability, and I'd picked up that it couldn't be used. But I hadn't noticed the completely reimagined Timer solution.

I don't have any of ATmega808/809/1608/1609/3208/3209/4808/4809 that I can experiment with, so I'd suggest to work this out later. The initial datasheet was published in 2018, so it is very new.

[feilipu]

Further, I'm quite sure that avr-libc doesn't support this series of devices, as 2.0.0 was released in 2016. Without avr-libc, everything here is irrelevant.

The only option is to make a note that the megaAVR 0-series is unsupported.

EDIT checked that it is only the Timer architecture that is different, so support can be added in (provided the user configures their own prvSetupTimerInterrupt() function). So, now the megaAVR 0-series is supported.

[TintuVayalattu]

I think, megaAVR-0 series is of architecture avr8x - which is the same as xmega and few tiny devices. This is supported by avr-libc since the architecture was already existing.
I have one 4808. May be I can try after this got merged.

[feilipu]

Ok. That makes sense. I've not seen that avr8x architecture before.

Then it would be best to handle support as part of an ATxmega port.

Something to add later, or separately.

EDIT Searching for avr8x produces this interesting conversation. There be dragons.🐲

[yuhui-zheng]

Another solution I could think of is probably making prvSetupTimerInterrupt() in port.c external. We could provide example implementations in various projects, e.g. 8-bit/16-bit timer (as default probably), watchdog as a second clock source (for security initiatives), and RTC (for use cases concerning about clock skew). Users could determine which one(s) to use in their application scenario.

This may make sense, since all the timers we are talking about here are not part of the MCU core but rather peripheral. (In contrast to ARM, SysTick is provided in MCU core.) This will also make port cleaner...

[feilipu]

Agreed. As noted in another comment, putting the TimerN configuration into a separate file is what I do in practice. I usually hold all the timer configurations in a separate file called FreeRTOSBoardDefs.h, or FreeRTOSVariant.h for Arduino_FreeRTOS.

But, this is unrelated to the OP comment. Support for this new ATmega808/809/1608/1609/3208/3209/4808/4809 avr8x family is going to be difficult as the tool set required is not yet fully developed. Something that can be looked at as a future addition, imho.

[TintuVayalattu]

As far as I know, these devices(EDIT: megaAVR-0) are supported using a device spec file from DFP.
These devices are supproted in Atmel START and MCC for public. In fact, few IoT examples are also available in 4808 which consumes almost 90% of memory resources. Anyway, I can check and confirm if there is any limitation.

[feilipu]

I have checked the portmacro.h and port.c file from the v10.0.0 files included in an ATmega4809 example using FreeRTOS 10.0.0.

• portmacro.h - no relevant differences, but uses some depreciated gcc grammar.
• port.c - removed optional debugging bytes in pxPortInitialiseStack, only standard 2-byte stack management, and some depreciated gcc grammar.

I think, if the prvSetupTimerInterrupt() is kept as an external or weak, along with the portSCHEDULER_ISR definition being weak, there are is nothing preventing support for these megaAVR 0-series devices working.

I can add the small differences if desired.

EDIT @yuhui-zheng since it was only a few small things, I'm doing it anyway.
Sorry it breaks your review approval (again).

EDIT Done.

[yuhui-zheng]

A standalone comment -- I setup a project which runs with Atmel Studio simulator. https://github.com/yuhui-zheng/FreeRTOS/tree/atmega_port_demo/FreeRTOS/Demo/AVR_ATMega_AtmelStudio_simulator

I'll use this one to verify build at least. And if you are interested, could play with it as well. AVR_ATMega_AtmelStudio_simulator/README.md has included some details regarding to setup. (The project is configured to use ATmega2560, one 8-bit timer, one 16-bit timer, one WDT, and etc. And if to play with RTC, could reconfigure the project. But you'll notice, RTC is not so common in ATmega family.)

[yuhui-zheng]

Per internal discussion, we'd like to make this an ongoing effort to improve the port. Thus planning to merge this first before further changes. A couple of things we may consider:

• Putting this port temporarily under ./portable/ThirdParty/GCC. This port may get mature there, and be moved back. (We've done this with a couple of ports for licensing/quality control/other reasons. Mentioning, to not surprise you. If we decide to do so, I'll put things in a single PR so that rebase may be easier.)

• Either weak linkage or external linkage for prvSetupTimerInterrupt. We have existing examples for using weak linkage for functions implemented in porting layer. (This is assuming we have a good default implementation for target MCUs.) External linkage is also in consideration, since finding a default for all devices may be hard. (If using 16-bit timer is a good default for all ATmega devices, that's perfect.)

• Formatting. We'll do it in a separate PR.

I'll approve without merging for a little bit.

[yuhui-zheng]

I think we are missing #include <avr/wdt.h> in this file. In the simulator project I linked, WDTO_15MS is not recognized without #include <avr/wdt.h>

Also, if you try the simulator project, the tick count after vTaskDelay is off. The attached snapshot is from running with 8-bit timer. And in the FreeRTOS Viewer window you'll see every 100 ticks, the breakpoint at line 82 is triggered. (Since mainCHECK_PERIOD is configured to 100.) But when using WDT0_15MS, this is not the case anymore. (The fix may be simply using a matching WDT period setting. Prefer to be consistent... )

.

[feilipu]

I think we are missing #include <avr/wdt.h> in portmacro.h file.

Agreed. I usually hold all the timer configurations in a separate file called FreeRTOSBoardDefs.h, or FreeRTOSVariant.h, and forgot to move it over too.

This relates to your question about using a separate layer, for individual timer configuration, and in practice that is what I do.

EDIT added.

[yuhui-zheng]

I'd propose to use counter as default clock source. It's more aligned with other ports.

(But considering all the differences between various ATmega MCUs, maybe we should move tick timer initialization into application layer. No change request for now, let's decide where to put tick timer initialization.)

[feilipu]

Using the TimerN for the tick is normal practice. But the issue is that every MCU has different timers available, and each of these have different reserved bits. It gets very complex, as you've pointed out.

My personal preference is to use the RTC related timer (usually Timer2), which ensures that there no drift. But this relies on having an external 32kHz watch crystal implemented. Not a general solution.

The advantage of the WDT is simple and repeatable configuration across all the common "hobbyist" MCU versions (Arduino).

[yuhui-zheng]

Is the linker script provided by START or sample projects? Checking since we are relying on .lowtext section for behavioral correctness, though I'm not seeing this "populated" when playing with Atmel Studio. If no, we may want to consider explicitly document this...

[feilipu]

The linker script is provided by binutils-avr used with gcc. This PR is based on solely using the Open Source tools available for AVR. Nothing to do with Atmel Studio (although it would be doing the same thing under the covers, since it uses avr-libc too).

Look for /usr/lib/avr/lib/ldscripts/avr6.x in the binutils-avr package.

[feilipu]

Ok. I think I'm done here. @yuhui-zheng for review, etc.

[yuhui-zheng]

@feilipu Thanks. The change for reti and ret makes sense -- the return from vPortYieldFromTick() preserves SREG I bit, and the second return from ISR sets SREG I bit to reenable interrupt. I'll see if my simulator effort can better capture this in a test maybe.

Let's merge this PR, and make incremental changes to the port. I'll immediate follow up with a PR to move port to thirdparty directory per previous comment.