User account creation filtered due to spam.

Bug 1078 - Problems with attributes documentation
Summary: Problems with attributes documentation
Status: RESOLVED FIXED
Alias: None
Product: gcc
Classification: Unclassified
Component: target (show other bugs)
Version: 2.97
: P3 normal
Target Milestone: ---
Assignee: Not yet assigned to anyone
URL:
Keywords: documentation
Depends on: 27543 27544
Blocks:
  Show dependency treegraph
 
Reported: 2000-12-16 15:36 UTC by Joseph S. Myers
Modified: 2016-04-16 23:28 UTC (History)
4 users (show)

See Also:
Host: i686-pc-linux-gnu
Target: i686-pc-linux-gnu
Build: i686-pc-linux-gnu
Known to work:
Known to fail:
Last reconfirmed: 2006-02-26 19:15:09


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Joseph S. Myers 2000-12-16 15:36:00 UTC
There are many problems with the documentation of attributes in
extend.texi:

1) The syntax of attributes on labels is undocumented, though it's
   mentioned in invoke.texi that attributes can be placed on labels.

2) The data attributes eightbit_data and tiny_data are listed under
   function attributes.

3) There is no documentation for the attributes "common" and
   "no_stack_limit".

4) There is no documentation for the C++ attributes "com_interface"
   and "init_priority" in extend.texi, though init_priority is
   mentioned in invoke.texi.

5) Several attributes have documented lists of targets for which they
   are implemented, but those lists are incomplete, not mentioning
   some implemented targets:

        Attribute       Machines not documented
        =========       =======================
        interrupt       ARC, C4X, V850, m68hc11
        dllimport       ARM/pe, MCore, i386 Windows NT
        dllexport       ARM/pe, MCore, i386 Windows NT
        stdcall         ns32k
        cdecl           ns32k
        naked           MCore
        interrupt_handler   SH, V850

6) Several machine-specific attributes are not documented:

        Attribute       Machine
        =========       =======
        overlaid        VMS on Alpha
        isr             ARM
        progmem         AVR
        assembler       C4X
        leaf_pretend    C4X
        OS_Task         H8/300
        monitor         H8/300
        syscall_linkage IA64
        sp_switch       SH
        trap_exit       SH
        sda             V850
        tda             V850
        zda             V850
        trap            m68hc11

Release:
2.97 20001216 (experimental)

Environment:
System: Linux decomino 2.2.18 #1 Thu Dec 14 19:30:45 UTC 2000 i686 unknown
Architecture: i686

	
host: i686-pc-linux-gnu
build: i686-pc-linux-gnu
target: i686-pc-linux-gnu
configured with: ../gcc-cvs/configure --prefix=/opt/gcc/snapshot --disable-shared --enable-threads=posix --with-system-zlib

How-To-Repeat:
Find undocumented attributes in the source code or alluded to in other
bits of documentation.
Comment 1 Joseph S. Myers 2000-12-16 15:36:00 UTC
Fix:
Document all attributes, using machine-specific knowledge where
necessary.
Comment 2 Alexandre Oliva 2001-06-12 19:08:33 UTC
State-Changed-From-To: open->analyzed
State-Changed-Why: Documented interrupt_handler, sp_switch and trap_exit.
Comment 3 Joseph S. Myers 2001-09-10 22:25:08 UTC
From: "Joseph S. Myers" <jsm28@cam.ac.uk>
To: <gcc-gnats@gcc.gnu.org>,  <gcc-bugs@gcc.gnu.org>
Cc:  
Subject: other/1078
Date: Mon, 10 Sep 2001 22:25:08 +0100 (BST)

 PR other/1078 lists problems with the documentation of various attributes.  
 The following is an update to the list there:
 
 init_priority is now documented.
 
 The SH attributes interrupt_handler, sp_switch and trap_exit are now
 documented.
 
 The ARM attribute interfacearm, not on the previous list, is undocumented.
 
 The stormy16 attribute interrupt is not documented.
 
 Could the ARC, ARM, AVR, C4X, H8/300, IA64, i386, m68hc11, MCore, ns32k,
 stormy16 and V850 maintainers update the documentation in extend.texi
 relating to their targets' attributes?
 
 -- 
 Joseph S. Myers
 jsm28@cam.ac.uk
Comment 4 Andrew Pinski 2006-05-11 02:16:39 UTC
PR 27544 is about a missing docs for an attribute for RS6000, altivec.
PR 27543 is about ms_struct attribute on rs6000/PowerPC as it just says x86 supports it which is no longer true.
Comment 5 Eric Weddington 2007-07-25 17:05:43 UTC
Patch to document AVR progmem attribute:
http://gcc.gnu.org/ml/gcc-patches/2007-07/msg01832.html
Comment 6 Eric Weddington 2007-09-04 03:37:09 UTC
(In reply to comment #5)
> Patch to document AVR progmem attribute:
> http://gcc.gnu.org/ml/gcc-patches/2007-07/msg01832.html
> 

Now committed:
http://gcc.gnu.org/ml/gcc-patches/2007-09/msg00159.html

This bug is fixed for the AVR target.
Comment 7 sandra 2015-12-22 04:44:13 UTC
Problems (1) and (2) have been corrected.  Documentation for "no_stack_limit" and "com_interface" is still missing, but "common" and "init_priority" are now documented.

Since the list of attributes and targets has changed greatly over the past 15 years I think the list of attributes missing documentation in the initial PR is not very useful any more....  better to scan the current code and fix problems immediately if possible rather than let the list sit for another 15 years.  :-)
Comment 8 sandra 2016-01-02 03:46:04 UTC
Author: sandra
Date: Sat Jan  2 03:45:32 2016
New Revision: 232034

