ESP8266 Developer Zone

Re: Meaning of ICACHE_FLASH_ATTR

2016-07-09T22:16:26+08:00

mkeyno wrote:
what is the benefits to put the function in different type of memory , if is due to speed how much each section has different

Hello,

The speed difference might not be much if you are running your code off 80MHz QIO flash. Typically, assuming ideal conditions, you may have a 15-20% code execution speed increase by using IRAM instead of CACHE.
However, if you share the primary flash SPI interface to drive IO expanders or communication chips, you should run code from IRAM when the code cannot fit in the cache. That can make a big difference at times.

Do note that the LOADING SPEED and EXECUTION SPEED are two completely different things. Running a huge inline routine with no loops from IRAM will not be much faster than CACHE mode.
However, for applications like ciphers or other complex looping code, IRAM will prove way better than the CACHE. The loading time is the same - only execution times make the big difference.
Hope that helps!

Statistics: Posted by Guest — Sat Jul 09, 2016 10:16 pm

Re: Meaning of ICACHE_FLASH_ATTR

2016-07-09T22:09:48+08:00

NiclasH wrote:
Very interesting thread. I got here because I wanted to find out what does this ICACHE_FLASH_ATTR means, and to my surprise the c_types.h showed;

Code:
#define ICACHE_FLASH_ATTR

i.e. nothing!!!!

And that definition doesn't match dkinzer's (probably) pasted code from c_types.h back at that time.

SO, I ran a test, just to make sure. And yes, this macro has no meaning in my SDK (ESP8266_RTOS_SDK_V1.4.0/), exactly the same binaries are produced no matter if I add or remove it.

The definition now is;

Code:
#define __packed __attribute__((packed)) #define STORE_ATTR __attribute__((aligned(4))) #define SHMEM_ATTR #define ICACHE_FLASH_ATTR #define DMEM_ATTR __attribute__((section(".bss"))) #define IRAM_ATTR __attribute__((section(".text"))) #define ICACHE_RODATA_ATTR __attribute__((section(".irom.text")))

So, I guess that for stuff that I really need in IRAM (interrupt routines and Flash FS), should be marked with the IRAM_ATTR macro, and data that is totally constant could be marked with ICACHE_RODATA_ATTR.

Is there anyone that can confirm this?

Cheers
Niclas

Hello Niclas,
As mentioned in the SDK getting started guide, all functions are stored in CACHE area by default since ESP8266_RTOS_SDK_v1.2.0.
You need not add the attribute anymore to every function.
And you are correct about IRAM and RODATA part.

Statistics: Posted by Guest — Sat Jul 09, 2016 10:09 pm

Re: Meaning of ICACHE_FLASH_ATTR

2016-07-09T17:03:59+08:00

what is the benefits to put the function in different type of memory , if is due to speed how much each section has different

Statistics: Posted by mkeyno — Sat Jul 09, 2016 5:03 pm

Re: Meaning of ICACHE_FLASH_ATTR

2016-05-26T18:22:13+08:00

Very interesting thread. I got here because I wanted to find out what does this ICACHE_FLASH_ATTR means, and to my surprise the c_types.h showed;

Code:

#define ICACHE_FLASH_ATTR

i.e. nothing!!!!

And that definition doesn't match dkinzer's (probably) pasted code from c_types.h back at that time.

SO, I ran a test, just to make sure. And yes, this macro has no meaning in my SDK (ESP8266_RTOS_SDK_V1.4.0/), exactly the same binaries are produced no matter if I add or remove it.

The definition now is;

Code:

#define __packed            __attribute__((packed))
#define STORE_ATTR          __attribute__((aligned(4)))

#define SHMEM_ATTR
#define ICACHE_FLASH_ATTR

#define DMEM_ATTR           __attribute__((section(".bss")))
#define IRAM_ATTR           __attribute__((section(".text")))
#define ICACHE_RODATA_ATTR  __attribute__((section(".irom.text")))

So, I guess that for stuff that I really need in IRAM (interrupt routines and Flash FS), should be marked with the IRAM_ATTR macro, and data that is totally constant could be marked with ICACHE_RODATA_ATTR.

Is there anyone that can confirm this?

Cheers
Niclas

Statistics: Posted by NiclasH — Thu May 26, 2016 6:22 pm

Re: Meaning of ICACHE_FLASH_ATTR

2016-04-25T03:31:59+08:00

eriksl wrote:
Very good questions, this has been all mysterious.

But I can answer your last question: simply put ALL your code in flash (apart maybe from a few a very small functions that handle interrupts). The libs from the SDK already take up most of the IRAM so you will run out of it very quickly.

If we program using Arduino IDE, do we have control over where we can put our code, if we want?

Statistics: Posted by electronicsguy — Mon Apr 25, 2016 3:31 am

Re: Meaning of ICACHE_FLASH_ATTR

2016-02-09T16:33:59+08:00

Very good questions, this has been all mysterious.

But I can answer your last question: simply put ALL your code in flash (apart maybe from a few a very small functions that handle interrupts). The libs from the SDK already take up most of the IRAM so you will run out of it very quickly.

