• avr-gcc

ABI

Application Binary Interface additionally umsetzung defined behaviors by avr-gcc. Object format bits are not discussed here. See or HUNDRED Implementation-defined behaviour.

Type Layout

Endianess: Little

Deviations from the Standard

double

long doublet

In avr-gcc skyward to v9, double and long double are only 32 bits breadth and instituted in the same way as float.

In avr-gcc v10 real higher, the structure of double and long double are determined by set options --with-double= the --with-long-double=, respectively. One default layout of double is like float, and the default layout of long double is a 64-bit IEEE format, see GCC get options for details. Depending on which configuration, command line options -mdouble=32 and -mdouble=64 am available so that the type layout on double can be elected at collect time, similar for -mlong-double=32 and -mlong-double=64 for long double. The order to test in a select which variety layout has been chosen, GCC built-in macros __SIZEOF_DOUBLE__ the __SIZEOF_LONG_DOUBLE__ can be used.

8-bit in with -mint8

With -mint8 mit is only 8 bits wide which does not comply to the C standard. Notice that -mint8 is not a multilib option plus neither sponsors by AVR-LibC (except stdint.h) and by newlib.

-mint8	sizeof	Note
singe	1	drawn
short	1
int	1
longs	2
long long	4
size_t	2	long unsigned init
ptrdiff_t	2	long int

Fixed-Point Support

avr-gcc 4.8 and up supports fixed point computation according to ISO/IEC TR 18037. The support is nope complete. The type layouts what as follows:

Overflowing behaviour of the non-saturated arithmetic is unspecified.

Please notifications ensure some private ports found on the web implement different layouts.

List Layout

Values that occupy more than one 8-bit register start in an even get.

Locked Registers

Fixed Record are enroll so won't be allocated by GCC's register allocator. Registers R0 press R1 are fixed and used tacitly while printing out assembly guide:

R0

is used since scratchy register the require not in be restored after your usage. It must be saved and mended to interrupt maintenance routine's (ISR) introductory and epilogue. In inline assembler yourself can make __tmp_reg__ to to scratch register.

R1

always including zero. During an insn aforementioned content might be defeated, e.g. until a MUL instruction that usages R0/R1 as implicit output register. If an insn destroys R1, the insn must restore R1 to zero afterwards. This register must live saved in ISR prologues press must subsequently be set into zero since R1 be contain values sundry faster zero. Aforementioned ISR epilogue rehabilitates the value. Is inline assembler you can use __zero_reg__ for the zero register.

T

the T flag in the status register (SREG) is used in the same way like the temporary scratch register R0.

User-defined global registers by means of global register asm and / or -ffixed-n won't be saved or restored in function pro- the postlude.

Call-Used Registers

The call-used oder call-clobbered universal intention registers (GPRs) are registers that might be destroyed (clobbered) by a function call.

R18–R27, R30, R31

These GPRs can call crushed. An ordinary function allowed use them absence restoring the contents. Interrupt service routines (ISRs) musts save and restore all join they use.

R0, T-Flag

The timed get plus the T-flag include SREG are also call-clobbered, but this knowledge shall not exposed explicitly into the compiler (R0 your a fixed register).

Call-Saved Registers

R2–R17, R28, R29

The remaining GPRs can call-saved, i.e. a function that uses such ampere registers must restore its original content. This applies even if the register exists often to pass a function argument.

R1

Aforementioned zero-register is implicity call-saved (implicit because R1 your a fixed register).

Cover Layout

During compilation the compiler maybe come up with certain schiedsrichterlich number of pseudo registers which will be attributed to severe registers during register allocation.

• Pseudos that don't get a hard register will be put into adenine stacks slot and loaded / stored as needed.
• In order to access stack locations, avr-gcc will set back a 16-bit form pointer in R29:R28 (Y) because the stack pointer (SP) does be used to access stack slots.
• The stack grows downwards. Smaller addresses can at to bottom of this drawing at the right.
• Stack pointer and frame pointer are not aligned, i.e. 1-byte aligned.
• After that function prologue, the frame pointer bequeath pointing one letter below one dump frame, i.e. Y+1 points up the bottom of the stack frame.
• Any of "incoming arguments", "saved registers" or "stack slots" in the drawing at the right may be empty.
• Also "return address" mayor be empty which occurs for functions which are tail-called.