URL: https://gcc.gnu.org/viewcvs?rev=232034&root=gcc&view=rev
Log:
2016-01-01  Sandra Loosemore  <sandra@codesourcery.com>

	PR 1078

	gcc/
	* extend.texi (Common Function Attributes) <no_stack_limit>: New.
	* invoke.texi (Code Gen Options) <-fno-stack-limit>: Add pointer
	to corresponding attribute.

Modified:
    trunk/gcc/ChangeLog
    trunk/gcc/doc/extend.texi
    trunk/gcc/doc/invoke.texi
Comment 9 sandra 2016-01-02 03:56:35 UTC
"no_stack_limit" is documented now.

I've proposed deleting "com_interface", as it's been obsolete since 2001:
https://gcc.gnu.org/ml/gcc-patches/2016-01/msg00011.html

It looks like the only target-inspecific attributes missing documentation are the transactional memory attributes.  I filed a separate issue (PR 69115) for that since it requires clarification from the experts on that feature.

I have not reviewed the state of the target-specific attribute documentation yet.
Comment 10 sandra 2016-01-05 18:04:32 UTC
Author: sandra
Date: Tue Jan  5 18:04:01 2016
New Revision: 232081

URL: https://gcc.gnu.org/viewcvs?rev=232081&root=gcc&view=rev
Log:
2016-01-05  Sandra Loosemore <sandra@codesourcery.com>

	PR 1078
	gcc/
	* doc/extend.texi (MicroBlaze Function Attributes): Document
	interrupt_handler and fast_interrupt attributes.

Modified:
    trunk/gcc/ChangeLog
    trunk/gcc/doc/extend.texi
Comment 11 sandra 2016-01-05 19:46:14 UTC
Author: sandra
Date: Tue Jan  5 19:45:43 2016
New Revision: 232085

URL: https://gcc.gnu.org/viewcvs?rev=232085&root=gcc&view=rev
Log:
2016-01-05  Sandra Loosemore <sandra@codesourcery.com>

	PR 1078
	gcc/
	* doc/extend.texi (V850 Function Attributes): New section.
	(V850 Variable Attributes): New section.

Modified:
    trunk/gcc/ChangeLog
    trunk/gcc/doc/extend.texi
Comment 12 sandra 2016-01-05 20:52:20 UTC
Author: sandra
Date: Tue Jan  5 20:51:48 2016
New Revision: 232092

URL: https://gcc.gnu.org/viewcvs?rev=232092&root=gcc&view=rev
Log:
2016-01-05  Sandra Loosemore <sandra@codesourcery.com>

	PR 1078
	gcc/
	* doc/extend.texi (RL78 Variable Attributes): New section.

Modified:
    trunk/gcc/ChangeLog
    trunk/gcc/doc/extend.texi
Comment 13 sandra 2016-01-07 18:02:57 UTC
Author: sandra
Date: Thu Jan  7 18:02:25 2016
New Revision: 232136

URL: https://gcc.gnu.org/viewcvs?rev=232136&root=gcc&view=rev
Log:
2016-01-07  Sandra Loosemore <sandra@codesourcery.com>

	PR 1078
	gcc/
	* doc/extend.texi (Nvidia PDX Function Attributes): New section.

Modified:
    trunk/gcc/ChangeLog
    trunk/gcc/doc/extend.texi
Comment 14 sandra 2016-01-07 18:25:10 UTC
I've finished going through the target-specific attributes.  I filed new target-specific issues for things that need attention from target maintainers:

PR 69151: h8300 "OS_Task", "monitor"
PR 69150: mcore "dllimport", "dllexport"
PR 69142: s390 "s390_vector_bool"
PR 69179: darwin "apple_kext_compatibility", "weak_import"

Additionally, the VMS "common_object" and Solaris "init" and "fini" attributes seem to exist only to provide an implementation hook for compatibility pragmas on those targets and probably aren't intended to be used directly.  So I have left those undocumented for now.

So, I think the only thing remaining to be done for this issue is to decide what to do about "com_interface".
Comment 15 sandra 2016-04-16 23:23:24 UTC
Author: sandra
Date: Sat Apr 16 23:22:52 2016
New Revision: 235066

URL: https://gcc.gnu.org/viewcvs?rev=235066&root=gcc&view=rev
Log:
2016-04-16  Sandra Loosemore  <sandra@codesourcery.com>

	PR target/1078

	gcc/cp/
	* tree.c (cxx_attribute_table): Remove "com_interface" entry.
	(handle_com_interface_attribute): Delete.

Modified:
    trunk/gcc/cp/ChangeLog
    trunk/gcc/cp/tree.c
Comment 16 sandra 2016-04-16 23:28:45 UTC
The com_interface attribute has been deleted on trunk now.  Per comment #14, I think that was the last thing to be done for this issue, so I'm marking it fixed now.