Statistics: Posted by eriksl — Tue Feb 09, 2016 4:33 pm

Re: Meaning of ICACHE_FLASH_ATTR

2016-02-09T11:28:39+08:00

Does the ESP8266 CPU have an instruction cache on it, or are instructions directly fetched from the external flash memory whenever they are executed?

If there is a cache, how big is it?

I'm trying to figure out how the performance of the internal instruction ram and external flash differ -- so I can allocate code correctly.

Thanks

Statistics: Posted by philip — Tue Feb 09, 2016 11:28 am

Re: Meaning of ICACHE_FLASH_ATTR

2015-12-11T03:22:55+08:00

code with ICACHE_FLASH_ATTR will end up in irom (flash) only.
code without ICACHE_FLASH_ATTR will end up in irom (flash) and will be copied to iram (ram) on bootup.

The iram space is quite limited, including space needed by SDK and other libraries you will only have a few kbytes for your own application. So add the phrase to every function you declare.

Statistics: Posted by eriksl — Fri Dec 11, 2015 3:22 am

Re: Meaning of ICACHE_FLASH_ATTR

2015-12-10T21:49:46+08:00

Hi,

1. With ICACHE_FLASH_ATTR progam is located in FLASH, and if necessary read directly from FLASH, or before use sent to a cache? and than used ?
2. Without ICACHE_FLASH_ATTR program is loaded into IRAM at start, and if there is no place for all ?
The rest is located in Flash is run directly from FLASH or with cache ?

Best Regards
Mariusz

Statistics: Posted by mariuszb — Thu Dec 10, 2015 9:49 pm

Re: Meaning of ICACHE_FLASH_ATTR

2015-10-03T15:00:00+08:00

I don't know. I did place complete libraries (from the SDK and libc, one by one) in IROM and at certain points it just crashed. So I am not going there anymore. I must say that Espressif has been doing good work lately with moving more functions in their SDK to IROM. Now the biggest user of IRAM is libc.

Statistics: Posted by eriksl — Sat Oct 03, 2015 3:00 pm

Re: Meaning of ICACHE_FLASH_ATTR

2015-10-03T05:54:11+08:00

eriksl wrote:
You never know what IRAM-bound functions (including in the SDK!) call these functions and cause unexpected crashes. I've been there.

What were the circumstances? What ISR and what function(s)?

Statistics: Posted by dkinzer — Sat Oct 03, 2015 5:54 am

Re: Meaning of ICACHE_FLASH_ATTR

2015-10-02T23:19:43+08:00

This is a dangerous technique. You never know what IRAM-bound functions (including in the SDK!) call these functions and cause unexpected crashes. I've been there... If you want sqrt in your program, the best option imho still is to write/copy your version and include it in your program, in IROM.

Statistics: Posted by eriksl — Fri Oct 02, 2015 11:19 pm

Re: Meaning of ICACHE_FLASH_ATTR

2015-10-02T22:41:43+08:00

eriksl wrote:
Neil, that's also a good method. Doesn't work for me though, because I always have a few functions that need to be in IRAM.

For those few functions that need to be in IRAM (e.g. interrupt service handlers), use a different attribute that puts them in the .iram0 section.

Code:

#define IRAM0     __attribute__((section(".iram0.text")))
void IRAM0 myISR(void)
{
}

Since this function will be in .iram0.text it won't be among those whose section name is modified by

Code:

objcopy --rename-section .text=.irom0.text --rename-section .literal=.irom0.literal myObjectFile.o

It should also be noted how the SDK include files define ICACHE_FLASH_ATTR (in c_types.h):

Code:

#ifdef ICACHE_FLASH
#define ICACHE_FLASH_ATTR __attribute__((section(".irom0.text")))
#define ICACHE_RODATA_ATTR __attribute__((section(".irom.text")))
#else
#define ICACHE_FLASH_ATTR
#define ICACHE_RODATA_ATTR
#endif /* ICACHE_FLASH */

This means that even if you adorn your functions with ICACHE_FLASH_ATTR, they will still not be in .irom0.text unless ICACHE_FLASH is defined when the files are compiled. This is usually accomplished by using -DICACHE_FLASH on the compiler command line.

Another useful technique can be found in the ESP8266-Arduino linker script. The excerpt below comes from esp8266/Arduino on GitHub:

Code:

  .irom0.text : ALIGN(4)
  {
    _irom0_text_start = ABSOLUTE(.);
    *core_esp8266_*.o(.literal*, .text*)
    *spiffs*.o(.literal*, .text*)
    *.cpp.o(.literal*, .text*)
    *libm.a:(.literal .text .literal.* .text.*)
    *libsmartconfig.a:(.literal .text .literal.* .text.*)
    *(.irom0.literal .irom.literal .irom.text.literal .irom0.text .irom.text)
    _irom0_text_end = ABSOLUTE(.);
    _flash_code_end = ABSOLUTE(.);
  } >irom0_0_seg :irom0_0_phdr

Note, particularly, the fourth and seventh lines. The fourth line causes all of the core esp8266/Arduino code .literal and .text sections to be put in .irom0.text. This accomplishes exactly the same purpose as does using objcopy to rename the sections. (The fifth line does the same for SPIFFS code.) The seventh line causes all .literal and .text sections in the libm.a to be put in .irom0.text. This works around a problem where using sqrt() in an application would cause the cache RAM size to be exceeded.

Statistics: Posted by dkinzer — Fri Oct 02, 2015 10:41 pm

Re: Meaning of ICACHE_FLASH_ATTR

2015-10-02T20:54:41+08:00

Neil, that's also a good method. Doesn't work for me though, because I always have a few functions that need to be in IRAM.

This is what I did: forget about the whole ICACHE_FLASH_ATTR thing and #define my own, similar replacement, with the simple name "irom" which exactly describes what it does and also is so much easier to type.

The other way around, default everything in IROM and only exceptions in IRAM would be even better, but I appreciate that that is not possible because then you would need to scan ALL library sources (including libc) for functions that possibly might need to end up in IRAM. This decision is non-trivial, it depends on what code calls the function.

Statistics: Posted by eriksl — Fri Oct 02, 2015 8:54 pm

Re: Meaning of ICACHE_FLASH_ATTR

2015-10-02T20:40:58+08:00

That's a great response and very helpful, thanks eriksl.

Statistics: Posted by geo.espressif — Fri Oct 02, 2015 8:40 pm

Re: Meaning of ICACHE_FLASH_ATTR

2015-10-02T20:38:13+08:00

@eriksl ... I think you have posted a VITAL report here. This should be a blog post somewhere as opposed to a forum post that might get lost

One technique I have seen used is to not include the ICACHE_FLASH_ATTR modification of each of the source functions ... but instead, when the compilation of a .c to a .o has completed, rename the .text section to be .irom0.text

For example ...:

objcopy --rename-section .text=.irom0.text --rename-section .literal=.irom0.literal myObjectFile.o

Do you have any thoughts on the wisdom of that notion?

Neil

Statistics: Posted by kolban — Fri Oct 02, 2015 8:38 pm

Re: Meaning of ICACHE_FLASH_ATTR

2015-10-02T17:55:58+08:00

It has been explained here and there, but never explicitly, so I'll take the shot on doing it simple & good (one time).

The esp8266 has 32k (maybe 64k, that's not completely clear) of IRAM. That means RAM for instructions, code. This is different from the ~80k of DRAM (which means data ram, not dynamic ram, it's all dynamic ram, the iram too). One cannot be use for the other and v.v.

Programs are stored in the flash memory and due to the fast interface (SPI-quad) instructions can be fetched and executed "in place", in other words, without copying them to ram first. In some occasions you cannot execute your code from SPI flash memory directly, mostly because it needs to be maximum fast or because it handles the flash memory itself (e.g. writing to it). In that case, you can have some code, 32k in total, have copied from the flash at startup, to the IRAM. This code will run from IRAM, not from FLASH.

The forementioned #define, which has an ugly, completely wrong name, if applied to a function, takes care that the function is output to the .irom0_text section, which tells the linker to put the function in FLASH memory segment. The default is to output to .text segment which will put the function into the IRAM segment.

A lot of the SDK-code, which you must link to your firmware to have it working, also output their code to the IRAM segment. So there is actually not a lot left, from the 32k for your own application, about 2k, maybe 3k. So use it very sparingly. Also many functions if not all, from libc, are placed into the IRAM segment. So it is very easy to run out of IRAM space. Even though you may have 512k or even 4m of FLASH memory (depening on the chip used). I had to reimplement some functions from libc in my own code, simply because they take up too much space in IRAM.

So always, unless impossible, add this #define to all of your functions.

I think that should cover most of it.

Statistics: Posted by eriksl — Fri Oct 02, 2015 5:55 pm

Re: Meaning of ICACHE_FLASH_ATTR

2015-10-02T17:41:39+08:00

That's disappointing, never mind.

Any rough ideas? I have no idea and I've been using it roughly at random. Something to do with the memory the function is compiled to / speed of calling?

Statistics: Posted by geo.espressif — Fri Oct 02, 2015 5:41 pm

Re: Meaning of ICACHE_FLASH_ATTR

2015-10-02T17:32:17+08:00

You are completely right. It's a shame this #define is never explained, as is the whole concept behind it, which the community how has had to guess. For one it's still not 100% sure if the esp does any instruction caching and if the upper 32k iram (if it even exists) is used for that. I am not talking about the execution of code in iram (lower 32k iram), which the above macro refers to.

Statistics: Posted by eriksl — Fri Oct 02, 2015 5:32 pm

Meaning of ICACHE_FLASH_ATTR

2015-10-02T16:55:14+08:00

Could someone point me in the direction of where 'ICACHE_FLASH_ATTR' is described in the documentation please? I can't find it in either the SDK or HDK user guides.

Statistics: Posted by geo.espressif — Fri Oct 02, 2015 4:55 pm