diff options
Diffstat (limited to 'cpukit/score/cpu/avr/avr/pgmspace.h')
| -rw-r--r-- | cpukit/score/cpu/avr/avr/pgmspace.h | 192 |
1 files changed, 99 insertions, 93 deletions
diff --git a/cpukit/score/cpu/avr/avr/pgmspace.h b/cpukit/score/cpu/avr/avr/pgmspace.h index 4036f68275..42010168b1 100644 --- a/cpukit/score/cpu/avr/avr/pgmspace.h +++ b/cpukit/score/cpu/avr/avr/pgmspace.h @@ -1,80 +1,85 @@ -/* Copyright (c) 2002 - 2007 Marek Michalkiewicz - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of the copyright holders nor the names of - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE - LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. */ - +/** + * @file pgmspace.h + * + * @brief Definitions for ATmega640 + * + * The functions in this module provide interfaces for a program to access + * data stored in program space (flash memory) of the device. In order to + * use these functions, the target device must support either the \c LPM or + * \c ELPM instructions. + * + * @note These functions are an attempt to provide some compatibility with + * header files that come with IAR C, to make porting applications between + * different compilers easier. This is not 100% compatibility though (GCC + * does not have full support for multiple address spaces yet). + * + * @note If you are working with strings which are completely based in ram, + * use the standard string functions described in \ref avr_string. + * + * \note If possible, put your constant tables in the lower 64 KB and use + * pgm_read_byte_near() or pgm_read_word_near() instead of + * pgm_read_byte_far() or pgm_read_word_far() since it is more efficient that + * way, and you can still use the upper 64K for executable code. + * All functions that are suffixed with a \c _P \e require their + * arguments to be in the lower 64 KB of the flash ROM, as they do + * not use ELPM instructions. This is normally not a big concern as + * the linker setup arranges any program space constants declared + * using the macros from this header file so they are placed right after + * the interrupt vectors, and in front of any executable code. However, + * it can become a problem if there are too many of these constants, or + * for bootloaders on devices with more than 64 KB of ROM. + * <em>All these functions will not work in that situation.</em> + * + * Contributors: + * Created by Marek Michalkiewicz <marekm@linux.org.pl> + * Eric B. Weddington <eric@ecentral.com> + * Wolfgang Haidinger <wh@vmars.tuwien.ac.at> (pgm_read_dword()) + * Ivanov Anton <anton@arc.com.ru> (pgm_read_float()) + */ /* - pgmspace.h - - Contributors: - Created by Marek Michalkiewicz <marekm@linux.org.pl> - Eric B. Weddington <eric@ecentral.com> - Wolfgang Haidinger <wh@vmars.tuwien.ac.at> (pgm_read_dword()) - Ivanov Anton <anton@arc.com.ru> (pgm_read_float()) + * Copyright (c) 2002 - 2007 Marek Michalkiewicz + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * * Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * * Neither the name of the copyright holders nor the names of + * contributors may be used to endorse or promote products derived + * from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ -/** \file */ -/** \defgroup avr_pgmspace <avr/pgmspace.h>: Program Space Utilities - \code - #include <avr/io.h> - #include <avr/pgmspace.h> - \endcode - - The functions in this module provide interfaces for a program to access - data stored in program space (flash memory) of the device. In order to - use these functions, the target device must support either the \c LPM or - \c ELPM instructions. - - \note These functions are an attempt to provide some compatibility with - header files that come with IAR C, to make porting applications between - different compilers easier. This is not 100% compatibility though (GCC - does not have full support for multiple address spaces yet). - - \note If you are working with strings which are completely based in ram, - use the standard string functions described in \ref avr_string. - - \note If possible, put your constant tables in the lower 64 KB and use - pgm_read_byte_near() or pgm_read_word_near() instead of - pgm_read_byte_far() or pgm_read_word_far() since it is more efficient that - way, and you can still use the upper 64K for executable code. - All functions that are suffixed with a \c _P \e require their - arguments to be in the lower 64 KB of the flash ROM, as they do - not use ELPM instructions. This is normally not a big concern as - the linker setup arranges any program space constants declared - using the macros from this header file so they are placed right after - the interrupt vectors, and in front of any executable code. However, - it can become a problem if there are too many of these constants, or - for bootloaders on devices with more than 64 KB of ROM. - <em>All these functions will not work in that situation.</em> -*/ - #ifndef __PGMSPACE_H_ #define __PGMSPACE_H_ 1 +/** + * @defgroup avr_pgmspace Program Space Utilities + * + * @ingroup avr + * + */ +/**@{**/ + #define __need_size_t #include <inttypes.h> #include <stddef.h> @@ -402,7 +407,7 @@ typedef uint64_t prog_uint64_t PROGMEM; /** \ingroup avr_pgmspace \def pgm_read_byte_near(address_short) - Read a byte from the program space with a 16-bit (near) address. + Read a byte from the program space with a 16-bit (near) address. \note The address is a byte address. The address is in the program space. */ @@ -410,16 +415,16 @@ typedef uint64_t prog_uint64_t PROGMEM; /** \ingroup avr_pgmspace \def pgm_read_word_near(address_short) - Read a word from the program space with a 16-bit (near) address. - \note The address is a byte address. + Read a word from the program space with a 16-bit (near) address. + \note The address is a byte address. The address is in the program space. */ #define pgm_read_word_near(address_short) __LPM_word((uint16_t)(address_short)) /** \ingroup avr_pgmspace \def pgm_read_dword_near(address_short) - Read a double word from the program space with a 16-bit (near) address. - \note The address is a byte address. + Read a double word from the program space with a 16-bit (near) address. + \note The address is a byte address. The address is in the program space. */ #define pgm_read_dword_near(address_short) \ @@ -427,8 +432,8 @@ typedef uint64_t prog_uint64_t PROGMEM; /** \ingroup avr_pgmspace \def pgm_read_float_near(address_short) - Read a float from the program space with a 16-bit (near) address. - \note The address is a byte address. + Read a float from the program space with a 16-bit (near) address. + \note The address is a byte address. The address is in the program space. */ #define pgm_read_float_near(address_short) \ @@ -718,10 +723,10 @@ typedef uint64_t prog_uint64_t PROGMEM; __result; \ })) -/* -Check for architectures that implement RAMPD (avrxmega3, avrxmega5, +/* +Check for architectures that implement RAMPD (avrxmega3, avrxmega5, avrxmega7) as they need to save/restore RAMPZ for ELPM macros so it does -not interfere with data accesses. +not interfere with data accesses. */ #if defined (__AVR_HAVE_RAMPD__) @@ -753,16 +758,16 @@ not interfere with data accesses. /** \ingroup avr_pgmspace \def pgm_read_byte_far(address_long) - Read a byte from the program space with a 32-bit (far) address. + Read a byte from the program space with a 32-bit (far) address. - \note The address is a byte address. + \note The address is a byte address. The address is in the program space. */ #define pgm_read_byte_far(address_long) __ELPM((uint32_t)(address_long)) /** \ingroup avr_pgmspace \def pgm_read_word_far(address_long) - Read a word from the program space with a 32-bit (far) address. + Read a word from the program space with a 32-bit (far) address. \note The address is a byte address. The address is in the program space. */ @@ -771,7 +776,7 @@ not interfere with data accesses. /** \ingroup avr_pgmspace \def pgm_read_dword_far(address_long) - Read a double word from the program space with a 32-bit (far) address. + Read a double word from the program space with a 32-bit (far) address. \note The address is a byte address. The address is in the program space. */ @@ -780,7 +785,7 @@ not interfere with data accesses. /** \ingroup avr_pgmspace \def pgm_read_float_far(address_long) - Read a float from the program space with a 32-bit (far) address. + Read a float from the program space with a 32-bit (far) address. \note The address is a byte address. The address is in the program space. */ @@ -791,36 +796,36 @@ not interfere with data accesses. /** \ingroup avr_pgmspace \def pgm_read_byte(address_short) - Read a byte from the program space with a 16-bit (near) address. + Read a byte from the program space with a 16-bit (near) address. - \note The address is a byte address. + \note The address is a byte address. The address is in the program space. */ #define pgm_read_byte(address_short) pgm_read_byte_near(address_short) /** \ingroup avr_pgmspace \def pgm_read_word(address_short) - Read a word from the program space with a 16-bit (near) address. + Read a word from the program space with a 16-bit (near) address. - \note The address is a byte address. + \note The address is a byte address. The address is in the program space. */ #define pgm_read_word(address_short) pgm_read_word_near(address_short) /** \ingroup avr_pgmspace \def pgm_read_dword(address_short) - Read a double word from the program space with a 16-bit (near) address. + Read a double word from the program space with a 16-bit (near) address. - \note The address is a byte address. + \note The address is a byte address. The address is in the program space. */ #define pgm_read_dword(address_short) pgm_read_dword_near(address_short) /** \ingroup avr_pgmspace \def pgm_read_float(address_short) - Read a float from the program space with a 16-bit (near) address. + Read a float from the program space with a 16-bit (near) address. - \note The address is a byte address. + \note The address is a byte address. The address is in the program space. */ #define pgm_read_float(address_short) pgm_read_float_near(address_short) @@ -878,4 +883,5 @@ extern char *strtok_rP(char *__s, PGM_P __delim, char **__last); } #endif +/** @} */ #endif /* __PGMSPACE_H_ */ |