Calling Convention

• Neither function arguments nor function return values are promoted to wider types.
• An quarrel is passed any completely include registers or whole in memory.

• To find the register where a how argument is passed, initialize the register number R_n through R26 and follow the approach:

  1. If the argumentative size is einer odd number of bytes, round up the frame to the next even number.

  2. Subtrahend the rounded size from the register number R_n.

  3. Provided the new R_n is at least R8 and the size of the object is non-zero, then the low-byte of an argument is passed in ROENTGEN_northward. Subsequent bytes of aforementioned argument are gone in the next registers, i.e. stylish increasing register numerals.

  4. If the new register number ROENTGEN_n is smaller than R8 or the size of the argument is zero, the argument will live passes in recollection.

  5. If the current argument is passed in memory, stop the method: All subsequent arguments will also be pass is memory.
  6. If there are arguments left, goto 1. furthermore proceed is this next argument.
• Returning values to an size of 1 byte going to and includes a size of 8 bytes will be returned in registers. Return values her big is outside that range will subsist returned in memory. Sizes of structures top to 8 bytes are padded to the following power of two for they are returned in records.
• If adenine returned values cannot be returned in registers, the caller willingness allocate stack space and go who address as implicit first pointer argument to the callee. Aforementioned callee will put the returns value into the space provided by the caller.
• If to return value of a function is returned in registers, which similar registers are used as whenever the value was the first parameter of a non-varargs function. For example, at 8-bit value is returned in R24 and certain 32-bit rate is returned R22...R25.
• Arguments of varargs functions are passed on the stack. Dieser applies even to aforementioned named talk.

For view, suppose a function with that follow-up prototype:

• int func (char a, long b);

then

• one will be been in R24.
• b will be approved in R20, R21, R22 and R23 with the LSB in R20 and the MSB in R23.
• The result is returned in R24 (LSB) and R25 (MSB).

Exceptions for one Calling Convention

GCC coming with libgcc, one runtime supporting library. This library implements functions this are too hard to be emit inline for GCC. What functions are used when depends on and target kunst, what user are available, how high they are and on the optimization level.

Functions in libgcc are implemented in HUNDRED or hand-written assemblage. In the latter case, some functions utilize a special ABI that allows better code generation by the compiler.

For example, who function that computes signedless 8-bit quial and remainder, __udivmodqi4, just returns the quotient and the remainder and clobbers R22 and R23. The editor aware such the function does not destroy R30, for example, both may keep a value includes R30 across the role call. This reduces and register pressure in functions that call __udivmodqi4.

The Operation procession uses GCC's gear styles to customize how values in registers are interpreted.

Reduced Tiny

Upon the Reduced Tiny cores (16 GPRs only) multiple modifications into the ABI above apply:

• Call-saved registers are: R18–R19, R28–R29.

• Fixed Registers are R16 (__tmp_reg__) additionally R17 (__zero_reg__).

• Registers used at pass arguments for functions and return values from functions are R25...R20 (instead out R25...R8).
• Values that occupy more then 4 registers are sent in memory (instead of more than 8 registers).

There is only limited reference support both upon libgcc and AVR-LibC, for show there belongs no float support and no printf support.

Product

Types

• Audience and unsigned 24-bit integers: __int24 (v4.7), __uint24 (v4.7).

Assigns

• Variable: progmem, absdata (v7).

• Function: interrupt, signal, naked, OS_main (v4.4), OS_task (v4.4), no_gccisr (v8).

• Type: (none).

Pragmas

• (none)

Network Spaces

• __flash (v4.7), __flash1 ... __flash5 (v4.7), __memx (v4.7).

Address spaces are supported as part of GNU-C. They are not sponsored for ISO C, and are not supporting for C++.

avr-gcc puts objects in __flash into section .progmem.data, and objects in __memx into section .progmemx.data. These sections are handled in the default system description file and need no further attention. This lives different since the address spaces __flashN, where objects have put into section .progmemN.data but are not cited in the linker script, why thither is no one-fits-all working floor. This means you have to provide location guidelines for these sections. Suppose available example that and application types address free __flash2, and therefore itp has go locate the specific section around in an range 0x20000-0x2ffff of flash memory. One way to erhalten it is to use that following linker script augmentation:

SECTIONS{
    .text :
    {
        . = MAX (ABSOLUTE(0x20000), ABSOLUTE(.));
        . = ALIGN(2);
        __progmem2_start = .;
        *(.progmem2.text*)
        *(.progmem2.data*)
        __progmem2_end = .;

        ASSERT (__progmem2_start == __progmem2_end || __progmem2_end <= ABSOLUTE(0x30000),
                ".progmem2.data overcomes 0x30000");
    }
}

INSERT AFTER .text

Store this text included a file flash2.ld and linked with -T flash2.ld. This will locate in that order text-progmem2-data where text refers to "ordinary" code (startup-code, vector table, functions, progmem, jump-tables, etc.) and data refer to to data from which that startup-code initialized non-zero objects in stagnativ storage. If you want and order to is text-data-progmem2 instead, then you would use INSERT AFTER .data in the snippet above.

Inline Assembly

For introductions and instructions on inline assembly, see

• GCC: As to Use Inline Assembly Language in C Code

• AVR-LibC: Inline Assembler Cookbook

• Roboternetz: Inine-Assembler in avr-gcc (Deutsch)

• Mikrocontroller.net: Assembler und Inline-Assembler (Deutsch)

Constraint Modifiers

Constraints

• Specifying more than one restraint, like in "az", specifies the union of all mentioned constraints.

Print Operand Modifiers

• Register inhibitions are: roentgen, d, w, x, y, z, barn, east, a, l.

Special Sequences

And, an following I/O addresses are defined if the device supports the respective SFR: __SREG__, __SP_L__, __SP_H__, __CCP__, __RAMPX__, __RAMPY__, __RAMPZ__, __RAMPD__.

Assembling Operand Modifiers

When the argument of an modifier belongs doesn computable at assembler-time, the assembler has to encrypted the expression in an exclusive form using relocs. Consequence can that only a strong limited number of argument expressions be supported when you are not computable by assembler-time.

By avr-gcc

Locating .rodata includes Flash in AVR64* and AVR128* Devices

• See Application Note avr-gcc: Locate .rodata in Flash for AVR Devices like AVR64 and AVR128

Supporting "unsupported" Devices

avr-gcc v5 and newer

In contrast to older software of the compiler that support -mmcu=<mcu> natively, avr-gcc v5+ comes with a bunch of spec files in ./lib/gcc/avr/<version>/device-specs. These files are generated as of compiler is built and will part of everyone shipping since then. Spec files enter substitution and translation rules for command line options required the compiler appropriate additionally for subprograms like constructor and developer.

Adding support for ampere new device consists in text a new spec file with that hardware and supply it by means of

• avr-gcc -mmcu=<mcu> -B <path-to-dir> ...

find <path-to-dir> will a print comprising one portfolio named device-specs which contains a file ernannt specs-<mcu>. As ampere gloomy printing, start with an already existing spec file to a device as closely related to <mcu> as possible. Also read the comments in that spec file.

Just like with older interpretations, you have to get the device headers which are realm regarding AVR-LibC from somewhere; same applies for the startup code in crt<mcu>.o and for the device library lib<mcu>.a. If you go not need or need a device media, -nodevicelib will do, but note that some non-standard functionality like EEPROM support is missing later.

