Update PROGMEM reference page to recommend "const"

[PaulStoffregen]

The old AVR toolchain Arduino uses does not require "const" together with PROGMEM, but it accept const. But newer versions do require const.

This old documentation should be updated to recommend coding practice that is forward compatible.

http://arduino.cc/en/Reference/PROGMEM

It might also be good to mention Arduino Due, which doesn't use AVR PROGMEM.

[matthijskooijman]

While we're updating the PROGMEM page, perhaps the prog_char etc. stuff can also go? Since avr-gcc 1.8.0, those types are deprecated and it's ok to use the regular types (so just PROGMEM char foo;). The PROGMEM page is now confusing for people.

The Arduino itself already stopped using these types over a year ago (see 0acebee).

[c00kiemon5ter]

It's been 7 months and prog_* is still on that page, eventhough deprecated.
This should really be cleaned and so should the source.

Starting with #795 , #1695 and #1448 tried to fix this in the source level,
but it seems there are still occurances of prog_* in the code.

Occurances of prog_char still exist in:

./hardware/arduino/bootloaders/stk500v2/avrinterruptnames.h
./libraries/GSM/GSM3ShieldV1ModemCore.cpp
./libraries/GSM/GSM3ShieldV1BaseProvider.cpp
./libraries/GSM/GSM3ShieldV1ModemCore.h
./libraries/GSM/GSM3ShieldV1BaseProvider.h
./libraries/Robot_Control/utility/scripts_Hello_User.h
./libraries/Robot_Control/examples/explore/R06_Wheel_Calibration/scripts_library.h

while prog_ seems to appear in:

./hardware/arduino/firmwares/wifishield/wifi_dnld/src/SOFTWARE_FRAMEWORK/DRIVERS/FLASHC/flashc.c
./hardware/arduino/firmwares/wifishield/wifi_dnld/src/SOFTWARE_FRAMEWORK/DRIVERS/FLASHC/flashc.h
./hardware/arduino/firmwares/wifishield/wifiHD/src/SOFTWARE_FRAMEWORK/DRIVERS/FLASHC/flashc.c
./hardware/arduino/firmwares/wifishield/wifiHD/src/SOFTWARE_FRAMEWORK/DRIVERS/FLASHC/flashc.h
./hardware/arduino/bootloaders/stk500v2/avrinterruptnames.h
./libraries/GSM/GSM3ShieldV1ModemCore.cpp
./libraries/GSM/GSM3ShieldV1BaseProvider.cpp
./libraries/GSM/GSM3ShieldV1ModemCore.h
./libraries/GSM/GSM3ShieldV1BaseProvider.h
./libraries/TFT/utility/Adafruit_ST7735.cpp
./libraries/Robot_Control/utility/scripts_Hello_User.h
./libraries/Robot_Control/examples/explore/R06_Wheel_Calibration/scripts_library.h
./libraries/Robot_Control/Arduino_LCD.cpp
./libraries/Robot_Control/Arduino_LCD.h

from the above avrinterruptnames.h #defines prog_char to plain char

[c00kiemon5ter]

Looking into the avr changes for 1.8 it looks to me that the right replacement for the deprepcated prog_* is to use the PGM_P macro with const much like what #1695 did.

ie, in libraries/Robot_Control/utility/scripts_Hello_User.h

const prog_char hello_user_script1[] PROGMEM="What's your name?";

should become

PGM_P const hello_user_script1 PROGMEM="What's your name?";

I will try to find some time and make the changes, then test the result.
If anybody is up to this, do go forward and report your findings.

[matthijskooijman]

You're right that PGM_P is the backward-compatible replacement for prog_char *. However, realize that declaring a char * is not the same as declaring a char[]. Specifically, this line:

char foo[] = "123";

declares a four-element array, which is initialized to {'1', '2', '3', '\0'}. In other words, the size of the foo variable is four bytes. Whereas this line:

char *foo = "123";

causes the string "123" (e.g., four bytes with values {'1', '2', '3', '\0'} to be put into memory somewhere, and the variable foo will be a pointer variable initialized to the address of those four bytes. This means that the foo variable is two bytes in size, but the total memory usage is six bytes (but if the string "123" is used more than once, those four bytes can be shared between usages).

Now, I think this means that the line:

PGM_P const foo PROGMEM = "123";

will put the two-byte pointer in PROGMEM, but the actual string in regular memory. I haven't this, but this is how I understand how things should work.

However, the changelog you linked says:

The reason for this was that these type names have proven to be not useful in any way, since actually taking care of using the proper access methods when accessing objects declared that way has always been in the responsibility of the developer anyway. There is nothing the compiler could do technically to prevent the developer from erroneously using the wrong access method (SRAM vs. flash ROM).

Which suggests to me that the prog_* types have been added to avr-libc in an attempt to improve error detection / automatic loading of progmem variables later on, but this never worked out. I also suspect this means that these types really never had any actual value and thus could be simply removed altogether, without breaking compatibility with older gcc versions?

[cmaglie]

See also #2647 #2122

[svgeesus]

Where is the repository for the Arduino reference pages? I would submit pull requests for documentaton updates, except that the content does not seem to be in this repository.

[ffissore]

@Nantonos we are working on improving the way people may contribute to the documentation. Stay tuned

[svgeesus]

Hello Federico,

Wednesday, February 18, 2015, 8:43:20 AM, you wrote:

@Nantonos we are working on improving the way people may contribute to the documentation. Stay tuned

Excellent, great news.

With 1.0.x it seemed that the documentation shipped locally and the
online documentation were different. Was that issue fixed now that
1.6.0 is out?

Best regards,
Nantonos mailto:[email protected]

[cmaglie]

Yes, 1.6.0 has an updated snapshot of the documentation.

[agdl]

@Nantonos here https://github.com/arduino/reference-en the repo. We are still working on the documentation but you can contribute :)

[svgeesus]

Hello Arturo,

Friday, February 20, 2015, 10:34:43 AM, you wrote:

@Nantonoshere https://github.com/arduino/reference-enthe repo. We
are still working on the documentation but you can contribute :)

Excellent, thanks for the pointer.

Best regards,
Nantonos mailto:[email protected]

[agdl]

@Nantonos reference updated let me know if you have any suggstion or improvement so i can include them both online and in the new repo :)

[svgeesus]

Hello Arturo,

Friday, February 20, 2015, 1:05:18 PM, you wrote:

@Nantonosreference updated let me know if you have any suggstion or
improvement so i can include them both online and in the new repo :)

Looking on
https://github.com/arduino/reference-en/blob/master/Language/Variables/Utilities/PROGMEM.adoc
I see one use of const in an example, but no text recommending const
or explaining why it is needed on newer gcc versions.

It would also be good to see discussion of how this is an AVR feature
and not applicable (except as AVR emulation for legacy code) on other
architectures such as the SAM on Due. Because this has been a topic of
discussion:

http://forum.arduino.cc/index.php?topic=155158.0

and is a known compat issue
#1317
(as that issue is closed I assume Due has an avr/pgmspace.h compat
layer now? if so, the PROGMEM page should discuss it.

Would you prefer that I fork this repo and submit pull requests, or discuss
improvements on this list?

Best regards,
Nantonos mailto:[email protected]

[agdl]

@Nantonos i pushed online a new PROGMEM reference here http://arduino.cc/en/Reference/PROGMEM you can use it as template to improve the documentation. Please if you want to contribute fork the repo and submit a PR!

[agdl]

ok you can fork it now