return value from micros() is inconistent on AVR vs SAM

[bperrybap]

The documentation here:
https://www.arduino.cc/en/Reference/Micros
states that the return value from micros() is an unsigned long.
From looking at wiring.h and wiring.c in both the AVR and SAM cores:

• return value is (unsigned long) on AVR
• return return value is a uint32_t on SAM

For additional reference:
The return value on Teensy3 uses uint32_t
The return value on ChipKit (pic32) uses unsigned long (which is 64 bits)

unsigned long and uint32_t are often not the same in 32 bit environments.
I'm not sure how to fix this as the code in the SAM and Teensy3 cores do not reflect what the API documentation says and I'm not sure what the implication of changing those cores to return an unsigned long instead of a uint32_t would be.

Was the intent for it to be a 32bit value or was it to be a "unsigned long" which means it will be at least 32 bits?
It might be better/clearer not to use unsigned long in the API documentation unless the code really does use that type .
There are other standard types that could be used to better reflect what was intended.
i.e. uint32_t, uint_least32_t

Or if unsigned long was really meant, then it seems like the code should be returning that type.

This can be a potential issue when writing library or sketch code that needs to work on many different cores.

i.e. I have code that needs to save the return value and use it later.

Also, there might be some rollover calculation issues when doing compares & math if the sketch/library moves the uint32_t into an unsigned long when the actual value is only 32 bits but unsigned long is 64.

I think in my code for the time being I'm going to cast the return value of micros() to be a uint32_t to work around any of these potential issues.

[matthijskooijman]

See also arduino/Arduino#4525, which starts about documentation, but the discussion talks about the actual types to be used in the code as well.

[cmaglie]

The "official" return type is unsigned long each core should implement micros using that return type.

ArduinoCore-API/api/Common.h

Line 113 in 27bb766

unsigned long micros(void);

The sam core should be fixed once this is merged: arduino/ArduinoCore-sam#39

Other 32 bit cores (even from 3rd party) uses uint32_t that is equivalent to unsigned long, while not correct in principle, in practice it should work without problems.

To me it seems that there is nothing more to discuss here, so I'm going forward and closing this one. Please reopen if I missed something.