Language-reference - please include more details on the internals.

It would be really useful if the functions within the LanguageReference included (perhaps as a footnote) more details on how they work:

For example, what (exactly) does digitalWrite() do?
What is the assembly code used?
How many instruction-cycles does it take?
What is the overhead?
If you already know the pin configuration, is there a faster command?

Also, there isn't really a good language reference for using inline assembly, and I think there should be, especially given that there are no byte-wide instructions within the basic library.

Thanks for your time.

Well, given that Arduino started as being for hobbyists and artists, and you seem well beyond that, you can figure some of this out.
The source code is all your machine.
The datasheet lists the clock cycles for each instruction.
Overhead for digitalWrite? The source code will tell you - but basically it checks that the pin is still set up for digital outputs before it makes the output high or low.
Faster - sure. Use direct port manipulation, and assume the direct data register is already correct:
I regularly use this to set clear D2 for example, after having used pinMode (2, OUTPUT); in setup.
PORTD = PORTD | 0b00000100; // set D2, leave rest alone
PORTD = PORTD & 0b00000100; // clear D2, leave rest alone
PIND = 0b00000100; // flip D2 output (high to low, or low to high)

Direct port manipulation is byte-wide. Most hobbyist/artists don't even know about assembler, so you're ahead of the game there too.

Thanks for your comments. I did know that, but it took quite a lot of digging to find it out. My point was really that the documentation is lacking. In particular, for a relative beginner, it's not very discoverable - and one ends up using the Arduino at a fraction of its capability. I wouldn't have even known that the Arduino had such capabilities, if I hadn't programmed PIC assembler once upon a time.

What I'd really like to see is:

  1. A more detailed explanation of how the functions are implemented (are they actually even functions, or are most of them simply macros?). I know the source is available, but it would be nice to have direct hyperlinks from the documentation.

  2. A list of Assembler instructions, and register details, which should be a "first class" part of the documentation, next to language and libraries. This is especially important when some aspects of the microcontroller are not available via the standard functions.
    I think this is more about having macros that save us from needing to know too much about the hardware addresses, rather than using assembler per-se. In your example, there is hidden knowledge that pinMode(2) applies to PortD masked with 0b100.

  3. Some extra functions as part of the language which should allow us to avoid recourse to embedded assembler or register-poking within the C program. For example a BitSet(13) instruction, which might do just the equivalent of the single-instruction "set bit within port", but with the appropriate macro-handling to allow "13" to refer to the digital pin 13, rather than having to worry about which underlying port it is. Likewise, I think ByteWrite() should really exist as a part of the language.
    In other words, it should be possible to get most of the advanced functionality out of the Arduino without having to resort to embedded ASM. Otherwise, much of the point of wrtiting in C is lost.

  4. Some more details on the compiler optimisations. For example, the canonical example is "int led = 13". But shouldn't that be "char", so as not to waste a pair of registers where only one will do? For that matter, will GCC optimise away the entire allocation of a register and in this context, treat it as equivalent to "const" ? How efficient is the compiler at fully utilising the underlying hardware?

Thank again for your time

Sorry; the arduino environment is aimed at beginners. If you want to learn at the level of detail you are asking for, you MUST learn how to find and read the manufacturer data sheets, the avr-gcc and avr-libc documention, books, tutorials, and classes on the C and C++ languages, and source code. None of this is part of "Arduino" itself; they're all separate projects/products. Arduino is just some glue and ADDITIONAL library functions that add "ease of use." (Your request is similar to "Excel is great, but microsoft should include information on the 8086 instruction set.")

it should be possible to get most of the advanced functionality out of the Arduino without having to resort to embedded ASM.

It is. You just have to figure out how, using resources outside the Arduino documentation (and perhaps outside the community. See the tutorials at for example.)

Well, some of that might happen eventually. In the meantime, happy digging :wink:
We moderators can't do much about it.

  1. Macros, functions, classes, whatever - most of the time it seems to that one is just digging in the weeds at that point. As a hardware designer, I don't care most of the time, unless I'm trying to make stuff run really fast - in which case it all seems to come down to direct port manipulation, arrays, and SPI tranfers.

  2. "having macros that save us from needing to know too much about the hardware addresses" was the main goal I think, making it easy for hobbyists/artists.
    Getting folks to make the jump from
    byte redButton = 2;
    pinMode (redButton, OUTPUT);
    that is, using descriptive names to describe the hardware, seemed a big advance to start.
    Software name "2" on the board mapping to physical pin whatever being actually connected to IO port D, bit 2, on some chip types despite being on 2 different physical packages, and to another port/bit altogether on another chip type, that seemed really clever to me.

  3. I think there are bit read and write commands. byte read & write are not so handy until you get to the bigger chips (1284, 2560) where whole bytes are actually brought out. I struggled with that to start, not having a complete 8-bit port usable on the 328P designs - serial got in the way, crystal got in the way, not all pins were brought out, etc. As I got into serial/SPI/I2C transfers, I kind of got over that. And eventually got into usingAtmega1284P instead to have 32 IO and whole ports to use for stuff.

  4. int led = 13; yeah, just bad example to start. I use byte myself, some use const & define, most times its just digging in the weeds. There's a whole website on the avr gcc compiler, everybody says the compiler does a pretty good job, so I don't worry much about it except when I'm really going for speed.

As Monty Python might say - is this the 5 minute discussion, or the full half hour? 8)

The thing is, 99.99% of the details you never need to know. That's the way technology is organised, and just as well, otherwise we would never be able to write a single line of code, if we had to know the operation of every gate inside the CPU. There is probably no one in Atmel who knows all that.

Similarly, the GCC compiler is over 7 million lines of code, I would strongly suggest not to learn the inside details!

The best way to learn about the source code is to read the source code. And the best way to improve it is to submit patches :slight_smile: