1<html lang="en"> 2<head> 3<title>Named Address Spaces - Using the GNU Compiler Collection (GCC)</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Using the GNU Compiler Collection (GCC)"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="C-Extensions.html#C-Extensions" title="C Extensions"> 9<link rel="prev" href="Fixed_002dPoint.html#Fixed_002dPoint" title="Fixed-Point"> 10<link rel="next" href="Zero-Length.html#Zero-Length" title="Zero Length"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988-2013 Free Software Foundation, Inc. 14 15Permission is granted to copy, distribute and/or modify this document 16under the terms of the GNU Free Documentation License, Version 1.3 or 17any later version published by the Free Software Foundation; with the 18Invariant Sections being ``Funding Free Software'', the Front-Cover 19Texts being (a) (see below), and with the Back-Cover Texts being (b) 20(see below). A copy of the license is included in the section entitled 21``GNU Free Documentation License''. 22 23(a) The FSF's Front-Cover Text is: 24 25 A GNU Manual 26 27(b) The FSF's Back-Cover Text is: 28 29 You have freedom to copy and modify this GNU Manual, like GNU 30 software. Copies published by the Free Software Foundation raise 31 funds for GNU development.--> 32<meta http-equiv="Content-Style-Type" content="text/css"> 33<style type="text/css"><!-- 34 pre.display { font-family:inherit } 35 pre.format { font-family:inherit } 36 pre.smalldisplay { font-family:inherit; font-size:smaller } 37 pre.smallformat { font-family:inherit; font-size:smaller } 38 pre.smallexample { font-size:smaller } 39 pre.smalllisp { font-size:smaller } 40 span.sc { font-variant:small-caps } 41 span.roman { font-family:serif; font-weight:normal; } 42 span.sansserif { font-family:sans-serif; font-weight:normal; } 43--></style> 44<link rel="stylesheet" type="text/css" href="../cs.css"> 45</head> 46<body> 47<div class="node"> 48<a name="Named-Address-Spaces"></a> 49<p> 50Next: <a rel="next" accesskey="n" href="Zero-Length.html#Zero-Length">Zero Length</a>, 51Previous: <a rel="previous" accesskey="p" href="Fixed_002dPoint.html#Fixed_002dPoint">Fixed-Point</a>, 52Up: <a rel="up" accesskey="u" href="C-Extensions.html#C-Extensions">C Extensions</a> 53<hr> 54</div> 55 56<h3 class="section">6.16 Named Address Spaces</h3> 57 58<p><a name="index-Named-Address-Spaces-2521"></a> 59As an extension, GNU C supports named address spaces as 60defined in the N1275 draft of ISO/IEC DTR 18037. Support for named 61address spaces in GCC will evolve as the draft technical report 62changes. Calling conventions for any target might also change. At 63present, only the AVR, SPU, M32C, and RL78 targets support address 64spaces other than the generic address space. 65 66 <p>Address space identifiers may be used exactly like any other C type 67qualifier (e.g., <code>const</code> or <code>volatile</code>). See the N1275 68document for more details. 69 70 <p><a name="AVR-Named-Address-Spaces"></a> 71 72<h4 class="subsection">6.16.1 AVR Named Address Spaces</h4> 73 74<p>On the AVR target, there are several address spaces that can be used 75in order to put read-only data into the flash memory and access that 76data by means of the special instructions <code>LPM</code> or <code>ELPM</code> 77needed to read from flash. 78 79 <p>Per default, any data including read-only data is located in RAM 80(the generic address space) so that non-generic address spaces are 81needed to locate read-only data in flash memory 82<em>and</em> to generate the right instructions to access this data 83without using (inline) assembler code. 84 85 <dl> 86<dt><code>__flash</code><dd><a name="index-g_t_0040code_007b_005f_005fflash_007d-AVR-Named-Address-Spaces-2522"></a>The <code>__flash</code> qualifier locates data in the 87<code>.progmem.data</code> section. Data is read using the <code>LPM</code> 88instruction. Pointers to this address space are 16 bits wide. 89 90 <br><dt><code>__flash1</code><dt><code>__flash2</code><dt><code>__flash3</code><dt><code>__flash4</code><dt><code>__flash5</code><dd><a name="index-g_t_0040code_007b_005f_005fflash1_007d-AVR-Named-Address-Spaces-2523"></a><a name="index-g_t_0040code_007b_005f_005fflash2_007d-AVR-Named-Address-Spaces-2524"></a><a name="index-g_t_0040code_007b_005f_005fflash3_007d-AVR-Named-Address-Spaces-2525"></a><a name="index-g_t_0040code_007b_005f_005fflash4_007d-AVR-Named-Address-Spaces-2526"></a><a name="index-g_t_0040code_007b_005f_005fflash5_007d-AVR-Named-Address-Spaces-2527"></a>These are 16-bit address spaces locating data in section 91<code>.progmem</code><var>N</var><code>.data</code> where <var>N</var> refers to 92address space <code>__flash</code><var>N</var>. 93The compiler sets the <code>RAMPZ</code> segment register appropriately 94before reading data by means of the <code>ELPM</code> instruction. 95 96 <br><dt><code>__memx</code><dd><a name="index-g_t_0040code_007b_005f_005fmemx_007d-AVR-Named-Address-Spaces-2528"></a>This is a 24-bit address space that linearizes flash and RAM: 97If the high bit of the address is set, data is read from 98RAM using the lower two bytes as RAM address. 99If the high bit of the address is clear, data is read from flash 100with <code>RAMPZ</code> set according to the high byte of the address. 101See <a href="AVR-Built_002din-Functions.html#AVR-Built_002din-Functions"><code>__builtin_avr_flash_segment</code></a>. 102 103 <p>Objects in this address space are located in <code>.progmemx.data</code>. 104</dl> 105 106 <p><b>Example</b> 107 108<pre class="smallexample"> char my_read (const __flash char ** p) 109 { 110 /* p is a pointer to RAM that points to a pointer to flash. 111 The first indirection of p reads that flash pointer 112 from RAM and the second indirection reads a char from this 113 flash address. */ 114 115 return **p; 116 } 117 118 /* Locate array[] in flash memory */ 119 const __flash int array[] = { 3, 5, 7, 11, 13, 17, 19 }; 120 121 int i = 1; 122 123 int main (void) 124 { 125 /* Return 17 by reading from flash memory */ 126 return array[array[i]]; 127 } 128</pre> 129 <p class="noindent">For each named address space supported by avr-gcc there is an equally 130named but uppercase built-in macro defined. 131The purpose is to facilitate testing if respective address space 132support is available or not: 133 134<pre class="smallexample"> #ifdef __FLASH 135 const __flash int var = 1; 136 137 int read_var (void) 138 { 139 return var; 140 } 141 #else 142 #include <avr/pgmspace.h> /* From AVR-LibC */ 143 144 const int var PROGMEM = 1; 145 146 int read_var (void) 147 { 148 return (int) pgm_read_word (&var); 149 } 150 #endif /* __FLASH */ 151</pre> 152 <p class="noindent">Notice that attribute <a href="AVR-Variable-Attributes.html#AVR-Variable-Attributes"><code>progmem</code></a> 153locates data in flash but 154accesses to these data read from generic address space, i.e. 155from RAM, 156so that you need special accessors like <code>pgm_read_byte</code> 157from <a href="http://nongnu.org/avr-libc/user-manual/">AVR-LibC</a><!-- /@w --> 158together with attribute <code>progmem</code>. 159 160<p class="noindent"><b>Limitations and caveats</b> 161 162 <ul> 163<li>Reading across the 64 KiB section boundary of 164the <code>__flash</code> or <code>__flash</code><var>N</var> address spaces 165shows undefined behavior. The only address space that 166supports reading across the 64 KiB flash segment boundaries is 167<code>__memx</code>. 168 169 <li>If you use one of the <code>__flash</code><var>N</var> address spaces 170you must arrange your linker script to locate the 171<code>.progmem</code><var>N</var><code>.data</code> sections according to your needs. 172 173 <li>Any data or pointers to the non-generic address spaces must 174be qualified as <code>const</code>, i.e. as read-only data. 175This still applies if the data in one of these address 176spaces like software version number or calibration lookup table are intended to 177be changed after load time by, say, a boot loader. In this case 178the right qualification is <code>const</code> <code>volatile</code> so that the compiler 179must not optimize away known values or insert them 180as immediates into operands of instructions. 181 182 <li>The following code initializes a variable <code>pfoo</code> 183located in static storage with a 24-bit address: 184 <pre class="smallexample"> extern const __memx char foo; 185 const __memx void *pfoo = &foo; 186</pre> 187 <p class="noindent">Such code requires at least binutils 2.23, see 188<a href="http://sourceware.org/PR13503">PR13503</a><!-- /@w -->. 189 190 </ul> 191 192<h4 class="subsection">6.16.2 M32C Named Address Spaces</h4> 193 194<p><a name="index-g_t_0040code_007b_005f_005ffar_007d-M32C-Named-Address-Spaces-2529"></a> 195On the M32C target, with the R8C and M16C CPU variants, variables 196qualified with <code>__far</code> are accessed using 32-bit addresses in 197order to access memory beyond the first 64 Ki bytes. If 198<code>__far</code> is used with the M32CM or M32C CPU variants, it has no 199effect. 200 201<h4 class="subsection">6.16.3 RL78 Named Address Spaces</h4> 202 203<p><a name="index-g_t_0040code_007b_005f_005ffar_007d-RL78-Named-Address-Spaces-2530"></a> 204On the RL78 target, variables qualified with <code>__far</code> are accessed 205with 32-bit pointers (20-bit addresses) rather than the default 16-bit 206addresses. Non-far variables are assumed to appear in the topmost 20764 KiB of the address space. 208 209<h4 class="subsection">6.16.4 SPU Named Address Spaces</h4> 210 211<p><a name="index-g_t_0040code_007b_005f_005fea_007d-SPU-Named-Address-Spaces-2531"></a> 212On the SPU target variables may be declared as 213belonging to another address space by qualifying the type with the 214<code>__ea</code> address space identifier: 215 216<pre class="smallexample"> extern int __ea i; 217</pre> 218 <p class="noindent">The compiler generates special code to access the variable <code>i</code>. 219It may use runtime library 220support, or generate special machine instructions to access that address 221space. 222 223 </body></html> 224 225