How to use assembly in Arduino?

The Arduino IDE is quite idiosyncratic. It won't let you work on a project that doesn't have a file with the extension “.ino”. On the other hand, it doesn't care about how much code is in that file, and you can keep it happy by creating an empty .ino file. I recommend however that you put at least a comment block in that file, in order to make things less confusing for other people who could see your project. Then you can put your assembly code alongside this empty file, in files of their own ending with the “.S” extension. These files will be preprocessed before being assembled, so you can #include <avr/io.h> and use the macros defined therein for the IO ports, bits, etc.

The project would look like this:

my_project/         # containing directory
├── my_project.ino  # comments only, to keep the IDE happy
├── my_project.S    # main assembly file
└── some_extras.S   # possibly more assembly files...

If the whole project is pure assembly, one of your assembly files should define a symbol called main, which is the entry point of the program:

.global main
main:
    ; code starts here

If you are going to mix assembly and C++, then you can define main() in the .ino file, and call from there your assembly routines, which should be declared as extern "C":

extern "C" void my_assembly_routine();

int main()
{
    my_assembly_routine();
}

Mind the calling conventions when mixing asm and C++ though.

If you are going to use the Arduino core library, then you should define setup() and loop() instead of main(). The Arduino core will then provide it's own main(), which takes care of its initialization.

If you are going to write mostly C++, with only some assembly sprinkled here and there, inline assembly could be a better option. C.f. Michel Keijzers' answer.

Sorry.

The main learning effect of this exercise is "Don't do it". You won't beat the c++ compiler regarding performance (speed). But you will run into more errors than you can imagine.

The only purpose of manual assembler language inside c/c++ is to add nanosecond timing by adding some asm("nop"); statements to wait a controlled small number of cpu clock cycles. @Michel Keijzers' examples are already implemented. Even in Arduino's convenience environment.

IMO it's more challenging to get beyond Arduino programming by going directly to the MCU's hardware level, dealing with Timers, other MCU components, Registers etc. directly. In C/C++ of course. There you learn that there's much more that can be done beyond the Arduino environment.

Or: Look at compiled results via avr-objdump to learn how C++ is compiled to machine code by experts. Very eventually, you might notice how you could help the compiler optimizing.

Re: "The main learning effect of this exercise is "Don't do it". You won't beat the c++ compiler..." I agree with Edgar Bonet: (1) Arduino is about learning, including learning Assembler programming, hardware, etc. And ... (2) Yes, you can beat the C++ compiler with a little practice. E.g. the GNU tool-chain can input the C++ program and output the corresponding Assembler. This can be very instructive for learning Assembler. You can then hand-craft any bit of that code...make it faster, or smaller --o-0--

You have to use the asm keyword, like:

asm("sei \n")

In your case it is advised to use defines, e.g.

#define CLI()          asm("cli \n")
#define noInterrupts() cli()

#define SEI()          asm("sei \n")
#define interrupts()   sei()

See more info at arduino-inline-assembly-tutorial-1.