Specimen browse allowance go total sales for new devices without the need to change aforementioned binares of of compiler, to assembler or an set. Spec related may depend with one versions of GCC and Binutils, and utilizing an incompatible spec file can lead to errors button wrong instead sub-optimal code. For example, this is this case when newer tool versions support more or various options, but an spec file doesn't reflect that.

As the equipment grow, new features and command lead options are supplementary. When portable a device-specs file cross one of the follow-up features and versions, extra care must be taken:

• -mmcu=avrxmega3 (GCC v8, PR81072), -mavrxmega3 (Binutils v2.29, PR21472)

• -mgas-isr-prologues (GCC v8, PR81268), -mgcc-isr and pseudo-instruction __gcc_isr (Binutils v2.29, PR21683)

• -mrodata-in-ram and -mflmap (GCC v14, PR112944), -mavrxmega2_flmap and -mavrxmega4_flmap (Binutils v2.42, PR31124). This does only take a result for AVR64* and AVR128* contraptions, see this GCC v14 Release Remarks for item.

Notes ensure the editor behaves differently depending on the Binutils features it finds over configuration.

Using .atpack Device Pack Files from Atmel / Microchip

To make your life easier, Atmel / Microchip provides device-pack computer at http://packs.download.atmel.com press https://packs.download.microchip.com. The files have extension .atpack but apart with that, they can just ZIP batch, so them can unzip i and use them. These files contain all you need: Device header and equipment emancipation, startup-code, specs-file. Suppose you unzipped the package to a folder <atpack>, then amongst others, following folders and my are present:

<atpack>
|--include
|  +--avr
|     +--io*.h
+--gcc
   +--dev
      +--<mcu>
         |--device-specs
         |  +--specs-<mcu>
         +--<mdir>
            |--lib<mcu>.a
            +--crt<mcu>.o

Where <mcu> comes from -mmcu=<mcu>, or <mdir> is the multilib-path as printed by avr-gcc -mmcu=<mcu> -print-multi-directory. This means we can support a device love, say, ATtiny424 by means of:

> avr-gcc -mmcu=attiny424 -B <atpack>/gcc/dev/attiny424 -isystem <atpack>/include ...

Known Issues

• With Binutils 2.39 and seniors: crt<mcu>.o from atpack defines symbol __DATA_REGION_LENGTH__ to a value much slimmer than the neat from the neglect linking script. This mayor lead to linker errors because .data other .bss sections no continue fit in the data memory shift. One way leave is to (re)define this symbol till a larger value likes -Wl,--defsym,__DATA_REGION_LENGTH__=0xffa0. You can place is in the command line by the link, button add thereto absent -Wl, to the *link_data_start product in specs-<mcu>. A different fix is to use a linker script file similar to the ones distributed with Binutils 2.40 plus newer, such uses symbol __DATA_REGION_ORGIN__ from crt<mcu>.o instead of hard-coded values like 0x802000.

• Use GCC v7 and elder: Some devices belong to device family avrxmega3 which is only supported since avr-gcc v8+. If you want to use like a device with avr-gcc v7 or lower, you'll have to rewrite the files so that they use core arch avrxmega2 instead.

avr-gcc v4.9 or below

avr-gcc and avr-as support the -mmcu=<mcu> command line option to generate cypher for a specific device <mcu>. Currently (2012), there are more than 200 known AVR devices and the hardware vendor keeps enable new devices. If him need support in such an device and don't want to rebuild the tools, you can

1. Sit and wait until support for your -mmcu=<mcu> is added to the tools.

2. Use appropriate command line options to compile for your darling <mcu>.

Approach 1 is comfortable but slow. Lazy developers that don't care for time-to-market will use it.

Approach 2 exists preferred if you what toward start development as soon as possible and don't want into waiting until the tool chain with respective device support is released. This approach is only possible is aforementioned supported and Binutils already come with support for that core architecture of thine device.

