AVR-LibC  2.2.1
Standard C library for AVR-GCC
 

AVR-LibC Documentation

Logo

AVR-LibC Development Pages

Main Page

User Manual

Library Reference

FAQ

Example Projects

File List

Loading...
Searching...
No Matches
pgmspace.h
Go to the documentation of this file.
1/* Copyright (c) 2002-2007 Marek Michalkiewicz
2 Copyright (c) 2006, Carlos Lamas
3 Copyright (c) 2009-2010, Jan Waclawek
4 All rights reserved.
5
6 Redistribution and use in source and binary forms, with or without
7 modification, are permitted provided that the following conditions are met:
8
9 * Redistributions of source code must retain the above copyright
10 notice, this list of conditions and the following disclaimer.
11 * Redistributions in binary form must reproduce the above copyright
12 notice, this list of conditions and the following disclaimer in
13 the documentation and/or other materials provided with the
14 distribution.
15 * Neither the name of the copyright holders nor the names of
16 contributors may be used to endorse or promote products derived
17 from this software without specific prior written permission.
18
19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
23 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29 POSSIBILITY OF SUCH DAMAGE. */
30
31/* $Id$ */
32
33/*
34 pgmspace.h
35
36 Contributors:
37 Created by Marek Michalkiewicz <marekm@linux.org.pl>
38 Eric B. Weddington <eric@ecentral.com>
39 Wolfgang Haidinger <wh@vmars.tuwien.ac.at> (pgm_read_dword())
40 Ivanov Anton <anton@arc.com.ru> (pgm_read_float())
41 */
42
43/** \file */
44/** \defgroup avr_pgmspace <avr/pgmspace.h>: Program Space Utilities
45 \code
46 #include <avr/io.h>
47 #include <avr/pgmspace.h>
48 \endcode
49
50 The functions in this module provide interfaces for a program to access
51 data stored in program space (flash memory) of the device.
52
53 \note These functions are an attempt to provide some compatibility with
54 header files that come with IAR C, to make porting applications between
55 different compilers easier. This is not 100% compatibility though (GCC
56 does not have full support for multiple address spaces yet).
57
58 \note If you are working with strings which are completely based in RAM,
59 use the standard string functions described in \ref avr_string.
60
61 \note If possible, put your constant tables in the lower 64 KB and use
62 pgm_read_byte_near() or pgm_read_word_near() instead of
63 pgm_read_byte_far() or pgm_read_word_far() since it is more efficient that
64 way, and you can still use the upper 64K for executable code.
65 All functions that are suffixed with a \c _P \e require their
66 arguments to be in the lower 64 KB of the flash ROM, as they do
67 not use ELPM instructions. This is normally not a big concern as
68 the linker setup arranges any program space constants declared
69 using the macros from this header file so they are placed right after
70 the interrupt vectors, and in front of any executable code. However,
71 it can become a problem if there are too many of these constants, or
72 for bootloaders on devices with more than 64 KB of ROM.
73 <em>All these functions will not work in that situation.</em>
74
75 \note For <b>Xmega</b> devices, make sure the NVM controller
76 command register (\c NVM.CMD or \c NVM_CMD) is set to 0x00 (NOP)
77 before using any of these functions.
78*/
79
80#ifndef __PGMSPACE_H_
81#define __PGMSPACE_H_ 1
82
83#ifndef __DOXYGEN__
84#define __need_size_t
85#endif
86#include <inttypes.h>
87#include <stddef.h>
88#include <avr/io.h>
89
90#ifndef __DOXYGEN__
91#ifndef __ATTR_CONST__
92#define __ATTR_CONST__ __attribute__((__const__))
93#endif
94
95#ifndef __ATTR_PROGMEM__
96#define __ATTR_PROGMEM__ __attribute__((__progmem__))
97#endif
98
99#ifndef __ATTR_PURE__
100#define __ATTR_PURE__ __attribute__((__pure__))
101#endif
102
103#ifndef __ATTR_ALWAYS_INLINE__
104#define __ATTR_ALWAYS_INLINE__ __inline__ __attribute__((__always_inline__))
105#endif
106
107#define PROGMEM __ATTR_PROGMEM__
108
109#endif /* !__DOXYGEN__ */
110
111/**
112 \ingroup avr_pgmspace
113 \def PROGMEM_FAR
114
115 Attribute to use in order to declare an object being located in
116 far flash ROM. This is similar to #PROGMEM, except that it puts
117 the static storage object in section
118 <tt>\ref sec_dot_progmemx ".progmemx.data"</tt>.
119 In order to access the object,
120 the <tt>pgm_read_*_far</tt> and \c _PF functions declare in this header
121 can be used. In order to get its address, see pgm_get_far_address().
122
123 It only makes sense to put read-only objects in this section,
124 though the compiler does not diagnose when this is not the case. */
125#define PROGMEM_FAR __attribute__((__section__(".progmemx.data")))
126
127#ifdef __DOXYGEN__
128
129/**
130 \ingroup avr_pgmspace
131 \def PROGMEM
132
133 Attribute to use in order to declare an object being located in
134 flash ROM. */
135#define PROGMEM __attribute__((__progmem__))
136
137/** \ingroup avr_pgmspace
138 \fn char pgm_read_char (const char *__addr)
139 Read a <tt>char</tt> from 16-bit (near) byte-address \p __addr.
140 The address is in the lower 64 KiB of program memory. */
141static inline char pgm_read_char (const char *__addr);
142
143/** \ingroup avr_pgmspace
144 \fn unsigned char pgm_read_unsigned_char (const unsigned char *__addr)
145 Read an <tt>unsigned char</tt> from 16-bit (near) byte-address \p __addr.
146 The address is in the lower 64 KiB of program memory. */
147static inline unsigned char pgm_read_unsigned_char (const unsigned char *__addr);
148
149/** \ingroup avr_pgmspace
150 \fn signed char pgm_read_signed_char (const signed char *__addr)
151 Read a <tt>signed char</tt> from 16-bit (near) byte-address \p __addr.
152 The address is in the lower 64 KiB of program memory. */
153static inline signed char pgm_read_signed_char (const signed char *__addr);
154
155/** \ingroup avr_pgmspace
156 \fn uint8_t pgm_read_u8 (const uint8_t *__addr)
157 Read an <tt>uint8_t</tt> from 16-bit (near) byte-address \p __addr.
158 The address is in the lower 64 KiB of program memory. */
159static inline uint8_t pgm_read_u8 (const uint8_t *__addr);
160
161/** \ingroup avr_pgmspace
162 \fn int8_t pgm_read_i8 (const int8_t *__addr)
163 Read an <tt>int8_t</tt> from 16-bit (near) byte-address \p __addr.
164 The address is in the lower 64 KiB of program memory. */
165static inline int8_t pgm_read_i8 (const int8_t *__addr);
166
167/** \ingroup avr_pgmspace
168 \fn short pgm_read_short (const short *__addr)
169 Read a <tt>short</tt> from 16-bit (near) byte-address \p __addr.
170 The address is in the lower 64 KiB of program memory. */
171static inline short pgm_read_short (const short *__addr);
172
173/** \ingroup avr_pgmspace
174 \fn unsigned short pgm_read_unsigned_short (const unsigned short *__addr)
175 Read an <tt>unsigned short</tt> from 16-bit (near) byte-address \p __addr.
176 The address is in the lower 64 KiB of program memory. */
177static inline unsigned short pgm_read_unsigned_short (const unsigned short *__addr);
178
179/** \ingroup avr_pgmspace
180 \fn uint16_t pgm_read_u16 (const uint16_t *__addr)
181 Read an <tt>uint16_t</tt> from 16-bit (near) byte-address \p __addr.
182 The address is in the lower 64 KiB of program memory. */
183static inline uint16_t pgm_read_u16 (const uint16_t *__addr);
184
185/** \ingroup avr_pgmspace
186 \fn int16_t pgm_read_i16 (const int16_t *__addr)
187 Read an <tt>int16_t</tt> from 16-bit (near) byte-address \p __addr.
188 The address is in the lower 64 KiB of program memory. */
189static inline int16_t pgm_read_i16 (const int16_t *__addr);
190
191/** \ingroup avr_pgmspace
192 \fn int pgm_read_int (const int *__addr)
193 Read an <tt>int</tt> from 16-bit (near) byte-address \p __addr.
194 The address is in the lower 64 KiB of program memory. */
195static inline int pgm_read_int (const int *__addr);
196
197/** \ingroup avr_pgmspace
198 \fn signed pgm_read_signed (const signed *__addr)
199 Read a <tt>signed</tt> from 16-bit (near) byte-address \p __addr.
200 The address is in the lower 64 KiB of program memory. */
201static inline signed pgm_read_signed (const signed *__addr);
202
203/** \ingroup avr_pgmspace
204 \fn unsigned pgm_read_unsigned (const unsigned *__addr)
205 Read an <tt>unsigned</tt> from 16-bit (near) byte-address \p __addr.
206 The address is in the lower 64 KiB of program memory. */
207static inline unsigned pgm_read_unsigned (const unsigned *__addr);
208
209/** \ingroup avr_pgmspace
210 \fn signed int pgm_read_signed_int (const signed int *__addr)
211 Read a <tt>signed int</tt> from 16-bit (near) byte-address \p __addr.
212 The address is in the lower 64 KiB of program memory. */
213static inline signed int pgm_read_signed_int (const signed int *__addr);
214
215/** \ingroup avr_pgmspace
216 \fn unsigned int pgm_read_unsigned_int (const unsigned int *__addr)
217 Read an <tt>unsigned int</tt> from 16-bit (near) byte-address \p __addr.
218 The address is in the lower 64 KiB of program memory. */
219static inline unsigned int pgm_read_unsigned_int (const unsigned int *__addr);
220
221/** \ingroup avr_pgmspace
222 \fn __int24 pgm_read_i24 (const __int24 *__addr)
223 Read an <tt>__int24</tt> from 16-bit (near) byte-address \p __addr.
224 The address is in the lower 64 KiB of program memory. */
225static inline __int24 pgm_read_i24 (const __int24 *__addr);
226
227/** \ingroup avr_pgmspace
228 \fn __uint24 pgm_read_u24 (const __uint24 *__addr)
229 Read an <tt>__uint24</tt> from 16-bit (near) byte-address \p __addr.
230 The address is in the lower 64 KiB of program memory. */
231static inline __uint24 pgm_read_u24 (const __uint24 *__addr);
232
233/** \ingroup avr_pgmspace
234 \fn uint32_t pgm_read_u32 (const uint32_t *__addr)
235 Read an <tt>uint32_t</tt> from 16-bit (near) byte-address \p __addr.
236 The address is in the lower 64 KiB of program memory. */
237static inline uint32_t pgm_read_u32 (const uint32_t *__addr);
238
239/** \ingroup avr_pgmspace
240 \fn int32_t pgm_read_i32 (const int32_t *__addr)
241 Read an <tt>int32_t</tt> from 16-bit (near) byte-address \p __addr.
242 The address is in the lower 64 KiB of program memory. */
243static inline int32_t pgm_read_i32 (const int32_t *__addr);
244
245/** \ingroup avr_pgmspace
246 \fn long pgm_read_long (const long *__addr)
247 Read a <tt>long</tt> from 16-bit (near) byte-address \p __addr.
248 The address is in the lower 64 KiB of program memory. */
249static inline long pgm_read_long (const long *__addr);
250
251/** \ingroup avr_pgmspace
252 \fn unsigned long pgm_read_unsigned_long (const unsigned long *__addr)
253 Read an <tt>unsigned long</tt> from 16-bit (near) byte-address \p __addr.
254 The address is in the lower 64 KiB of program memory. */
255static inline unsigned long pgm_read_unsigned_long (const unsigned long *__addr);
256
257/** \ingroup avr_pgmspace
258 \fn long long pgm_read_long_long (const long long *__addr)
259 Read a <tt>long long</tt> from 16-bit (near) byte-address \p __addr.
260 The address is in the lower 64 KiB of program memory. */
261static inline long long pgm_read_long_long (const long long *__addr);
262
263/** \ingroup avr_pgmspace
264 \fn unsigned long long pgm_read_unsigned_long_long (const unsigned long long *__addr)
265 Read an <tt>unsigned long long</tt> from 16-bit (near) byte-address
266 \p __addr.
267 The address is in the lower 64 KiB of program memory. */
268static inline unsigned long long pgm_read_unsigned_long_long (const unsigned long long *__addr);
269
270/** \ingroup avr_pgmspace
271 \fn uint64_t pgm_read_u64 (const uint64_t *__addr)
272 Read an <tt>uint64_t</tt> from 16-bit (near) byte-address \p __addr.
273 The address is in the lower 64 KiB of program memory. */
274static inline uint64_t pgm_read_u64 (const uint64_t *__addr);
275
276/** \ingroup avr_pgmspace
277 \fn int64_t pgm_read_i64 (const int64_t *__addr)
278 Read an <tt>int64_t</tt> from 16-bit (near) byte-address \p __addr.
279 The address is in the lower 64 KiB of program memory. */
280static inline int64_t pgm_read_i64 (const int64_t *__addr);
281
282/** \ingroup avr_pgmspace
283 \fn float pgm_read_float (const float *__addr)
284 Read a <tt>float</tt> from 16-bit (near) byte-address \p __addr.
285 The address is in the lower 64 KiB of program memory. */
286static inline float pgm_read_float (const float *__addr);
287
288/** \ingroup avr_pgmspace
289 \fn double pgm_read_double (const double *__addr)
290 Read a <tt>double</tt> from 16-bit (near) byte-address \p __addr.
291 The address is in the lower 64 KiB of program memory. */
292static inline double pgm_read_double (const double *__addr);
293
294/** \ingroup avr_pgmspace
295 \fn long double pgm_read_long_double (const long double *__addr)
296 Read a <tt>long double</tt> from 16-bit (near) byte-address \p __addr.
297 The address is in the lower 64 KiB of program memory. */
298static inline long double pgm_read_long_double (const long double *__addr);
299
300#else /* !DOXYGEN */
301#if defined(__AVR_TINY__)
302/* For Reduced Tiny devices, avr-gcc adds 0x4000 when it takes the address
303 of a PROGMEM object. This means we can use open coded C/C++ to read
304 from progmem. This assumes we have
305 - GCC PR71948 - Make progmem work on Reduced Tiny (GCC v7 / 2016-08) */
306#define __LPM__1(res, addr) res = *addr
307#define __LPM__2(res, addr) res = *addr
308#define __LPM__3(res, addr) res = *addr
309#define __LPM__4(res, addr) res = *addr
310#define __LPM__8(res, addr) res = *addr
311
312#elif defined(__AVR_HAVE_LPMX__)
313#define __LPM__1(res, addr) \
314 __asm __volatile__ ("lpm %0,%a1" \
315 : "=r" (res) : "z" (addr))
316
317#define __LPM__2(res, addr) \
318 __asm __volatile__ ("lpm %A0,%a1+" "\n\t" \
319 "lpm %B0,%a1+" \
320 : "=r" (res), "+z" (addr))
321
322#define __LPM__3(res, addr) \
323 __asm __volatile__ ("lpm %A0,%a1+" "\n\t" \
324 "lpm %B0,%a1+" "\n\t" \
325 "lpm %C0,%a1+" \
326 : "=r" (res), "+z" (addr))
327
328#define __LPM__4(res, addr) \
329 __asm __volatile__ ("lpm %A0,%a1+" "\n\t" \
330 "lpm %B0,%a1+" "\n\t" \
331 "lpm %C0,%a1+" "\n\t" \
332 "lpm %D0,%a1+" \
333 : "=r" (res), "+z" (addr))
334
335#define __LPM__8(res, addr) \
336 __asm __volatile__ ("lpm %r0+0,%a1+" "\n\t" \
337 "lpm %r0+1,%a1+" "\n\t" \
338 "lpm %r0+2,%a1+" "\n\t" \
339 "lpm %r0+3,%a1+" "\n\t" \
340 "lpm %r0+4,%a1+" "\n\t" \
341 "lpm %r0+5,%a1+" "\n\t" \
342 "lpm %r0+6,%a1+" "\n\t" \
343 "lpm %r0+7,%a1+" \
344 : "=r" (res), "+z" (addr))
345#else /* Has no LPMx and no Reduced Tiny => Has LPM. */
346#define __LPM__1(res, addr) \
347 __asm __volatile__ ("lpm $ mov %A0,r0" \
348 : "=r" (res) : "z" (addr) : "r0")
349
350#define __LPM__2(res, addr) \
351 __asm __volatile__ ("lpm $ mov %A0,r0 $ adiw %1,1" "\n\t" \
352 "lpm $ mov %B0,r0" \
353 : "=r" (res), "+z" (addr) :: "r0")
354
355#define __LPM__3(res, addr) \
356 __asm __volatile__ ("lpm $ mov %A0,r0 $ adiw %1,1" "\n\t" \
357 "lpm $ mov %B0,r0 $ adiw %1,1" "\n\t" \
358 "lpm $ mov %C0,r0" \
359 : "=r" (res), "+z" (addr) :: "r0")
360
361#define __LPM__4(res, addr) \
362 __asm __volatile__ ("lpm $ mov %A0,r0 $ adiw %1,1" "\n\t" \
363 "lpm $ mov %B0,r0 $ adiw %1,1" "\n\t" \
364 "lpm $ mov %C0,r0 $ adiw %1,1" "\n\t" \
365 "lpm $ mov %D0,r0" \
366 : "=r" (res), "+z" (addr) :: "r0")
367
368#define __LPM__8(res, addr) \
369 __asm __volatile__ ("lpm $ mov %r0+0,r0 $ adiw %1,1" "\n\t" \
370 "lpm $ mov %r0+1,r0 $ adiw %1,1" "\n\t" \
371 "lpm $ mov %r0+2,r0 $ adiw %1,1" "\n\t" \
372 "lpm $ mov %r0+3,r0 $ adiw %1,1" "\n\t" \
373 "lpm $ mov %r0+4,r0 $ adiw %1,1" "\n\t" \
374 "lpm $ mov %r0+5,r0 $ adiw %1,1" "\n\t" \
375 "lpm $ mov %r0+6,r0 $ adiw %1,1" "\n\t" \
376 "lpm $ mov %r0+7,r0" \
377 : "=r" (res), "+z" (addr) :: "r0")
378#endif /* LPM cases */
379
380#define _Avrlibc_Def_Pgm_1(Name, Typ) \
381 static __ATTR_ALWAYS_INLINE__ \
382 Typ pgm_read_##Name (const Typ *__addr) \
383 { \
384 Typ __res; \
385 __LPM__1 (__res, __addr); \
386 return __res; \
387 }
388
389#define _Avrlibc_Def_Pgm_2(Name, Typ) \
390 static __ATTR_ALWAYS_INLINE__ \
391 Typ pgm_read_##Name (const Typ *__addr) \
392 { \
393 Typ __res; \
394 __LPM__2 (__res, __addr); \
395 return __res; \
396 }
397
398#define _Avrlibc_Def_Pgm_3(Name, Typ) \
399 static __ATTR_ALWAYS_INLINE__ \
400 Typ pgm_read_##Name (const Typ *__addr) \
401 { \
402 Typ __res; \
403 __LPM__3 (__res, __addr); \
404 return __res; \
405 }
406
407#define _Avrlibc_Def_Pgm_4(Name, Typ) \
408 static __ATTR_ALWAYS_INLINE__ \
409 Typ pgm_read_##Name (const Typ *__addr) \
410 { \
411 Typ __res; \
412 __LPM__4 (__res, __addr); \
413 return __res; \
414 }
415
416#define _Avrlibc_Def_Pgm_8(Name, Typ) \
417 static __ATTR_ALWAYS_INLINE__ \
418 Typ pgm_read_##Name (const Typ *__addr) \
419 { \
420 Typ __res; \
421 __LPM__8 (__res, __addr); \
422 return __res; \
423 }
424
425_Avrlibc_Def_Pgm_1 (char, char)
426_Avrlibc_Def_Pgm_1 (unsigned_char, unsigned char)
427_Avrlibc_Def_Pgm_1 (signed_char, signed char)
428_Avrlibc_Def_Pgm_1 (u8, uint8_t)
429_Avrlibc_Def_Pgm_1 (i8, int8_t)
430#if __SIZEOF_INT__ == 1
431_Avrlibc_Def_Pgm_1 (int, int)
432_Avrlibc_Def_Pgm_1 (signed, signed)
433_Avrlibc_Def_Pgm_1 (unsigned, unsigned)
434_Avrlibc_Def_Pgm_1 (signed_int, signed int)
435_Avrlibc_Def_Pgm_1 (unsigned_int, unsigned int)
436#endif
437#if __SIZEOF_SHORT__ == 1
438_Avrlibc_Def_Pgm_1 (short, short)
439_Avrlibc_Def_Pgm_1 (unsigned_short, unsigned short)
440#endif
441
442_Avrlibc_Def_Pgm_2 (u16, uint16_t)
443_Avrlibc_Def_Pgm_2 (i16, int16_t)
444#if __SIZEOF_INT__ == 2
445_Avrlibc_Def_Pgm_2 (int, int)
446_Avrlibc_Def_Pgm_2 (signed, signed)
447_Avrlibc_Def_Pgm_2 (unsigned, unsigned)
448_Avrlibc_Def_Pgm_2 (signed_int, signed int)
449_Avrlibc_Def_Pgm_2 (unsigned_int, unsigned int)
450#endif
451#if __SIZEOF_SHORT__ == 2
452_Avrlibc_Def_Pgm_2 (short, short)
453_Avrlibc_Def_Pgm_2 (unsigned_short, unsigned short)
454#endif
455#if __SIZEOF_LONG__ == 2
456_Avrlibc_Def_Pgm_2 (long, long)
457_Avrlibc_Def_Pgm_2 (unsigned_long, unsigned long)
458#endif
459
460#if defined(__INT24_MAX__)
461_Avrlibc_Def_Pgm_3 (i24, __int24)
462_Avrlibc_Def_Pgm_3 (u24, __uint24)
463#endif /* Have __int24 */
464
465_Avrlibc_Def_Pgm_4 (u32, uint32_t)
466_Avrlibc_Def_Pgm_4 (i32, int32_t)
467_Avrlibc_Def_Pgm_4 (float, float)
468#if __SIZEOF_LONG__ == 4
469_Avrlibc_Def_Pgm_4 (long, long)
470_Avrlibc_Def_Pgm_4 (unsigned_long, unsigned long)
471#endif
472#if __SIZEOF_LONG_LONG__ == 4
473_Avrlibc_Def_Pgm_4 (long_long, long long)
474_Avrlibc_Def_Pgm_4 (unsigned_long_long, unsigned long long)
475#endif
476#if __SIZEOF_DOUBLE__ == 4
477_Avrlibc_Def_Pgm_4 (double, double)
478#endif
479#if __SIZEOF_LONG_DOUBLE__ == 4
480_Avrlibc_Def_Pgm_4 (long_double, long double)
481#endif
482
483#if __SIZEOF_LONG_LONG__ == 8
484_Avrlibc_Def_Pgm_8 (u64, uint64_t)
485_Avrlibc_Def_Pgm_8 (i64, int64_t)
486_Avrlibc_Def_Pgm_8 (long_long, long long)
487_Avrlibc_Def_Pgm_8 (unsigned_long_long, unsigned long long)
488#endif
489#if __SIZEOF_DOUBLE__ == 8
490_Avrlibc_Def_Pgm_8 (double, double)
491#endif
492#if __SIZEOF_LONG_DOUBLE__ == 8
493_Avrlibc_Def_Pgm_8 (long_double, long double)
494#endif
495
496#endif /* DOXYGEN */
497
498#ifdef __DOXYGEN__
499
500/** \ingroup avr_pgmspace
501 \fn char pgm_read_char_far (uint_farptr_t __addr)
502 Read a <tt>char</tt> from far byte-address \p __addr.
503 The address is in the program memory. */
504static inline char pgm_read_char_far (uint_farptr_t __addr);
505
506/** \ingroup avr_pgmspace
507 \fn unsigned char pgm_read_unsigned_char_far (uint_farptr_t __addr)
508 Read an <tt>unsigned char</tt> from far byte-address \p __addr.
509 The address is in the program memory. */
510static inline unsigned char pgm_read_unsigned_char_far (uint_farptr_t __addr);
511
512/** \ingroup avr_pgmspace
513 \fn signed char pgm_read_signed_char_far (uint_farptr_t __addr)
514 Read a <tt>signed char</tt> from far byte-address \p __addr.
515 The address is in the program memory. */
516static inline signed char pgm_read_signed_char_far (uint_farptr_t __addr);
517
518/** \ingroup avr_pgmspace
519 \fn uint8_t pgm_read_u8_far (uint_farptr_t __addr)
520 Read an <tt>uint8_t</tt> from far byte-address \p __addr.
521 The address is in the program memory. */
522static inline uint8_t pgm_read_u8_far (uint_farptr_t __addr);
523
524/** \ingroup avr_pgmspace
525 \fn int8_t pgm_read_i8_far (uint_farptr_t __addr)
526 Read an <tt>int8_t</tt> from far byte-address \p __addr.
527 The address is in the program memory. */
528static inline int8_t pgm_read_i8_far (uint_farptr_t __addr);
529
530/** \ingroup avr_pgmspace
531 \fn short pgm_read_short_far (uint_farptr_t __addr)
532 Read a <tt>short</tt> from far byte-address \p __addr.
533 The address is in the program memory. */
534static inline short pgm_read_short_far (uint_farptr_t __addr);
535
536/** \ingroup avr_pgmspace
537 \fn unsigned short pgm_read_unsigned_short_far (uint_farptr_t __addr)
538 Read an <tt>unsigned short</tt> from far byte-address \p __addr.
539 The address is in the program memory. */
540static inline unsigned short pgm_read_unsigned_short_far (uint_farptr_t __addr);
541
542/** \ingroup avr_pgmspace
543 \fn uint16_t pgm_read_u16_far (uint_farptr_t __addr)
544 Read an <tt>uint16_t</tt> from far byte-address \p __addr.
545 The address is in the program memory. */
546static inline uint16_t pgm_read_u16_far (uint_farptr_t __addr);
547
548/** \ingroup avr_pgmspace
549 \fn int16_t pgm_read_i16_far (uint_farptr_t __addr)
550 Read an <tt>int16_t</tt> from far byte-address \p __addr.
551 The address is in the program memory. */
552static inline int16_t pgm_read_i16_far (uint_farptr_t __addr);
553
554/** \ingroup avr_pgmspace
555 \fn int pgm_read_int_far (uint_farptr_t __addr)
556 Read an <tt>int</tt> from far byte-address \p __addr.
557 The address is in the program memory. */
558static inline int pgm_read_int_far (uint_farptr_t __addr);
559
560/** \ingroup avr_pgmspace
561 \fn unsigned pgm_read_unsigned_far (uint_farptr_t __addr)
562 Read an <tt>unsigned</tt> from far byte-address \p __addr.
563 The address is in the program memory. */
564static inline unsigned pgm_read_unsigned_far (uint_farptr_t __addr);
565
566/** \ingroup avr_pgmspace
567 \fn unsigned int pgm_read_unsigned_int_far (uint_farptr_t __addr)
568 Read an <tt>unsigned int</tt> from far byte-address \p __addr.
569 The address is in the program memory. */
570static inline unsigned int pgm_read_unsigned_int_far (uint_farptr_t __addr);
571
572/** \ingroup avr_pgmspace
573 \fn signed pgm_read_signed_far (uint_farptr_t __addr)
574 Read a <tt>signed</tt> from far byte-address \p __addr.
575 The address is in the program memory. */
576static inline signed pgm_read_signed_far (uint_farptr_t __addr);
577
578/** \ingroup avr_pgmspace
579 \fn signed int pgm_read_signed_int_far (uint_farptr_t __addr)
580 Read a <tt>signed int</tt> from far byte-address \p __addr.
581 The address is in the program memory. */
582static inline signed int pgm_read_signed_int_far (uint_farptr_t __addr);
583
584/** \ingroup avr_pgmspace
585 \fn long pgm_read_long_far (uint_farptr_t __addr)
586 Read a <tt>long</tt> from far byte-address \p __addr.
587 The address is in the program memory. */
588static inline long pgm_read_long_far (uint_farptr_t __addr);
589
590/** \ingroup avr_pgmspace
591 \fn unsigned long pgm_read_unsigned_long_far (uint_farptr_t __addr)
592 Read an <tt>unsigned long</tt> from far byte-address \p __addr.
593 The address is in the program memory. */
594static inline unsigned long pgm_read_unsigned_long_far (uint_farptr_t __addr);
595
596/** \ingroup avr_pgmspace
597 \fn __int24 pgm_read_i24_far (uint_farptr_t __addr)
598 Read an <tt>__int24</tt> from far byte-address \p __addr.
599 The address is in the program memory. */
600static inline __int24 pgm_read_i24_far (uint_farptr_t __addr);
601
602/** \ingroup avr_pgmspace
603 \fn __uint24 pgm_read_u24_far (uint_farptr_t __addr)
604 Read an <tt>__uint24</tt> from far byte-address \p __addr.
605 The address is in the program memory. */
606static inline __uint24 pgm_read_u24_far (uint_farptr_t __addr);
607
608/** \ingroup avr_pgmspace
609 \fn uint32_t pgm_read_u32_far (uint_farptr_t __addr)
610 Read an <tt>uint32_t</tt> from far byte-address \p __addr.
611 The address is in the program memory. */
612static inline uint32_t pgm_read_u32_far (uint_farptr_t __addr);
613
614/** \ingroup avr_pgmspace
615 \fn int32_t pgm_read_i32_far (uint_farptr_t __addr)
616 Read an <tt>int32_t</tt> from far byte-address \p __addr.
617 The address is in the program memory. */
618static inline int32_t pgm_read_i32_far (uint_farptr_t __addr);
619
620/** \ingroup avr_pgmspace
621 \fn long long pgm_read_long_long_far (uint_farptr_t __addr)
622 Read a <tt>long long</tt> from far byte-address \p __addr.
623 The address is in the program memory. */
624static inline long long pgm_read_long_long_far (uint_farptr_t __addr);
625
626/** \ingroup avr_pgmspace
627 \fn unsigned long long pgm_read_unsigned_long_long_far (uint_farptr_t __addr)
628 Read an <tt>unsigned long long</tt> from far byte-address \p __addr.
629 The address is in the program memory. */
630static inline unsigned long long pgm_read_unsigned_long_long_far (uint_farptr_t __addr);
631
632/** \ingroup avr_pgmspace
633 \fn uint64_t pgm_read_u64_far (uint_farptr_t __addr)
634 Read an <tt>uint64_t</tt> from far byte-address \p __addr.
635 The address is in the program memory. */
636static inline uint64_t pgm_read_u64_far (uint_farptr_t __addr);
637
638/** \ingroup avr_pgmspace
639 \fn int64_t pgm_read_i64_far (uint_farptr_t __addr)
640 Read an <tt>int64_t</tt> from far byte-address \p __addr.
641 The address is in the program memory. */
642static inline int64_t pgm_read_i64_far (uint_farptr_t __addr);
643
644/** \ingroup avr_pgmspace
645 \fn float pgm_read_float_far (uint_farptr_t __addr)
646 Read a <tt>float</tt> from far byte-address \p __addr.
647 The address is in the program memory. */
648static inline float pgm_read_float_far (uint_farptr_t __addr);
649
650/** \ingroup avr_pgmspace
651 \fn double pgm_read_double_far (uint_farptr_t __addr)
652 Read a <tt>double</tt> from far byte-address \p __addr.
653 The address is in the program memory. */
654static inline double pgm_read_double_far (uint_farptr_t __addr);
655
656/** \ingroup avr_pgmspace
657 \fn long double pgm_read_long_double_far (uint_farptr_t __addr)
658 Read a <tt>long double</tt> from far byte-address \p __addr.
659 The address is in the program memory. */
660static inline long double pgm_read_long_double_far (uint_farptr_t __addr);
661
662#else /* !DOXYGEN */
663
664#if defined(__AVR_HAVE_ELPMX__)
665
666#ifdef __AVR_HAVE_RAMPD__
667/* For devices with EBI, reset RAMPZ to zero after. */
668#define __pgm_clr_RAMPZ_ "\n\t" "out %i2,__zero_reg__"
669#else
670/* Devices without EBI: no need to reset RAMPZ. */
671#define __pgm_clr_RAMPZ_ /* empty */
672#endif
673
674#define __ELPM__1(res, addr, T) \
675 __asm __volatile__ ("movw r30,%1" "\n\t" \
676 "out %i2,%C1" "\n\t" \
677 "elpm %A0,Z" \
678 __pgm_clr_RAMPZ_ \
679 : "=r" (res) \
680 : "r" (addr), "n" (& RAMPZ) \
681 : "r30", "r31")
682
683#define __ELPM__2(res, addr, T) \
684 __asm __volatile__ ("movw r30,%1" "\n\t" \
685 "out %i2,%C1" "\n\t" \
686 "elpm %A0,Z+" "\n\t" \
687 "elpm %B0,Z+" \
688 __pgm_clr_RAMPZ_ \
689 : "=r" (res) \
690 : "r" (addr), "n" (& RAMPZ) \
691 : "r30", "r31")
692
693#define __ELPM__3(res, addr, T) \
694 __asm __volatile__ ("movw r30,%1" "\n\t" \
695 "out %i2,%C1" "\n\t" \
696 "elpm %A0,Z+" "\n\t" \
697 "elpm %B0,Z+" "\n\t" \
698 "elpm %C0,Z+" \
699 __pgm_clr_RAMPZ_ \
700 : "=r" (res) \
701 : "r" (addr), "n" (& RAMPZ) \
702 : "r30", "r31")
703
704#define __ELPM__4(res, addr, T) \
705 __asm __volatile__ ("movw r30,%1" "\n\t" \
706 "out %i2,%C1" "\n\t" \
707 "elpm %A0,Z+" "\n\t" \
708 "elpm %B0,Z+" "\n\t" \
709 "elpm %C0,Z+" "\n\t" \
710 "elpm %D0,Z+" \
711 __pgm_clr_RAMPZ_ \
712 : "=r" (res) \
713 : "r" (addr), "n" (& RAMPZ) \
714 : "r30", "r31")
715
716#define __ELPM__8(res, addr, T) \
717 __asm __volatile__ ("movw r30,%1" "\n\t" \
718 "out %i2,%C1" "\n\t" \
719 "elpm %r0+0,Z+" "\n\t" \
720 "elpm %r0+1,Z+" "\n\t" \
721 "elpm %r0+2,Z+" "\n\t" \
722 "elpm %r0+3,Z+" "\n\t" \
723 "elpm %r0+4,Z+" "\n\t" \
724 "elpm %r0+5,Z+" "\n\t" \
725 "elpm %r0+6,Z+" "\n\t" \
726 "elpm %r0+7,Z+" \
727 __pgm_clr_RAMPZ_ \
728 : "=r" (res) \
729 : "r" (addr), "n" (& RAMPZ) \
730 : "r30", "r31")
731
732/* FIXME: AT43USB320 does not have RAMPZ but supports (external) program
733 memory of 64 KiW, at least that's what the comments in io43usb32x.h are
734 indicating. A solution would be to put the device in a different
735 multilib-set (see GCC PR78275), as io.h has "#define FLASHEND 0x0FFFF".
736 For now, just exclude AT43USB320 from code that uses RAMPZ. Also note
737 that the manual asserts that the entire program memory can be accessed
738 by LPM, implying only 64 KiB of program memory. */
739#elif defined(__AVR_HAVE_ELPM__) \
740 && !defined(__AVR_AT43USB320__)
741/* The poor devices without ELPMx: Do 24-bit addresses by hand... */
742#define __ELPM__1(res, addr, T) \
743 __asm __volatile__ ("mov r30,%A1" "\n\t" \
744 "mov r31,%B1" "\n\t" \
745 "out %i2,%C1 $ elpm $ mov %A0,r0" \
746 : "=r" (res) \
747 : "r" (addr), "n" (& RAMPZ) \
748 : "r30", "r31", "r0")
749
750#define __ELPM__2(res, addr, T) \
751 __asm __volatile__ \
752 ("mov r30,%A1" "\n\t" \
753 "mov r31,%B1" "\n\t" \
754 "mov %B0,%C1" "\n\t" \
755 "out %i2,%B0 $ elpm $ mov %A0,r0 $ adiw r30,1 $ adc %B0,r1" "\n\t" \
756 "out %i2,%B0 $ elpm $ mov %B0,r0" \
757 : "=r" (res) \
758 : "r" (addr), "n" (& RAMPZ) \
759 : "r30", "r31", "r0")
760
761#define __ELPM__3(res, addr, T) \
762 __asm __volatile__ \
763 ("mov r30,%A1" "\n\t" \
764 "mov r31,%B1" "\n\t" \
765 "mov %C0,%C1" "\n\t" \
766 "out %i2,%C0 $ elpm $ mov %A0,r0 $ adiw r30,1 $ adc %C0,r1" "\n\t" \
767 "out %i2,%C0 $ elpm $ mov %B0,r0 $ adiw r30,1 $ adc %C0,r1" "\n\t" \
768 "out %i2,%C0 $ elpm $ mov %C0,r0" \
769 : "=r" (res) \
770 : "r" (addr), "n" (& RAMPZ) \
771 : "r30", "r31", "r0")
772
773#define __ELPM__4(res, addr, T) \
774 __asm __volatile__ \
775 ("mov r30,%A1" "\n\t" \
776 "mov r31,%B1" "\n\t" \
777 "mov %D0,%C1" "\n\t" \
778 "out %i2,%D0 $ elpm $ mov %A0,r0 $ adiw r30,1 $ adc %D0,r1" "\n\t" \
779 "out %i2,%D0 $ elpm $ mov %B0,r0 $ adiw r30,1 $ adc %D0,r1" "\n\t" \
780 "out %i2,%D0 $ elpm $ mov %C0,r0 $ adiw r30,1 $ adc %D0,r1" "\n\t" \
781 "out %i2,%D0 $ elpm $ mov %D0,r0" \
782 : "=r" (res) \
783 : "r" (addr), "n" (& RAMPZ) \
784 : "r30", "r31", "r0")
785
786#define __ELPM__8(res, addr, T) \
787 __asm __volatile__ \
788 ("mov r30,%A1" "\n\t" \
789 "mov r31,%B1" "\n\t" \
790 "mov %r0+7,%C1" "\n\t" \
791 "out %i2,%r0+7 $ elpm $ mov %r0+0,r0 $ adiw r30,1 $ adc %r0+7,r1" "\n\t" \
792 "out %i2,%r0+7 $ elpm $ mov %r0+1,r0 $ adiw r30,1 $ adc %r0+7,r1" "\n\t" \
793 "out %i2,%r0+7 $ elpm $ mov %r0+2,r0 $ adiw r30,1 $ adc %r0+7,r1" "\n\t" \
794 "out %i2,%r0+7 $ elpm $ mov %r0+3,r0 $ adiw r30,1 $ adc %r0+7,r1" "\n\t" \
795 "out %i2,%r0+7 $ elpm $ mov %r0+4,r0 $ adiw r30,1 $ adc %r0+7,r1" "\n\t" \
796 "out %i2,%r0+7 $ elpm $ mov %r0+5,r0 $ adiw r30,1 $ adc %r0+7,r1" "\n\t" \
797 "out %i2,%r0+7 $ elpm $ mov %r0+6,r0 $ adiw r30,1 $ adc %r0+7,r1" "\n\t" \
798 "out %i2,%r0+7 $ elpm $ mov %r0+7,r0" \
799 : "=r" (res) \
800 : "r" (addr), "n" (& RAMPZ) \
801 : "r30", "r31", "r0")
802#else
803/* No ELPM: Fall back to __LPM__<N>. */
804#define __ELPM__1(r,a,T) const T *__a = (const T*)(uint16_t) a; __LPM__1(r,__a)
805#define __ELPM__2(r,a,T) const T *__a = (const T*)(uint16_t) a; __LPM__2(r,__a)
806#define __ELPM__3(r,a,T) const T *__a = (const T*)(uint16_t) a; __LPM__3(r,__a)
807#define __ELPM__4(r,a,T) const T *__a = (const T*)(uint16_t) a; __LPM__4(r,__a)
808#define __ELPM__8(r,a,T) const T *__a = (const T*)(uint16_t) a; __LPM__8(r,__a)
809#endif /* ELPM cases */
810
811#define _Avrlibc_Def_Pgm_Far_1(Name, Typ) \
812 static __ATTR_ALWAYS_INLINE__ \
813 Typ pgm_read_##Name##_far (uint_farptr_t __addr) \
814 { \
815 Typ __res; \
816 __ELPM__1 (__res, __addr, Typ); \
817 return __res; \
818 }
819
820#define _Avrlibc_Def_Pgm_Far_2(Name, Typ) \
821 static __ATTR_ALWAYS_INLINE__ \
822 Typ pgm_read_##Name##_far (uint_farptr_t __addr) \
823 { \
824 Typ __res; \
825 __ELPM__2 (__res, __addr, Typ); \
826 return __res; \
827 }
828
829#define _Avrlibc_Def_Pgm_Far_3(Name, Typ) \
830 static __ATTR_ALWAYS_INLINE__ \
831 Typ pgm_read_##Name##_far (uint_farptr_t __addr) \
832 { \
833 Typ __res; \
834 __ELPM__3 (__res, __addr, Typ); \
835 return __res; \
836 }
837
838#define _Avrlibc_Def_Pgm_Far_4(Name, Typ) \
839 static __ATTR_ALWAYS_INLINE__ \
840 Typ pgm_read_##Name##_far (uint_farptr_t __addr) \
841 { \
842 Typ __res; \
843 __ELPM__4 (__res, __addr, Typ); \
844 return __res; \
845 }
846
847#define _Avrlibc_Def_Pgm_Far_8(Name, Typ) \
848 static __ATTR_ALWAYS_INLINE__ \
849 Typ pgm_read_##Name##_far (uint_farptr_t __addr) \
850 { \
851 Typ __res; \
852 __ELPM__8 (__res, __addr, Typ); \
853 return __res; \
854 }
855
856_Avrlibc_Def_Pgm_Far_1 (char, char)
857_Avrlibc_Def_Pgm_Far_1 (unsigned_char, unsigned char)
858_Avrlibc_Def_Pgm_Far_1 (signed_char, signed char)
859_Avrlibc_Def_Pgm_Far_1 (u8, uint8_t)
860_Avrlibc_Def_Pgm_Far_1 (i8, int8_t)
861#if __SIZEOF_INT__ == 1
862_Avrlibc_Def_Pgm_Far_1 (int, int)
863_Avrlibc_Def_Pgm_Far_1 (unsigned, unsigned)
864_Avrlibc_Def_Pgm_Far_1 (unsigned_int, unsigned int)
865_Avrlibc_Def_Pgm_Far_1 (signed, signed)
866_Avrlibc_Def_Pgm_Far_1 (signed_int, signed int)
867#endif
868#if __SIZEOF_SHORT__ == 1
869_Avrlibc_Def_Pgm_Far_1 (short, short)
870_Avrlibc_Def_Pgm_Far_1 (unsigned_short, unsigned short)
871#endif
872
873_Avrlibc_Def_Pgm_Far_2 (u16, uint16_t)
874_Avrlibc_Def_Pgm_Far_2 (i16, int16_t)
875#if __SIZEOF_INT__ == 2
876_Avrlibc_Def_Pgm_Far_2 (int, int)
877_Avrlibc_Def_Pgm_Far_2 (unsigned, unsigned)
878_Avrlibc_Def_Pgm_Far_2 (unsigned_int, unsigned int)
879_Avrlibc_Def_Pgm_Far_2 (signed, signed)
880_Avrlibc_Def_Pgm_Far_2 (signed_int, signed int)
881#endif
882#if __SIZEOF_SHORT__ == 2
883_Avrlibc_Def_Pgm_Far_2 (short, short)
884_Avrlibc_Def_Pgm_Far_2 (unsigned_short, unsigned short)
885#endif
886#if __SIZEOF_LONG__ == 2
887_Avrlibc_Def_Pgm_Far_2 (long, long)
888_Avrlibc_Def_Pgm_Far_2 (unsigned_long, unsigned long)
889#endif
890
891#if defined(__INT24_MAX__)
892_Avrlibc_Def_Pgm_Far_3 (i24, __int24)
893_Avrlibc_Def_Pgm_Far_3 (u24, __uint24)
894#endif /* Have __int24 */
895
896_Avrlibc_Def_Pgm_Far_4 (u32, uint32_t)
897_Avrlibc_Def_Pgm_Far_4 (i32, int32_t)
898_Avrlibc_Def_Pgm_Far_4 (float, float)
899#if __SIZEOF_LONG__ == 4
900_Avrlibc_Def_Pgm_Far_4 (long, long)
901_Avrlibc_Def_Pgm_Far_4 (unsigned_long, unsigned long)
902#endif
903#if __SIZEOF_LONG_LONG__ == 4
904_Avrlibc_Def_Pgm_Far_4 (long_long, long long)
905_Avrlibc_Def_Pgm_Far_4 (unsigned_long_long, unsigned long long)
906#endif
907#if __SIZEOF_DOUBLE__ == 4
908_Avrlibc_Def_Pgm_Far_4 (double, double)
909#endif
910#if __SIZEOF_LONG_DOUBLE__ == 4
911_Avrlibc_Def_Pgm_Far_4 (long_double, long double)
912#endif
913
914#if __SIZEOF_LONG_LONG__ == 8
915_Avrlibc_Def_Pgm_Far_8 (u64, uint64_t)
916_Avrlibc_Def_Pgm_Far_8 (i64, int64_t)
917_Avrlibc_Def_Pgm_Far_8 (long_long, long long)
918_Avrlibc_Def_Pgm_Far_8 (unsigned_long_long, unsigned long long)
919#endif
920#if __SIZEOF_DOUBLE__ == 8
921_Avrlibc_Def_Pgm_Far_8 (double, double)
922#endif
923#if __SIZEOF_LONG_DOUBLE__ == 8
924_Avrlibc_Def_Pgm_Far_8 (long_double, long double)
925#endif
926
927#endif /* DOXYGEN */
928
929#ifdef __cplusplus
930extern "C" {
931#endif
932
933#if defined(__DOXYGEN__)
934/* No documentation for the deprecated stuff. */
935#elif defined(__PROG_TYPES_COMPAT__) /* !DOXYGEN */
936
937typedef void prog_void __attribute__((__progmem__,__deprecated__("prog_void type is deprecated.")));
938typedef char prog_char __attribute__((__progmem__,__deprecated__("prog_char type is deprecated.")));
939typedef unsigned char prog_uchar __attribute__((__progmem__,__deprecated__("prog_uchar type is deprecated.")));
940typedef int8_t prog_int8_t __attribute__((__progmem__,__deprecated__("prog_int8_t type is deprecated.")));
941typedef uint8_t prog_uint8_t __attribute__((__progmem__,__deprecated__("prog_uint8_t type is deprecated.")));
942typedef int16_t prog_int16_t __attribute__((__progmem__,__deprecated__("prog_int16_t type is deprecated.")));
943typedef uint16_t prog_uint16_t __attribute__((__progmem__,__deprecated__("prog_uint16_t type is deprecated.")));
944typedef int32_t prog_int32_t __attribute__((__progmem__,__deprecated__("prog_int32_t type is deprecated.")));
945typedef uint32_t prog_uint32_t __attribute__((__progmem__,__deprecated__("prog_uint32_t type is deprecated.")));
946#if !__USING_MINT8
947typedef int64_t prog_int64_t __attribute__((__progmem__,__deprecated__("prog_int64_t type is deprecated.")));
948typedef uint64_t prog_uint64_t __attribute__((__progmem__,__deprecated__("prog_uint64_t type is deprecated.")));
949#endif
950
951#ifndef PGM_P
952#define PGM_P const prog_char *
953#endif
954
955#ifndef PGM_VOID_P
956#define PGM_VOID_P const prog_void *
957#endif
958
959#else /* !defined(__DOXYGEN__), !defined(__PROG_TYPES_COMPAT__) */
960
961#ifndef PGM_P
962#define PGM_P const char *
963#endif
964
965#ifndef PGM_VOID_P
966#define PGM_VOID_P const void *
967#endif
968#endif /* defined(__DOXYGEN__), defined(__PROG_TYPES_COMPAT__) */
969
970/* Although in C, we can get away with just using __c, it does not work in
971 C++. We need to use &__c[0] to avoid the compiler puking. Dave Hylands
972 explaned it thusly,
973
974 Let's suppose that we use PSTR("Test"). In this case, the type returned
975 by __c is a prog_char[5] and not a prog_char *. While these are
976 compatible, they aren't the same thing (especially in C++). The type
977 returned by &__c[0] is a prog_char *, which explains why it works
978 fine. */
979
980#if defined(__DOXYGEN__)
981/*
982 * The #define below is just a dummy that serves documentation
983 * purposes only.
984 */
985/** \ingroup avr_pgmspace
986 \def PSTR(str)
987
988 Used to declare a static pointer to a string in program space. */
989# define PSTR(str) ({ static const PROGMEM char c[] = (str); &c[0]; })
990#else /* !DOXYGEN */
991/* The real thing. */
992# define PSTR(s) (__extension__({static const char __c[] PROGMEM = (s); &__c[0];}))
993#endif /* DOXYGEN */
994
995#if defined(__DOXYGEN__)
996/** \ingroup avr_pgmspace
997 \def PSTR_FAR(str)
998
999 Used to define a string literal in far program space, and to return its
1000 address of type #uint_farptr_t. */
1001# define PSTR_FAR(str) ({ static const PROGMEM_FAR char c[] = (str); pgm_get_far_address(c[0]); })
1002#else /* !DOXYGEN */
1003/* The real thing. */
1004# define PSTR_FAR(s) (__extension__({static const char __c[] PROGMEM_FAR = (s); pgm_get_far_address(__c[0]);}))
1005#endif /* DOXYGEN */
1006
1007#ifndef __DOXYGEN__
1008
1009/* These are used down the line for pgm_read_byte[_near] etc. */
1010
1011#if defined (__AVR_TINY__)
1012/* Attribute __progmem__ on Reduced Tiny works different than for
1013 all the other devices: When taking the address of a symbol that's
1014 attributed as progmem, then the compiler adds an offset of 0x4000
1015 to the value of the symbol. This means that accessing data in
1016 progmem can be performed by vanilla C/C++ code. This requires
1017 - GCC PR71948 - Make progmem work on Reduced Tiny (GCC v7 / 2016-08) */
1018#define __LPM(addr) (* (const uint8_t*)(addr))
1019#define __LPM_word(addr) (* (const uint16_t*)(addr))
1020#define __LPM_dword(addr) (* (const uint32_t*)(addr))
1021# if __SIZEOF_LONG_LONG__ == 8
1022# define __LPM_qword(addr) (* (const uint64_t*)(addr))
1023# endif
1024#else
1025#define __LPM(addr) \
1026 (__extension__({ \
1027 uint16_t __addr16 = (uint16_t) (addr); \
1028 uint8_t __result; \
1029 __LPM__1 (__result, __addr16); \
1030 __result; \
1031}))
1032
1033#define __LPM_word(addr) \
1034 (__extension__({ \
1035 uint16_t __addr16 = (uint16_t) (addr); \
1036 uint16_t __result; \
1037 __LPM__2 (__result, __addr16); \
1038 __result; \
1039}))
1040
1041#define __LPM_dword(addr) \
1042 (__extension__({ \
1043 uint16_t __addr16 = (uint16_t) (addr); \
1044 uint32_t __result; \
1045 __LPM__4 (__result, __addr16); \
1046 __result; \
1047}))
1048
1049#if __SIZEOF_LONG_LONG__ == 8
1050#define __LPM_qword(addr) \
1051 (__extension__({ \
1052 uint16_t __addr16 = (uint16_t) (addr); \
1053 uint64_t __result; \
1054 __LPM__8 (__result, __addr16); \
1055 __result; \
1056}))
1057#endif
1058#endif /* AVR_TINY */
1059
1060
1061#define __ELPM(addr) \
1062 (__extension__({ \
1063 uint_farptr_t __addr32 = (addr); \
1064 uint8_t __result; \
1065 __ELPM__1 (__result, __addr32, uint8_t); \
1066 __result; \
1067}))
1068
1069#define __ELPM_word(addr) \
1070 (__extension__({ \
1071 uint_farptr_t __addr32 = (addr); \
1072 uint16_t __result; \
1073 __ELPM__2 (__result, __addr32, uint16_t); \
1074 __result; \
1075}))
1076
1077#define __ELPM_dword(addr) \
1078 (__extension__({ \
1079 uint_farptr_t __addr32 = (addr); \
1080 uint32_t __result; \
1081 __ELPM__4 (__result, __addr32, uint32_t); \
1082 __result; \
1083}))
1084
1085#if __SIZEOF_LONG_LONG__ == 8
1086#define __ELPM_qword(addr) \
1087 (__extension__({ \
1088 uint_farptr_t __addr32 = (addr); \
1089 uint64_t __result; \
1090 __ELPM__8 (__result, __addr32, uint64_t); \
1091 __result; \
1092}))
1093#endif
1094
1095#endif /* !__DOXYGEN__ */
1096
1097/** \ingroup avr_pgmspace
1098 \def pgm_read_byte_near(__addr)
1099 Read a byte from the program space with a 16-bit (near) byte-address. */
1100
1101#define pgm_read_byte_near(__addr) __LPM ((uint16_t)(__addr))
1102
1103/** \ingroup avr_pgmspace
1104 \def pgm_read_word_near(__addr)
1105 Read a word from the program space with a 16-bit (near) byte-address. */
1106
1107#define pgm_read_word_near(__addr) __LPM_word ((uint16_t)(__addr))
1108
1109/** \ingroup avr_pgmspace
1110 \def pgm_read_dword_near(__addr)
1111 Read a double word from the program space with a 16-bit (near)
1112 byte-address. */
1113
1114#define pgm_read_dword_near(__addr) \
1115 __LPM_dword ((uint16_t)(__addr))
1116
1117/** \ingroup avr_pgmspace
1118 \def pgm_read_qword_near(__addr)
1119 Read a quad-word from the program space with a 16-bit (near)
1120 byte-address. */
1121
1122#define pgm_read_qword_near(__addr) __LPM_qword ((uint16_t)(__addr))
1123
1124/** \ingroup avr_pgmspace
1125 \def pgm_read_float_near (const float *address)
1126 Read a \c float from the program space with a 16-bit (near) byte-address.*/
1127
1128#define pgm_read_float_near(addr) pgm_read_float (addr)
1129
1130/** \ingroup avr_pgmspace
1131 \def pgm_read_ptr_near(__addr)
1132 Read a pointer from the program space with a 16-bit (near) byte-address. */
1133
1134#define pgm_read_ptr_near(__addr) \
1135 ((void*) __LPM_word ((uint16_t)(__addr)))
1136
1137/** \ingroup avr_pgmspace
1138 \def pgm_read_byte_far(__addr)
1139 Read a byte from the program space with a 32-bit (far) byte-address. */
1140
1141#define pgm_read_byte_far(__addr) __ELPM (__addr)
1142
1143/** \ingroup avr_pgmspace
1144 \def pgm_read_word_far(__addr)
1145 Read a word from the program space with a 32-bit (far) byte-address. */
1146
1147#define pgm_read_word_far(__addr) __ELPM_word (__addr)
1148
1149/** \ingroup avr_pgmspace
1150 \def pgm_read_dword_far(__addr)
1151 Read a double word from the program space with a 32-bit (far)
1152 byte-address. */
1153
1154#define pgm_read_dword_far(__addr) __ELPM_dword (__addr)
1155
1156/** \ingroup avr_pgmspace
1157 \def pgm_read_qword_far(__addr)
1158 Read a quad-word from the program space with a 32-bit (far)
1159 byte-address. */
1160
1161#define pgm_read_qword_far(__addr) __ELPM_qword (__addr)
1162
1163/** \ingroup avr_pgmspace
1164 \def pgm_read_ptr_far(__addr)
1165 Read a pointer from the program space with a 32-bit (far) byte-address. */
1166
1167#define pgm_read_ptr_far(__addr) ((void*) __ELPM_word (__addr))
1168
1169/** \ingroup avr_pgmspace
1170 \def pgm_read_byte(__addr)
1171 Read a byte from the program space with a 16-bit (near) nyte-address. */
1172
1173#define pgm_read_byte(__addr) pgm_read_byte_near(__addr)
1174
1175/** \ingroup avr_pgmspace
1176 \def pgm_read_word(__addr)
1177 Read a word from the program space with a 16-bit (near) byte-address. */
1178
1179#define pgm_read_word(__addr) pgm_read_word_near(__addr)
1180
1181/** \ingroup avr_pgmspace
1182 \def pgm_read_dword(__addr)
1183 Read a double word from the program space with a 16-bit (near)
1184 byte-address. */
1185
1186#define pgm_read_dword(__addr) pgm_read_dword_near(__addr)
1187
1188/** \ingroup avr_pgmspace
1189 \def pgm_read_qword(__addr)
1190 Read a quad-word from the program space with a 16-bit (near)
1191 byte-address. */
1192
1193#define pgm_read_qword(__addr) pgm_read_qword_near(__addr)
1194
1195/** \ingroup avr_pgmspace
1196 \def pgm_read_ptr(__addr)
1197 Read a pointer from the program space with a 16-bit (near) byte-address. */
1198
1199#define pgm_read_ptr(__addr) pgm_read_ptr_near(__addr)
1200
1201/** \ingroup avr_pgmspace
1202 \def pgm_get_far_address(var)
1203
1204 This macro evaluates to a ::uint_farptr_t 32-bit "far" pointer (only
1205 24 bits used) to data even beyond the 64 KiB limit for the 16-bit ordinary
1206 pointer. It is similar to the '&' operator, with some limitations.
1207 Example:
1208 \code
1209 #include <avr/pgmspace.h>
1210
1211 // Section .progmemx.data is located after all the code sections.
1212 PROGMEM_FAR
1213 const int data[] = { 2, 3, 5, 7, 9, 11 };
1214
1215 int get_data (uint8_t idx)
1216 {
1217 uint_farptr_t pdata = pgm_get_far_address (data[0]);
1218 return pgm_read_int_far (pdata + idx * sizeof(int));
1219 }
1220 \endcode
1221
1222 Comments:
1223
1224 - The overhead is minimal and it's mainly due to the 32-bit size operation.
1225
1226 - 24 bit sizes guarantees the code compatibility for use in future devices.
1227
1228 - \p var has to be resolved at link-time as an existing symbol,
1229 i.e. a simple variable name, an array name, or an array or structure
1230 element provided the offset is known at compile-time, and \p var is
1231 located in static storage, etc.
1232*/
1233#ifdef __DOXYGEN__
1234#define pgm_get_far_address(var)
1235#else
1236#ifndef __AVR_TINY__
1237#define pgm_get_far_address(var) \
1238(__extension__({ \
1239 uint_farptr_t __tmp; \
1240 \
1241 __asm__ __volatile__ ( \
1242 "ldi %A0, lo8(%1)" "\n\t" \
1243 "ldi %B0, hi8(%1)" "\n\t" \
1244 "ldi %C0, hh8(%1)" "\n\t" \
1245 "clr %D0" \
1246 : "=d" (__tmp) \
1247 : "i" (&(var)) \
1248 ); \
1249 __tmp; \
1250}))
1251#else
1252/* The working of the pgm_read_far() functions and macros is such
1253 that they decay to pgm_read() for devices without ELPM.
1254 Since GCC v7 PR71948, the compiler adds an offset of 0x4000 on
1255 Reduced Tiny when it takes the address of an object in PROGMEM,
1256 which means we have to add 0x4000 here, too. */
1257#define pgm_get_far_address(var) \
1258(__extension__({ \
1259 uint_farptr_t __tmp; \
1260 \
1261 __asm__ __volatile__ ( \
1262 "ldi %A0, lo8(0x4000+(%1))" "\n\t" \
1263 "ldi %B0, hi8(0x4000+(%1))" "\n\t" \
1264 "ldi %C0, hh8(0x4000+(%1))" "\n\t" \
1265 "clr %D0" \
1266 : "=d" (__tmp) \
1267 : "i" (&(var)) \
1268 ); \
1269 __tmp; \
1270}))
1271#endif /* AVR TINY */
1272#endif /* DOXYGEN */
1273
1274
1275/** \ingroup avr_pgmspace
1276 \fn const void * memchr_P(const void *s, int val, size_t len)
1277 \brief Scan flash memory for a character.
1278
1279 The memchr_P() function scans the first \p len bytes of the flash
1280 memory area pointed to by \p s for the character \p val. The first
1281 byte to match \p val (interpreted as an unsigned character) stops
1282 the operation.
1283
1284 \return The memchr_P() function returns a pointer to the matching
1285 byte or \c NULL if the character does not occur in the given memory
1286 area. */
1287extern const void * memchr_P(const void *, int __val, size_t __len) __ATTR_CONST__;
1288
1289/** \ingroup avr_pgmspace
1290 \fn int memcmp_P(const void *s1, const void *s2, size_t len)
1291 \brief Compare memory areas
1292
1293 The memcmp_P() function compares the first \p len bytes of the memory
1294 areas \p s1 and flash \p s2. The comparision is performed using unsigned
1295 char operations.
1296
1297 \returns The memcmp_P() function returns an integer less than, equal
1298 to, or greater than zero if the first \p len bytes of \p s1 is found,
1299 respectively, to be less than, to match, or be greater than the first
1300 \p len bytes of \p s2. */
1301extern int memcmp_P(const void *, const void *, size_t) __ATTR_PURE__;
1302
1303/** \ingroup avr_pgmspace
1304 \fn void *memccpy_P (void *dest, const void *src, int val, size_t len)
1305
1306 This function is similar to memccpy() except that \p src is pointer
1307 to a string in program space. */
1308extern void *memccpy_P(void *, const void *, int __val, size_t);
1309
1310/** \ingroup avr_pgmspace
1311 \fn void *memcpy_P(void *dest, const void *src, size_t n)
1312
1313 The memcpy_P() function is similar to memcpy(), except the src string
1314 resides in program space.
1315
1316 \returns The memcpy_P() function returns a pointer to dest. */
1317extern void *memcpy_P(void *, const void *, size_t);
1318
1319/** \ingroup avr_pgmspace
1320 \fn void *memmem_P(const void *s1, size_t len1, const void *s2, size_t len2)
1321
1322 The memmem_P() function is similar to memmem() except that \p s2 is
1323 pointer to a string in program space. */
1324extern void *memmem_P(const void *, size_t, const void *, size_t) __ATTR_PURE__;
1325
1326/** \ingroup avr_pgmspace
1327 \fn const void +memrchr_P(const void *src, int val, size_t len)
1328
1329 The memrchr_P() function is like the memchr_P() function, except
1330 that it searches backwards from the end of the \p len bytes pointed
1331 to by \p src instead of forwards from the front. (Glibc, GNU extension.)
1332
1333 \return The memrchr_P() function returns a pointer to the matching
1334 byte or \c NULL if the character does not occur in the given memory
1335 area. */
1336extern const void * memrchr_P(const void *, int __val, size_t __len) __ATTR_CONST__;
1337
1338/** \ingroup avr_pgmspace
1339 \fn char *strcat_P(char *dest, const char *src)
1340
1341 The strcat_P() function is similar to strcat() except that the \e src
1342 string must be located in program space (flash).
1343
1344 \returns The strcat() function returns a pointer to the resulting string
1345 \e dest. */
1346extern char *strcat_P(char *, const char *);
1347
1348/** \ingroup avr_pgmspace
1349 \fn const char *strchr_P(const char *s, int val)
1350 \brief Locate character in program space string.
1351
1352 The strchr_P() function locates the first occurrence of \p val
1353 (converted to a char) in the string pointed to by \p s in program
1354 space. The terminating null character is considered to be part of
1355 the string.
1356
1357 The strchr_P() function is similar to strchr() except that \p s is
1358 pointer to a string in program space.
1359
1360 \returns The strchr_P() function returns a pointer to the matched
1361 character or \c NULL if the character is not found. */
1362extern const char * strchr_P(const char *, int __val) __ATTR_CONST__;
1363
1364/** \ingroup avr_pgmspace
1365 \fn const char *strchrnul_P(const char *s, int c)
1366
1367 The strchrnul_P() function is like strchr_P() except that if \p c is
1368 not found in \p s, then it returns a pointer to the null byte at the
1369 end of \p s, rather than \c NULL. (Glibc, GNU extension.)
1370
1371 \return The strchrnul_P() function returns a pointer to the matched
1372 character, or a pointer to the null byte at the end of \p s (i.e.,
1373 \c s+strlen(s)) if the character is not found. */
1374extern const char * strchrnul_P(const char *, int __val) __ATTR_CONST__;
1375
1376/** \ingroup avr_pgmspace
1377 \fn int strcmp_P(const char *s1, const char *s2)
1378
1379 The strcmp_P() function is similar to strcmp() except that \p s2 is
1380 pointer to a string in program space.
1381
1382 \returns The strcmp_P() function returns an integer less than, equal
1383 to, or greater than zero if \p s1 is found, respectively, to be less
1384 than, to match, or be greater than \p s2. A consequence of the
1385 ordering used by strcmp_P() is that if \p s1 is an initial substring
1386 of \p s2, then \p s1 is considered to be "less than" \p s2. */
1387extern int strcmp_P(const char *, const char *) __ATTR_PURE__;
1388
1389/** \ingroup avr_pgmspace
1390 \fn char *strcpy_P(char *dest, const char *src)
1391
1392 The strcpy_P() function is similar to strcpy() except that src is a
1393 pointer to a string in program space.
1394
1395 \returns The strcpy_P() function returns a pointer to the destination
1396 string dest. */
1397extern char *strcpy_P(char *, const char *);
1398
1399/** \ingroup avr_pgmspace
1400 \fn int strcasecmp_P(const char *s1, const char *s2)
1401 \brief Compare two strings ignoring case.
1402
1403 The strcasecmp_P() function compares the two strings \p s1 and \p s2,
1404 ignoring the case of the characters.
1405
1406 \param s1 A pointer to a string in the devices SRAM.
1407 \param s2 A pointer to a string in the devices Flash.
1408
1409 \returns The strcasecmp_P() function returns an integer less than,
1410 equal to, or greater than zero if \p s1 is found, respectively, to
1411 be less than, to match, or be greater than \p s2. A consequence of
1412 the ordering used by strcasecmp_P() is that if \p s1 is an initial
1413 substring of \p s2, then \p s1 is considered to be "less than" \p s2. */
1414extern int strcasecmp_P(const char *, const char *) __ATTR_PURE__;
1415
1416/** \ingroup avr_pgmspace
1417 \fn char *strcasestr_P(const char *s1, const char *s2)
1418
1419 This funtion is similar to strcasestr() except that \p s2 is pointer
1420 to a string in program space. */
1421extern char *strcasestr_P(const char *, const char *) __ATTR_PURE__;
1422
1423/** \ingroup avr_pgmspace
1424 \fn size_t strcspn_P(const char *s, const char *reject)
1425
1426 The strcspn_P() function calculates the length of the initial segment
1427 of \p s which consists entirely of characters not in \p reject. This
1428 function is similar to strcspn() except that \p reject is a pointer
1429 to a string in program space.
1430
1431 \return The strcspn_P() function returns the number of characters in
1432 the initial segment of \p s which are not in the string \p reject.
1433 The terminating zero is not considered as a part of string. */
1434extern size_t strcspn_P(const char *__s, const char * __reject) __ATTR_PURE__;
1435
1436/** \ingroup avr_pgmspace
1437 \fn size_t strlcat_P(char *dst, const char *src, size_t siz)
1438 \brief Concatenate two strings.
1439
1440 The strlcat_P() function is similar to strlcat(), except that the \p src
1441 string must be located in program space (flash).
1442
1443 Appends \p src to string \p dst of size \p siz (unlike strncat(),
1444 \p siz is the full size of \p dst, not space left). At most \p siz-1
1445 characters will be copied. Always NULL terminates (unless \p siz <=
1446 \p strlen(dst)).
1447
1448 \returns The strlcat_P() function returns strlen(src) + MIN(siz,
1449 strlen(initial dst)). If retval >= siz, truncation occurred. */
1450extern size_t strlcat_P (char *, const char *, size_t );
1451
1452/** \ingroup avr_pgmspace
1453 \fn size_t strlcpy_P(char *dst, const char *src, size_t siz)
1454 \brief Copy a string from progmem to RAM.
1455
1456 Copy \p src to string \p dst of size \p siz. At most \p siz-1
1457 characters will be copied. Always NULL terminates (unless \p siz == 0).
1458 The strlcpy_P() function is similar to strlcpy() except that the
1459 \p src is pointer to a string in memory space.
1460
1461 \returns The strlcpy_P() function returns strlen(src). If
1462 retval >= siz, truncation occurred. */
1463extern size_t strlcpy_P (char *, const char *, size_t );
1464
1465/** \ingroup avr_pgmspace
1466 \fn size_t strnlen_P(const char *src, size_t len)
1467 \brief Determine the length of a fixed-size string.
1468
1469 The strnlen_P() function is similar to strnlen(), except that \c src is a
1470 pointer to a string in program space.
1471
1472 \returns The strnlen_P function returns strlen_P(src), if that is less than
1473 \c len, or \c len if there is no '\\0' character among the first \c len
1474 characters pointed to by \c src. */
1475extern size_t strnlen_P(const char *, size_t) __ATTR_CONST__; /* program memory can't change */
1476
1477/** \ingroup avr_pgmspace
1478 \fn int strncmp_P(const char *s1, const char *s2, size_t n)
1479
1480 The strncmp_P() function is similar to strcmp_P() except it only compares
1481 the first (at most) n characters of s1 and s2.
1482
1483 \returns The strncmp_P() function returns an integer less than, equal to,
1484 or greater than zero if s1 (or the first n bytes thereof) is found,
1485 respectively, to be less than, to match, or be greater than s2. */
1486extern int strncmp_P(const char *, const char *, size_t) __ATTR_PURE__;
1487
1488/** \ingroup avr_pgmspace
1489 \fn int strncasecmp_P(const char *s1, const char *s2, size_t n)
1490 \brief Compare two strings ignoring case.
1491
1492 The strncasecmp_P() function is similar to strcasecmp_P(), except it
1493 only compares the first \p n characters of \p s1.
1494
1495 \param s1 A pointer to a string in the devices SRAM.
1496 \param s2 A pointer to a string in the devices Flash.
1497 \param n The maximum number of bytes to compare.
1498
1499 \returns The strncasecmp_P() function returns an integer less than,
1500 equal to, or greater than zero if \p s1 (or the first \p n bytes
1501 thereof) is found, respectively, to be less than, to match, or be
1502 greater than \p s2. A consequence of the ordering used by
1503 strncasecmp_P() is that if \p s1 is an initial substring of \p s2,
1504 then \p s1 is considered to be "less than" \p s2. */
1505extern int strncasecmp_P(const char *, const char *, size_t) __ATTR_PURE__;
1506
1507/** \ingroup avr_pgmspace
1508 \fn char *strncat_P(char *dest, const char *src, size_t len)
1509 \brief Concatenate two strings.
1510
1511 The strncat_P() function is similar to strncat(), except that the \e src
1512 string must be located in program space (flash).
1513
1514 \returns The strncat_P() function returns a pointer to the resulting string
1515 dest. */
1516extern char *strncat_P(char *, const char *, size_t);
1517
1518/** \ingroup avr_pgmspace
1519 \fn char *strncpy_P(char *dest, const char *src, size_t n)
1520
1521 The strncpy_P() function is similar to strcpy_P() except that not more
1522 than n bytes of src are copied. Thus, if there is no null byte among the
1523 first n bytes of src, the result will not be null-terminated.
1524
1525 In the case where the length of src is less than that of n, the remainder
1526 of dest will be padded with nulls.
1527
1528 \returns The strncpy_P() function returns a pointer to the destination
1529 string dest. */
1530extern char *strncpy_P(char *, const char *, size_t);
1531
1532/** \ingroup avr_pgmspace
1533 \fn char *strpbrk_P(const char *s, const char *accept)
1534
1535 The strpbrk_P() function locates the first occurrence in the string
1536 \p s of any of the characters in the flash string \p accept. This
1537 function is similar to strpbrk() except that \p accept is a pointer
1538 to a string in program space.
1539
1540 \return The strpbrk_P() function returns a pointer to the character
1541 in \p s that matches one of the characters in \p accept, or \c NULL
1542 if no such character is found. The terminating zero is not considered
1543 as a part of string: if one or both args are empty, the result will
1544 \c NULL. */
1545extern char *strpbrk_P(const char *__s, const char * __accept) __ATTR_PURE__;
1546
1547/** \ingroup avr_pgmspace
1548 \fn const char *strrchr_P(const char *s, int val)
1549 \brief Locate character in string.
1550
1551 The strrchr_P() function returns a pointer to the last occurrence of
1552 the character \p val in the flash string \p s.
1553
1554 \return The strrchr_P() function returns a pointer to the matched
1555 character or \c NULL if the character is not found. */
1556extern const char * strrchr_P(const char *, int __val) __ATTR_CONST__;
1557
1558/** \ingroup avr_pgmspace
1559 \fn char *strsep_P(char **sp, const char *delim)
1560 \brief Parse a string into tokens.
1561
1562 The strsep_P() function locates, in the string referenced by \p *sp,
1563 the first occurrence of any character in the string \p delim (or the
1564 terminating '\\0' character) and replaces it with a '\\0'. The
1565 location of the next character after the delimiter character (or \c
1566 NULL, if the end of the string was reached) is stored in \p *sp. An
1567 ``empty'' field, i.e. one caused by two adjacent delimiter
1568 characters, can be detected by comparing the location referenced by
1569 the pointer returned in \p *sp to '\\0'. This function is similar to
1570 strsep() except that \p delim is a pointer to a string in program
1571 space.
1572
1573 \return The strsep_P() function returns a pointer to the original
1574 value of \p *sp. If \p *sp is initially \c NULL, strsep_P() returns
1575 \c NULL. */
1576extern char *strsep_P(char **__sp, const char * __delim);
1577
1578/** \ingroup avr_pgmspace
1579 \fn size_t strspn_P(const char *s, const char *accept)
1580
1581 The strspn_P() function calculates the length of the initial segment
1582 of \p s which consists entirely of characters in \p accept. This
1583 function is similar to strspn() except that \p accept is a pointer
1584 to a string in program space.
1585
1586 \return The strspn_P() function returns the number of characters in
1587 the initial segment of \p s which consist only of characters from \p
1588 accept. The terminating zero is not considered as a part of string. */
1589extern size_t strspn_P(const char *__s, const char * __accept) __ATTR_PURE__;
1590
1591/** \ingroup avr_pgmspace
1592 \fn char *strstr_P(const char *s1, const char *s2)
1593 \brief Locate a substring.
1594
1595 The strstr_P() function finds the first occurrence of the substring
1596 \p s2 in the string \p s1. The terminating '\\0' characters are not
1597 compared. The strstr_P() function is similar to strstr() except that
1598 \p s2 is pointer to a string in program space.
1599
1600 \returns The strstr_P() function returns a pointer to the beginning
1601 of the substring, or NULL if the substring is not found. If \p s2
1602 points to a string of zero length, the function returns \p s1. */
1603extern char *strstr_P(const char *, const char *) __ATTR_PURE__;
1604
1605/** \ingroup avr_pgmspace
1606 \fn char *strtok_P(char *s, const char * delim)
1607 \brief Parses the string into tokens.
1608
1609 strtok_P() parses the string \p s into tokens. The first call to
1610 strtok_P() should have \p s as its first argument. Subsequent calls
1611 should have the first argument set to NULL. If a token ends with a
1612 delimiter, this delimiting character is overwritten with a '\\0' and a
1613 pointer to the next character is saved for the next call to strtok_P().
1614 The delimiter string \p delim may be different for each call.
1615
1616 The strtok_P() function is similar to strtok() except that \p delim
1617 is pointer to a string in program space.
1618
1619 \returns The strtok_P() function returns a pointer to the next token or
1620 NULL when no more tokens are found.
1621
1622 \note strtok_P() is NOT reentrant. For a reentrant version of this
1623 function see strtok_rP().
1624 */
1625extern char *strtok_P(char *__s, const char * __delim);
1626
1627/** \ingroup avr_pgmspace
1628 \fn char *strtok_rP (char *string, const char *delim, char **last)
1629 \brief Parses string into tokens.
1630
1631 The strtok_rP() function parses \p string into tokens. The first call to
1632 strtok_rP() should have string as its first argument. Subsequent calls
1633 should have the first argument set to NULL. If a token ends with a
1634 delimiter, this delimiting character is overwritten with a '\\0' and a
1635 pointer to the next character is saved for the next call to strtok_rP().
1636 The delimiter string \p delim may be different for each call. \p last is
1637 a user allocated char* pointer. It must be the same while parsing the
1638 same string. strtok_rP() is a reentrant version of strtok_P().
1639
1640 The strtok_rP() function is similar to strtok_r() except that \p delim
1641 is pointer to a string in program space.
1642
1643 \returns The strtok_rP() function returns a pointer to the next token or
1644 NULL when no more tokens are found. */
1645extern char *strtok_rP(char *__s, const char * __delim, char **__last);
1646
1647/** \ingroup avr_pgmspace
1648 \fn size_t strlen_PF(uint_farptr_t s)
1649 \brief Obtain the length of a string
1650
1651 The strlen_PF() function is similar to strlen(), except that \e s is a
1652 far pointer to a string in program space.
1653
1654 \param s A far pointer to the string in flash
1655
1656 \returns The strlen_PF() function returns the number of characters in
1657 \e s. The contents of RAMPZ SFR are undefined when the function returns. */
1658extern size_t strlen_PF(uint_farptr_t src) __ATTR_CONST__; /* program memory can't change */
1659
1660/** \ingroup avr_pgmspace
1661 \fn size_t strnlen_PF(uint_farptr_t s, size_t len)
1662 \brief Determine the length of a fixed-size string
1663
1664 The strnlen_PF() function is similar to strnlen(), except that \e s is a
1665 far pointer to a string in program space.
1666
1667 \param s A far pointer to the string in Flash
1668 \param len The maximum number of length to return
1669
1670 \returns The strnlen_PF function returns strlen_P(\e s), if that is less
1671 than \e len, or \e len if there is no '\\0' character among the first \e
1672 len characters pointed to by \e s. The contents of RAMPZ SFR are
1673 undefined when the function returns. */
1674extern size_t strnlen_PF(uint_farptr_t src, size_t len) __ATTR_CONST__; /* program memory can't change */
1675
1676/** \ingroup avr_pgmspace
1677 \fn void *memcpy_PF(void *dest, uint_farptr_t src, size_t n)
1678 \brief Copy a memory block from flash to SRAM
1679
1680 The memcpy_PF() function is similar to memcpy(), except the data
1681 is copied from the program space and is addressed using a far pointer.
1682
1683 \param dest A pointer to the destination buffer
1684 \param src A far pointer to the origin of data in flash memory
1685 \param n The number of bytes to be copied
1686
1687 \returns The memcpy_PF() function returns a pointer to \e dst. The contents
1688 of RAMPZ SFR are undefined when the function returns. */
1689extern void *memcpy_PF(void *dest, uint_farptr_t src, size_t len);
1690
1691/** \ingroup avr_pgmspace
1692 \fn char *strcpy_PF(char *dst, uint_farptr_t src)
1693 \brief Duplicate a string
1694
1695 The strcpy_PF() function is similar to strcpy() except that \e src is a far
1696 pointer to a string in program space.
1697
1698 \param dst A pointer to the destination string in SRAM
1699 \param src A far pointer to the source string in Flash
1700
1701 \returns The strcpy_PF() function returns a pointer to the destination
1702 string \e dst. The contents of RAMPZ SFR are undefined when the funcion
1703 returns. */
1704extern char *strcpy_PF(char *dest, uint_farptr_t src);
1705
1706/** \ingroup avr_pgmspace
1707 \fn char *strncpy_PF(char *dst, uint_farptr_t src, size_t n)
1708 \brief Duplicate a string until a limited length
1709
1710 The strncpy_PF() function is similar to strcpy_PF() except that not more
1711 than \e n bytes of \e src are copied. Thus, if there is no null byte among
1712 the first \e n bytes of \e src, the result will not be null-terminated.
1713
1714 In the case where the length of \e src is less than that of \e n, the
1715 remainder of \e dst will be padded with nulls.
1716
1717 \param dst A pointer to the destination string in SRAM
1718 \param src A far pointer to the source string in Flash
1719 \param n The maximum number of bytes to copy
1720
1721 \returns The strncpy_PF() function returns a pointer to the destination
1722 string \e dst. The contents of RAMPZ SFR are undefined when the function
1723 returns. */
1724extern char *strncpy_PF(char *dest, uint_farptr_t src, size_t len);
1725
1726/** \ingroup avr_pgmspace
1727 \fn char *strcat_PF(char *dst, uint_farptr_t src)
1728 \brief Concatenates two strings
1729
1730 The strcat_PF() function is similar to strcat() except that the \e src
1731 string must be located in program space (flash) and is addressed using
1732 a far pointer
1733
1734 \param dst A pointer to the destination string in SRAM
1735 \param src A far pointer to the string to be appended in Flash
1736
1737 \returns The strcat_PF() function returns a pointer to the resulting
1738 string \e dst. The contents of RAMPZ SFR are undefined when the function
1739 returns */
1740extern char *strcat_PF(char *dest, uint_farptr_t src);
1741
1742/** \ingroup avr_pgmspace
1743 \fn size_t strlcat_PF(char *dst, uint_farptr_t src, size_t n)
1744 \brief Concatenate two strings
1745
1746 The strlcat_PF() function is similar to strlcat(), except that the \e src
1747 string must be located in program space (flash) and is addressed using
1748 a far pointer.
1749
1750 Appends src to string dst of size \e n (unlike strncat(), \e n is the
1751 full size of \e dst, not space left). At most \e n-1 characters
1752 will be copied. Always NULL terminates (unless \e n <= strlen(\e dst)).
1753
1754 \param dst A pointer to the destination string in SRAM
1755 \param src A far pointer to the source string in Flash
1756 \param n The total number of bytes allocated to the destination string
1757
1758 \returns The strlcat_PF() function returns strlen(\e src) + MIN(\e n,
1759 strlen(initial \e dst)). If retval >= \e n, truncation occurred. The
1760 contents of RAMPZ SFR are undefined when the funcion returns. */
1761extern size_t strlcat_PF(char *dst, uint_farptr_t src, size_t siz);
1762
1763/** \ingroup avr_pgmspace
1764 \fn char *strncat_PF(char *dst, uint_farptr_t src, size_t n)
1765 \brief Concatenate two strings
1766
1767 The strncat_PF() function is similar to strncat(), except that the \e src
1768 string must be located in program space (flash) and is addressed using a
1769 far pointer.
1770
1771 \param dst A pointer to the destination string in SRAM
1772 \param src A far pointer to the source string in Flash
1773 \param n The maximum number of bytes to append
1774
1775 \returns The strncat_PF() function returns a pointer to the resulting
1776 string \e dst. The contents of RAMPZ SFR are undefined when the function
1777 returns. */
1778extern char *strncat_PF(char *dest, uint_farptr_t src, size_t len);
1779
1780/** \ingroup avr_pgmspace
1781 \fn int strcmp_PF(const char *s1, uint_farptr_t s2)
1782 \brief Compares two strings
1783
1784 The strcmp_PF() function is similar to strcmp() except that \e s2 is a far
1785 pointer to a string in program space.
1786
1787 \param s1 A pointer to the first string in SRAM
1788 \param s2 A far pointer to the second string in Flash
1789
1790 \returns The strcmp_PF() function returns an integer less than, equal to,
1791 or greater than zero if \e s1 is found, respectively, to be less than, to
1792 match, or be greater than \e s2. The contents of RAMPZ SFR are undefined
1793 when the function returns. */
1794extern int strcmp_PF(const char *s1, uint_farptr_t s2) __ATTR_PURE__;
1795
1796/** \ingroup avr_pgmspace
1797 \fn int strncmp_PF(const char *s1, uint_farptr_t s2, size_t n)
1798 \brief Compare two strings with limited length
1799
1800 The strncmp_PF() function is similar to strcmp_PF() except it only
1801 compares the first (at most) \e n characters of \e s1 and \e s2.
1802
1803 \param s1 A pointer to the first string in SRAM
1804 \param s2 A far pointer to the second string in Flash
1805 \param n The maximum number of bytes to compare
1806
1807 \returns The strncmp_PF() function returns an integer less than, equal
1808 to, or greater than zero if \e s1 (or the first \e n bytes thereof) is found,
1809 respectively, to be less than, to match, or be greater than \e s2. The
1810 contents of RAMPZ SFR are undefined when the function returns. */
1811extern int strncmp_PF(const char *s1, uint_farptr_t s2, size_t n) __ATTR_PURE__;
1812
1813/** \ingroup avr_pgmspace
1814 \fn int strcasecmp_PF(const char *s1, uint_farptr_t s2)
1815 \brief Compare two strings ignoring case
1816
1817 The strcasecmp_PF() function compares the two strings \e s1 and \e s2, ignoring
1818 the case of the characters.
1819
1820 \param s1 A pointer to the first string in SRAM
1821 \param s2 A far pointer to the second string in Flash
1822
1823 \returns The strcasecmp_PF() function returns an integer less than, equal
1824 to, or greater than zero if \e s1 is found, respectively, to be less than, to
1825 match, or be greater than \e s2. The contents of RAMPZ SFR are undefined
1826 when the function returns. */
1827extern int strcasecmp_PF(const char *s1, uint_farptr_t s2) __ATTR_PURE__;
1828
1829/** \ingroup avr_pgmspace
1830 \fn int strncasecmp_PF(const char *s1, uint_farptr_t s2, size_t n)
1831 \brief Compare two strings ignoring case
1832
1833 The strncasecmp_PF() function is similar to strcasecmp_PF(), except it
1834 only compares the first \e n characters of \e s1 and the string in flash is
1835 addressed using a far pointer.
1836
1837 \param s1 A pointer to a string in SRAM
1838 \param s2 A far pointer to a string in Flash
1839 \param n The maximum number of bytes to compare
1840
1841 \returns The strncasecmp_PF() function returns an integer less than, equal
1842 to, or greater than zero if \e s1 (or the first \e n bytes thereof) is found,
1843 respectively, to be less than, to match, or be greater than \e s2. The
1844 contents of RAMPZ SFR are undefined when the function returns. */
1845extern int strncasecmp_PF(const char *s1, uint_farptr_t s2, size_t n) __ATTR_PURE__;
1846
1847/** \ingroup avr_pgmspace
1848 \fn uint_farptr_t strchr_PF(uint_farptr_t s, int val)
1849 \brief Locate character in far program space string.
1850
1851 The strchr_PF() function locates the first occurrence of \p val
1852 (converted to a char) in the string pointed to by \p s in far program
1853 space. The terminating null character is considered to be part of
1854 the string.
1855
1856 The strchr_PF() function is similar to strchr() except that \p s is
1857 a far pointer to a string in program space that's \e not \e required to be
1858 located in the lower 64 KiB block like it is the case for strchr_P().
1859
1860 \returns The strchr_PF() function returns a far pointer to the matched
1861 character or \c 0 if the character is not found. */
1862extern uint_farptr_t strchr_PF(uint_farptr_t, int __val) __ATTR_CONST__;
1863
1864/** \ingroup avr_pgmspace
1865 \fn char *strstr_PF(const char *s1, uint_farptr_t s2)
1866 \brief Locate a substring.
1867
1868 The strstr_PF() function finds the first occurrence of the substring \c s2
1869 in the string \c s1. The terminating '\\0' characters are not
1870 compared.
1871 The strstr_PF() function is similar to strstr() except that \c s2 is a
1872 far pointer to a string in program space.
1873
1874 \returns The strstr_PF() function returns a pointer to the beginning of the
1875 substring, or NULL if the substring is not found.
1876 If \c s2 points to a string of zero length, the function returns \c s1. The
1877 contents of RAMPZ SFR are undefined when the function returns. */
1878extern char *strstr_PF(const char *s1, uint_farptr_t s2);
1879
1880/** \ingroup avr_pgmspace
1881 \fn size_t strlcpy_PF(char *dst, uint_farptr_t src, size_t siz)
1882 \brief Copy a string from progmem to RAM.
1883
1884 Copy src to string dst of size siz. At most siz-1 characters will be
1885 copied. Always NULL terminates (unless siz == 0).
1886
1887 \returns The strlcpy_PF() function returns strlen(src). If retval >= siz,
1888 truncation occurred. The contents of RAMPZ SFR are undefined when the
1889 function returns. */
1890extern size_t strlcpy_PF(char *dst, uint_farptr_t src, size_t siz);
1891
1892/** \ingroup avr_pgmspace
1893 \fn int memcmp_PF(const void *s1, uint_farptr_t s2, size_t len)
1894 \brief Compare memory areas
1895
1896 The memcmp_PF() function compares the first \p len bytes of the memory
1897 areas \p s1 and flash \p s2. The comparision is performed using unsigned
1898 char operations. It is an equivalent of memcmp_P() function, except
1899 that it is capable working on all FLASH including the exteded area
1900 above 64kB.
1901
1902 \returns The memcmp_PF() function returns an integer less than, equal
1903 to, or greater than zero if the first \p len bytes of \p s1 is found,
1904 respectively, to be less than, to match, or be greater than the first
1905 \p len bytes of \p s2. */
1906extern int memcmp_PF(const void *, uint_farptr_t, size_t) __ATTR_PURE__;
1907
1908#ifdef __DOXYGEN__
1909/** \ingroup avr_pgmspace
1910 \fn size_t strlen_P(const char *src)
1911
1912 The strlen_P() function is similar to strlen(), except that src is a
1913 pointer to a string in program space.
1914
1915 \returns The strlen_P() function returns the number of characters in src.
1916
1917 \note strlen_P() is implemented as an inline function in the avr/pgmspace.h
1918 header file, which will check if the length of the string is a constant
1919 and known at compile time. If it is not known at compile time, the macro
1920 will issue a call to __strlen_P() which will then calculate the length
1921 of the string as normal.
1922*/
1923static inline size_t strlen_P(const char * s);
1924#else /* !DOXYGEN */
1925
1926#ifdef __AVR_TINY__
1927#define __strlen_P strlen
1928extern size_t strlen (const char*);
1929#else
1930extern size_t __strlen_P(const char *) __ATTR_CONST__; /* internal helper function */
1931#endif
1932
1933static __ATTR_ALWAYS_INLINE__ size_t strlen_P(const char * s);
1934size_t strlen_P(const char *s)
1935{
1936 return __builtin_constant_p(__builtin_strlen(s))
1937 ? __builtin_strlen(s) : __strlen_P(s);
1938}
1939#endif /* DOXYGEN */
1940
1941#ifdef __cplusplus
1942} // extern "C"
1943#endif
1944
1945#if defined(__cplusplus) && defined(__pgm_read_template__)
1946
1947/* Caveat: When this file is found via -isystem <path>, then some older
1948 avr-g++ versions come up with
1949
1950 error: template with C linkage
1951
1952 because the target description did not define NO_IMPLICIT_EXTERN_C. */
1953
1954template<typename __T, size_t>
1955struct __pgm_read_impl
1956{
1957 // A default implementaton for T's with a size not in { 1, 2, 3, 4, 8 }.
1958 // While this works, the performance is absolute scrap because GCC does
1959 // not handle objects well that don't fit in a register (i.e. avr-gcc
1960 // has no respective machine_mode).
1961 __T operator() (const __T *__addr) const
1962 {
1963 __T __res;
1964 memcpy_P (&__res, __addr, sizeof(__T));
1965 return __res;
1966 }
1967};
1968
1969template<typename __T>
1970struct __pgm_read_impl<__T, 1>
1971{
1972 __T operator() (const __T *__addr) const
1973 {
1974 __T __res; __LPM__1 (__res, __addr); return __res;
1975 }
1976};
1977
1978template<typename __T>
1979struct __pgm_read_impl<__T, 2>
1980{
1981 __T operator() (const __T *__addr) const
1982 {
1983 __T __res; __LPM__2 (__res, __addr); return __res;
1984 }
1985};
1986
1987template<typename __T>
1988struct __pgm_read_impl<__T, 3>
1989{
1990 __T operator() (const __T *__addr) const
1991 {
1992 __T __res; __LPM__3 (__res, __addr); return __res;
1993 }
1994};
1995
1996template<typename __T>
1997struct __pgm_read_impl<__T, 4>
1998{
1999 __T operator() (const __T *__addr) const
2000 {
2001 __T __res; __LPM__4 (__res, __addr); return __res;
2002 }
2003};
2004
2005template<typename __T>
2006struct __pgm_read_impl<__T, 8>
2007{
2008 __T operator() (const __T *__addr) const
2009 {
2010 __T __res; __LPM__8 (__res, __addr); return __res;
2011 }
2012};
2013
2014template<typename __T>
2015__T pgm_read (const __T *__addr)
2016{
2017 return __pgm_read_impl<__T, sizeof(__T)>() (__addr);
2018}
2019
2020//////////////////////////////////////////////////////////
2021
2022template<typename __T, size_t>
2023struct __pgm_read_far_impl
2024{
2025 // A default implementaton for T's with a size not in { 1, 2, 3, 4, 8 }.
2026 // While this works, the performance is absolute scrap because GCC does
2027 // not handle objects well that don't fit in a register (i.e. avr-gcc
2028 // has no respective machine_mode).
2029 __T operator() (const __T *__addr) const
2030 {
2031 __T __res;
2032 memcpy_PF (&__res, __addr, sizeof(__T));
2033 return __res;
2034 }
2035};
2036
2037template<typename __T>
2038struct __pgm_read_far_impl<__T, 1>
2039{
2040 __T operator() (uint_farptr_t __addr) const
2041 {
2042 __T __res; __ELPM__1 (__res, __addr, __T); return __res;
2043 }
2044};
2045
2046template<typename __T>
2047struct __pgm_read_far_impl<__T, 2>
2048{
2049 __T operator() (uint_farptr_t __addr) const
2050 {
2051 __T __res; __ELPM__2 (__res, __addr, __T); return __res;
2052 }
2053};
2054
2055template<typename __T>
2056struct __pgm_read_far_impl<__T, 3>
2057{
2058 __T operator() (uint_farptr_t __addr) const
2059 {
2060 __T __res; __ELPM__3 (__res, __addr, __T); return __res;
2061 }
2062};
2063
2064template<typename __T>
2065struct __pgm_read_far_impl<__T, 4>
2066{
2067 __T operator() (uint_farptr_t __addr) const
2068 {
2069 __T __res; __ELPM__4 (__res, __addr, __T); return __res;
2070 }
2071};
2072
2073template<typename __T>
2074struct __pgm_read_far_impl<__T, 8>
2075{
2076 __T operator() (uint_farptr_t __addr) const
2077 {
2078 __T __res; __ELPM__8 (__res, __addr, __T); return __res;
2079 }
2080};
2081
2082template<typename __T>
2083__T pgm_read_far (uint_farptr_t __addr)
2084{
2085 return __pgm_read_far_impl<__T, sizeof(__T)>() (__addr);
2086}
2087
2088#endif /* C++ */
2089
2090#ifdef __DOXYGEN__
2091/** \ingroup avr_pgmspace
2092 \fn T pgm_read<T> (const T *addr)
2093
2094 Read an object of type \c T from program memory address \p addr and
2095 return it.
2096 This template is only available when macro \c __pgm_read_template__
2097 is defined. */
2098template<typename T>
2099T pgm_read<T> (const T *addr);
2100
2101/** \ingroup avr_pgmspace
2102 \fn T pgm_read_far<T> (uint_farptr_t addr)
2103
2104 Read an object of type \c T from program memory address \p addr and
2105 return it.
2106 This template is only available when macro \c __pgm_read_template__
2107 is defined. */
2108template<typename T>
2109T pgm_read_far<T> (uint_farptr_t addr);
2110#endif /* DOXYGEN */
2111
2112#endif /* __PGMSPACE_H_ */
uint32_t uint_farptr_t
Definition inttypes.h:83
unsigned int uint16_t
Definition stdint.h:93
unsigned long int uint32_t
Definition stdint.h:103
signed long long int int64_t
Definition stdint.h:110
signed int int16_t
Definition stdint.h:88
unsigned char uint8_t
Definition stdint.h:83
unsigned long long int uint64_t
Definition stdint.h:117
signed long int int32_t
Definition stdint.h:98
signed char int8_t
Definition stdint.h:78