From patchwork Mon Jan 23 13:35:17 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Georg-Johann Lay X-Patchwork-Id: 137357 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) by ozlabs.org (Postfix) with SMTP id 97BEB1007D1 for ; Tue, 24 Jan 2012 00:36:01 +1100 (EST) Comment: DKIM? See http://www.dkim.org DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed; d=gcc.gnu.org; s=default; x=1327930563; h=Comment: DomainKey-Signature:Received:Received:Received:Received: Message-ID:Date:From:User-Agent:MIME-Version:To:CC:Subject: Content-Type:Mailing-List:Precedence:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:Sender:Delivered-To; bh=ukJTZ9X Q6ADQydl6XBEZjhZ7zFQ=; b=yRG5+7VG6TjUK+nQaWSd+tkEbwLzAHcLorUkXhI PL5Qwo3tyFkUQdBx91HcSGftDk1okaVlpg+xhEeuMX91otlfLHR486wcufg3PIE2 n0QxAJ7D8VwECZMRRvLgo8P9u13SHTxvD0nFEoSA7UFYPQkr9I+f53N3BrgVzXIN 7vEY= Comment: DomainKeys? See http://antispam.yahoo.com/domainkeys DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws; s=default; d=gcc.gnu.org; h=Received:Received:X-SWARE-Spam-Status:X-Spam-Check-By:Received:X-RZG-AUTH:X-RZG-CLASS-ID:Received:Message-ID:Date:From:User-Agent:MIME-Version:To:CC:Subject:Content-Type:X-IsSubscribed:Mailing-List:Precedence:List-Id:List-Unsubscribe:List-Archive:List-Post:List-Help:Sender:Delivered-To; b=XjkeG99aCbEhR0XVs8Uv/yMCHsLWoue2IKOwwlDrJ20NmVPBRd0Q7mRmOl5/Ji JPsSbSCq4oUvPRCHjFOo5zJik9yx4s/jbEY3DnUSJ6vHohiStRz8qUcUFTZT60H+ I9yA8ALw0PTFWlHr6w9Qla04DDMaAr0DsThXz3VCD80L4=; Received: (qmail 21352 invoked by alias); 23 Jan 2012 13:35:56 -0000 Received: (qmail 21129 invoked by uid 22791); 23 Jan 2012 13:35:54 -0000 X-SWARE-Spam-Status: No, hits=-1.5 required=5.0 tests=AWL, BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, RCVD_IN_DNSWL_NONE, TW_GM, TW_PG X-Spam-Check-By: sourceware.org Received: from mo-p00-ob.rzone.de (HELO mo-p00-ob.rzone.de) (81.169.146.160) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Mon, 23 Jan 2012 13:35:38 +0000 X-RZG-AUTH: :LXoWVUeid/7A29J/hMvvT2k715jHQaJercGObUOFkj18odoYNahU4Q== X-RZG-CLASS-ID: mo00 Received: from [192.168.0.22] (business-188-111-022-002.static.arcor-ip.net [188.111.22.2]) by smtp.strato.de (cohen mo39) (RZmta 27.5 AUTH) with ESMTPA id q06eb4o0NCTcmD ; Mon, 23 Jan 2012 14:35:19 +0100 (MET) Message-ID: <4F1D6215.3000404@gjlay.de> Date: Mon, 23 Jan 2012 14:35:17 +0100 From: Georg-Johann Lay User-Agent: Thunderbird 2.0.0.24 (X11/20100302) MIME-Version: 1.0 To: gcc-patches@gcc.gnu.org CC: Eric Weddington , Denis Chertykov Subject: [Patch,AVR,doc]: Fix some typos, add example. X-IsSubscribed: yes Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Besides fixing some typos, this patch adds an example that shows how to access code located with attribute progmem. The example in "AVR named address spaces" is moved up and the note on offset limitation is removed. Ok to apply? Johann PR target/49868 * doc/extend.texi (AVR Named Address Spaces): Move sample code up. Remove note on size/offset limitation. (AVR Variable Attributes): Add example how to read data located with progmem. Refer to named address spaces. Index: doc/extend.texi =================================================================== --- doc/extend.texi (revision 183341) +++ doc/extend.texi (working copy) @@ -1237,9 +1237,10 @@ in order to put read-only data into the data by means of the special instructions @code{LPM} or @code{ELPM} needed to read from flash. -Per default, any data including read-only data is located in RAM so -that address spaces are needed to locate read-only data in flash memory -@emph{and} to generate the right instructions to access the data +Per default, any data including read-only data is located in RAM +(the genric address space) so that non-generic address spaces are +needed to locate read-only data in flash memory +@emph{and} to generate the right instructions to access this data without using (inline) assembler code. @table @code @@ -1265,9 +1266,9 @@ address space @code{__pgm@var{N}}. The compiler will set the @code{RAMPZ} segment register approptiately before reading data by means of the @code{ELPM} instruction. -On devices with less 64kiB flash segments as indicated by the address +On devices with less 64@tie{}kiB flash segments as indicated by the address space, the compiler will cut down the segment number to a number the -device actually supports. Counting starts at @code{0} +device actually supports. Counting starts at@tie{}@code{0} for space @code{__pgm}. For example, if you access address space @code{__pgm3} on an ATmega128 device with two 64@tie{}kiB flash segments, the compiler will generate a read from @code{__pgm1}, i.e.@: it @@ -1284,6 +1285,31 @@ with @code{RAMPZ} set according to the h Objects in this address space will be located in @code{.progmem.data}. @end table +@b{Example} + +@example +char my_read (const __pgm char ** p) +@{ + /* p is a pointer to RAM that points to a pointer to flash. + The first indirection of p will read that flash pointer + from RAM and the second indirection reads a char from this + flash address. */ + + return **p; +@} + +/* Locate array[] in flash memory */ +const __pgm int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @}; + +int i = 1; + +int main (void) +@{ + /* Return 17 by reading from flash memory */ + return array[array[i]]; +@} +@end example + For each named address space supported by avr-gcc there is an equally named but uppercase built-in macro defined. The purpose is to facilitate testing if respective address space @@ -1311,8 +1337,9 @@ int read_i (void) Notice that attribute @ref{AVR Variable Attributes,@code{progmem}} locates data in flash but -accesses to these data will be to generic address space, i.e.@: RAM, -so that you need special access functions like @code{pgm_read_byte} +accesses to these data will read from generic address space, i.e.@: +from RAM, +so that you need special accessors like @code{pgm_read_byte} from @w{@uref{http://nongnu.org/avr-libc/user-manual,avr-libc}}. @b{Limitations and caveats} @@ -1331,10 +1358,10 @@ you will have to arrange your linker skr @code{.progmem@var{N}.data} sections according to your needs. @item -Any data or pointers to the AVR address spaces spaces must -also be qualified as @code{const}, i.e.@: as read-only data. +Any data or pointers to the non-generic address spaces must +be qualified as @code{const}, i.e.@: as read-only data. This still applies if the data in one of these address -spaces like software version number or lookup tables are intended to +spaces like software version number or calibration lookup table are intended to be changed after load time by, say, a boot loader. In this case the right qualification is @code{const} @code{volatile} so that the compiler must not optimize away known values or insert them @@ -1349,52 +1376,12 @@ extern const __pgmx char foo; const __pgmx void *pfoo = &foo; @end example The code will throw an assembler warning and the high byte of -@code{pfoo} will be initialized with @code{0}, i.e.@: the +@code{pfoo} will be initialized with@tie{}@code{0}, i.e.@: the initialization will be as if @code{foo} was located in the first 64@tie{}KiB chunk of flash. -@item -Address arithmetic for the @code{__pgmx} address space is carried out -as 16-bit signed integer arithmetic. This means that in the following -code array positions with offsets @code{idx}@tie{}>@tie{}8191 are -inaccessible. - -@example -extern const __pgmx long lookup[]; - -long read_lookup (unsigned idx) -@{ - return lookup[idx]; -@} -@end example - @end itemize -@b{Example} - -@example -char my_read (const __pgm ** p) -@{ - /* p is a pointer to RAM that points to a pointer to flash. - The first indirection of p will read that flash pointer - from RAM and the second indirection reads a char from this - flash address. */ - - return **p; -@} - -/* Locate array[] in flash memory */ -const __pgm int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @}; - -int i = 1; - -int main (void) -@{ - /* Return 17 by reading from flash memory */ - return array[array[i]]; -@} -@end example - @subsection M32C Named Address Spaces @cindex @code{__far} M32C Named Address Spaces @@ -4752,13 +4739,32 @@ data in the non-volatile program memory attribute accomplishes this by putting respective variables into a section whose name starts with @code{.progmem}. -This attrubute wirks similar to the @code{section} attribute +This attrubute works similar to the @code{section} attribute but adds additional checking. Notice that just like the @code{section} attribute, @code{progmem} affects the location of the data but not how this data is accessed. +In order to read data located with the @code{progmem} attribute +(inline) assembler must be used. +@example +/* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual,avr-libc}} */ +#include + +/* Locate var in flash memory */ +const int var[2] PROGMEM = @{ 1, 2 @}; + +int read_var (int i) +@{ + /* Access var[] by accessor macro from avr/pgmspace.h */ + return (int) pgm_read_word (& var[i]); +@} +@end example + AVR is a Harvard architecture processor and data and read-only data normally resides in the data memory (RAM). + +See also the @ref{AVR Named Address Spaces} section for +an alternate way to locate and access data in flash memory. @end table @subsection Blackfin Variable Attributes