Re: [Patch,wwwdocs,AVR]: AVR release notes

[Georg-Johann Lay <avr@gjlay.de>]

[-- Attachment #1: Type: text/plain, Size: 3622 bytes --]

Gerald Pfeifer wrote:
> On Fri, 20 Jan 2012, Georg-Johann Lay wrote:
>> Adding AVR-specific release notes to wwwdocs/htdocs/gcc-4.7/changes.html
> 
> Index: changes.html
> ===================================================================
> +    <li>The AVR port's libgcc has been improved and its multilib structure
> +      has been enhanced.  As a result, all objects contributing to an
> +      application must either be compiled with GCC versions up to 4.6.x or
> +      with GCC versions &ge;&nbsp;4.7.</li>
> 
> How about "...compiled with older versions of GCC, up to GCC 4.6.x,
> or GCC 4.7.0 and later" ?

The "compiled with" might be confusing, for example if someone uses a library
generated with 4.6 and compiles his application with 4.7. He does not compile
the library, but yet he might run into problems because the code assumes a
specific layout of libgcc. Therefore I used the "all objects" wording. It's bit
more technical, but I hoped the reduce misunderstandings.

> And I'd omit the &nbsp; just &ge;4.7.0 should work?
> 
> +    <li>Support has beed added for instrinsic named address spaces
> 
> "Support for...has been added" (also typo: beed -> been)
> 
> +    <code>__pgm</code>, <code>__pgm1</code>,&nbsp;&hellip;, <code>__pgm5</code>
> 
> How about omitting &nbsp; here?
> 
> +    and <code>__pgmx</code>.  These address spaces locate read-only data in
> +    flash memory and allow reading from flash memory by means of vanilla
> +    C&nbsp;instructions, i.e. without the need of (inline) assembler code.</li>
> 
> What's a C instruction?  C builtins?

Is "C code" better? Or C-code? Without the extension, inline assembler must be
used to get correct code, using C like a = b or pstruct->component will yield
wrong code without the extensions if b or *pstruct is located in flash.

> +    <li>Support for AVR-specific built-in functions has beed added.</li>
> 
> Which ones?

Must they all be named explicitly? Or is it ok to link to onlinedocs?
I'd prefer a link to the explanation in onlinedocs but I am unsure how stable
the links are as docs evolve over time/versions.

> +    <li>New command-line options <code>-maccumulate-args</code>,
> +      <code>-mbranch-cost=<i>cost</i></code> and <code>-mstrict-X</code>
> +      were added to allow better fine-tuning of code optimization.</li>
> 
> Should X be put under <i>...</i> here, to?

No, the X refers to X-register and must be literally, nothing else than
uppercase X is permitted.

> +    <li>Many optimizations to:
> +      <ul>
> +	<li>64-bit integer arithmetic</li>
> +	<li>Widening multiplication</li>
> +	<li>Integer divide-by-constant</li>
> 
> "division by a constant"
> 
> + <li>Generic built-in functions + like <code>__builtin_ffs*</code>, 
> <code>__builtin_clz*</code>,&nbsp;etc.</li>
> 
> I don't think we need &nbsp; here.  Breaking the lines here is something
> a web browser should avoid, but it is not verboten, technically.

Tried to get typesetting all right and avoid Hurenkinder, and I really don't
know if browsers add penalties like TeX does. I frequently see browsers offend
typesetting rules if there is no nanny.
What does "need no &nbsp;" mean? Nothing at ",etc." all or blank ", etc."?

> 
> +	<li>Merging of data in <code>.progmem</code></li>
> 
> What is ".progmen"?  Perhaps paraphrase this briefly?

Not easy without getting into too much technical details...
Maybe Eric can help. He is definitely better in English than I am.

> The update is fine assuming you look into my suggestions.

Attached an updated patch as there were many changes and so that Eric and Denis
can easier catch up.

Johann


[-- Attachment #2: www-changes-avr.diff --]
[-- Type: text/x-patch, Size: 2844 bytes --]

Index: changes.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/gcc-4.7/changes.html,v
retrieving revision 1.73
diff -u -r1.73 changes.html
--- changes.html	12 Jan 2012 19:35:29 -0000	1.73
+++ changes.html	30 Jan 2012 13:42:13 -0000
@@ -45,6 +45,11 @@
     <code>-compat-bsd</code> compiler option is not recognized any
     longer.</li>
 
+    <li>The AVR port's libgcc has been improved and its multilib structure
+      has been enhanced.  As a result, all objects contributing to an
+      application must either be compiled with GCC versions up to 4.6.x or
+      with GCC versions 4.7.0 or later.</li>
+      
     <li>The ARM port's <code>-mwords-little-endian</code> option has
     been deprecated.  It will be removed in a future release.</li>
 
@@ -530,6 +535,44 @@
 
 <h2 id="targets">New Targets and Target Specific Improvements</h2>
 
+<h3 id="avr">AVR</h3>
+  <ul>
+    <li>Support for the
+      <a href="http://gcc.gnu.org/onlinedocs/gcc/Named-Address-Spaces.html">named address spaces</a>
+      <code>__flash</code>, <code>__flash1</code>,&hellip;,
+      <code>__flash5</code> and <code>__memx</code> has beed added.
+      These address spaces locate read-only data in
+      flash memory and allow reading from flash memory by means of ordinary
+      C code, i.e. without the need of (inline) assembler code.</li>
+    <li>Support for AVR-specific <a href="http://gcc.gnu.org/onlinedocs/gcc/AVR-Built_002din-Functions.html">built-in functions</a>
+      has beed added.</li>
+    <li>Support has beed added for the built-in, 24-bit, signed and unsigned
+      integer types <code>__int24</code> and <code>__uint24</code>.</li>
+    <li>New command-line options <code>-maccumulate-args</code>,
+      <code>-mbranch-cost=<i>cost</i></code> and <code>-mstrict-X</code>
+      were added to allow better fine-tuning of code optimization.</li>
+    <li>Many optimizations to:
+      <ul>
+	<li>64-bit integer arithmetic</li>
+	<li>Widening multiplication</li>
+	<li>Integer division by a constant</li>
+	<li>Generic built-in functions like
+	  <code>__builtin_ffs*</code>, <code>__builtin_clz*</code>, etc.</li>
+	<li>If-else decision trees generated by <code>switch</code> instructions</li>
+	<li>Merging of data located in flash memory</li>
+	<li>New libgcc variants for devices with 8-bit wide stack pointer</li>
+	<li>&hellip;</li>
+      </ul>
+    <li>Better documentation:
+      <ul>
+	<li>Handling of <code>EIND</code> and indirect jumps on devices with
+	  more than 128&nbsp;KiB of program memory.</li>
+	<li>Function attributes <code>OS_main</code> and <code>OS_task</code>.</li>
+	<li>AVR-specific built-in macros.</li>
+      </ul>
+    </li>
+  </ul>
+
 <h3 id="arm">ARM</h3>
   <ul>
     <li>GCC now supports the Cortex-A7 processor implementing the