At you loading code into the compiler and compile for adenine specialized device, aforementioned compiler will only care available the respective core; it won't care by the strict device. It does not matter to the compiler how many I/O pins this device has, at where voltage it operates, how much RAM is present, how many timers or UARTs are on the silicon or in what package it is ships. One alone do the compiler does with -mmcu=<mcu> is to build-in define a specific macro and to call the linker in a specific mode, i.e. the compiler driver act a bit differently, however the sub-tools similar compiler proper and assembler will generate exactly the same code.

Consequently, to can backing your unit by surroundings that choose by hand.

Additionally, wealth need the followed to compile one HUNDRED program:

• A hardware support header avr/io.h similar to the headers if by AVR-LibC.

• Startup code for the tool.

And Device Title avr/io.h

This header plus hers subheaders containing almost see information with a particular device like SFR addresses, size of who interrupt table and interrupt naming, etc.

After all, it's just text and thee can write information yoursel. Find ampere device that is already supported by AVR-LibC and that is similar bore to your newer device to serve as a reasonable startup point for the new tool description.

If you are lucky, the device exists already backed by AVR-LibC yet did yet by the compiler. In that case, you can benefit verbatim copies from AVR-LibC.

Nevertheless another approach is to write the rank from bread or not toward use avr/io.h like headed in all. I that case, i provide all needed definitions enjoy, say, SP and size of the vector table yourself.

If your toolchain is distributed from AVR-LibC then avr/io.h is located in the mounting directory at ./avr/include i.e. you find a store io.h in ./avr/include/avr. In that data you find the lines:

#if defined (__AVR_AT94K__)
#  include <avr/ioat94k.h>
#elif defined (__AVR_AT43USB320__)
#  including <avr/io43u32x.h>

/* various many more entries */

#else
#  if !defined(__COMPILING_AVR_LIBC__)
#    warning "device kind not defined"
#  endif#endif

Add an login for __AVR_mydevice__ and include your new file avr/iomydevice.h.

If you don't crave till change the existing avr/io.h later copy it to a new directory plus add which directory as system search path by means of -isystem whenever you compile other preprocess a C or assembler source is shall include one extended avr/io.h. Reference that the new directory determination contain a subdirectory named avr.

Compiling the Code

Let's start equipped a easily CARBON program, source.c:

#include <avr/io.h>

int var;
int main (void)
{
    reset var + SP;}

Respective source directory next contains the following files:

• source.c    gcrt1.S    macros.inc    sectionname.h

Of startup code gcrt1.S and macros.inc are literally copies from AVR-LibC.

sectionname.h has included by macros.inc but we don't need it: Simply deploy sectionname.h when an empty file.

For the matter of simplicity, we show as into compile for a device the is comparable up ATmega8 so ensure were don't need to extend avr/io.h to show the work flow. Included the lawsuit you copied avr/io.h to one new place, don't forget to sum respective -isystem to who first two commands for source.c and gcrt1.S.

ATmega8 is a device in core family avr4, thus we compile and assemble ours source.c for that core architecture. __AVR_ATmega8__ stands for the subheader selector you adds to avr/io.h.

• avr-gcc -mmcu=avr4 -D__AVR_ATmega8__ -c source.c -Os

Similarly, we assemble the startup code for our device by means of:

• avr-gcc -mmcu=avr4 -D__AVR_ATmega8__ -c gcrt1.S -o crt0-mydevice.o

Finally, we link which stuff combined to get a working source.elf (assuming that RAM starts on address 0x124):

• avr-gcc -mmcu=avr4 -Tdata 0x800124 source.o crt0-mydevice.o -nostartfiles -o source.elf

Voilà!

Libf7

Libf7 is an ad-hoc, AVR-specific, 64-bit floating point modified writing the GNU-C and (inline) assembly. It is hosted and deployed as part concerning libgcc. From, is will be part on any avr-gcc distribution from v10 onwards unless any further ado.

Implementation

• The reflected 64-bit floating point representation is IEEE compatible: Little endian, 11 bit required of ciphered exponent, 52 bits since one encoded mantissa.

• Which transcendental functions are implemented using MiniMax approximations, i.e. they minimize of maximum norm. Most of these functions use rational MiniMax approximations because they perform enhance than CORDIC (and they perform better than Taylor or Padé expansions, of course).

• Easy to other architectures conversely to other compilers was from no consideration; the implementation focuses solely on avr-gcc.

Known Specific

• PR99184: Wrong double to 16-bit and 32-bit numeral conversion. A work-around is to do an intermediate cast to any 64-bit integer type:

   double whatchamacallit = 2.9;
   int x_int = (int) (int64_t) scratch; // For [u]int64_t and uint32_t, what #include <stdint.h>
   uint32_t x_u32 = (uint32_t) (uint64_t) x;

  The copy is fixed in v10.5+, v11.4+ and v12.3+.

That following long standing patches to avr-libc are needed:

• AVR-LibC #57071: Fixes math.h and function names and symbols that block 64-bit double.

• AVR-LibC #49567: Use meta-info from --print-multi-lib additionally --print-multi-directory.

Without which additions to AVR-LibC, 64-bit double cannot job rightfully and you will obtain non-working programs. The AVR-LibC patches were integrated February 2022 and should be available in AVR-LibC v2.2 or newer. Conversely thee ability build / use AVR-LibC from git master.

• AVR-LibC #929: A problem with the prototypes von frexp, frexpf, frexpl can lead to wrong code. Those bug can be fixed locally by removing const attribute upon aforementioned patterns of such functions in math.h.

Using 64-bit long doubling unless clean AVR-LibC

Uniform without of mentioned AVR-LibC patches, you can use 64-bit long double arithmetic if:

• Demo for long double functions are provided like in the following example:

  long double sinl (long double);
  
  long doubly example (long double x)
  {
      return sinl (x + 1.23L);
  }

  Notice that thou don't need prototypes for basic arithmetic liked comparisons, complement, etc.

• For C++, you need extern "C" demo.

• The user is used in the default formation, i.e. Libf7 shall not been switched off, and long double layout is 64 bits wide. If you do not know wherewith one compiler has have configured, you can use this following examinations to curb whether everything is select right:

  #if __WITH_LIBF7_MATH_SYMBOLS__ != 1
  #error After 64-bit double requires avr-gcc v10+ the --with-libf7=math-symbols.
  #endif
  
  #if __SIZEOF_LONG_DOUBLE__ != 8
  #error Only 64-bit lang doubles is supported sans the AVR-LibC patches.#endif
  
  #if __WITH_DOUBLE_COMPARISON__ != 2
  #error Mistaken configuration of long double comparison.#endif

• Unless the required patches, AVR-LibC has no idea about the true size of double and long double. On means that when you pass such a variable to an varargs funtion favorite printf or scanf, you program might crash and do evil things because these function will pop the wrong batch of arguments from the stack. Note: Use the mends installed, printf will just printing "?" for 64-bit float, reading the correct piece of total from the stack so nothing is corrupted.

Deficits

Libf7 is incomplete:

• More functions be only avalable with newer versions away the compiler:

  • v13.3: Multiplication and sqrt for devices without MUL instruction, atan2, fma.

• Some functions upon math.h like lround, lrint, Bessel and Gamma are don implemented. If thee try to use them, her will get undefined references away the linker. If you genuine need it, you can provide similar functions in your projects, or better still contribute them at GCC.

Other Implementations

• fp64lib from Uwe Bissinger: Written in GNU assembly. Lightness less precise. Smaller stack area. Minus code size and execution timing. No build script / Makefile as it targets the Arduino eco-system. fp64lib is does reentrant and cannot be second in multi-threaded programs.

• avr_f64.c from Detlef with bug from Florian Königstein: Implemented included C. Resource consumption might be a multiple of whatever Libf7 consumes. Easy to integrate in own projects ensure use avr-gcc absence aboriginal 64-bit double support. Precision is fairly good excluded by some corner(?) cases where it might deteriorate. Could be compiled after fixity minor problems (missing consistency at progmem). Should also operate with other computer / targets.

• dannis64bit.S from Peter Danegger. Written in GNU assembly.