[RFA:] gcc/doc/rtl.texi: Document NOTE_INSN_DELETED_LABEL

[Hans-Peter Nilsson <hans-peter dot nilsson at axis dot com>]

This had me puzzled for a while.  The CRIS port barfed because it
sanity-checks what was inside a LABEL_REF and it sometimes wasn't a
CODE_LABEL.  If you're puzzled too, grep for NOTE_INSN_DELETED_LABEL and
you'll be enlightened.  Or scared.  The name and the rtl dumps makes you
really think that the label is deleted.  Is it just me or isn't it
somewhat non-intuitive that the label is actually still there?  Besides,
there was no documentation for NOTE_INSN_DELETED_LABEL.

Passes make info.

Ok to commit?

	* doc/rtl.texi: Mention that besides as a CODE_LABEL, a label can
	sometimes be represented as a NOTE of type
	NOTE_INSN_DELETED_LABEL.
	(Insns): Document NOTE_INSN_DELETED_LABEL.

Index: rtl.texi
===================================================================
RCS file: /cvs/gcc/egcs/gcc/doc/rtl.texi,v
retrieving revision 1.17
diff -p -c -r1.17 rtl.texi
*** rtl.texi	2001/08/18 21:02:43	1.17
--- rtl.texi	2001/09/03 21:41:00
*************** outside the innermost loop containing th
*** 659,665 ****
  was found.
  
  In @code{code_label} expressions, it is 1 if the label may never be deleted.
! This is used for labels which are the target of non-local gotos.
  
  In an RTL dump, this flag is represented as @samp{/s}.
  
--- 659,667 ----
  was found.
  
  In @code{code_label} expressions, it is 1 if the label may never be deleted.
! This is used for labels which are the target of non-local gotos.  Such a
! label that would have been deleted is replaced with a @code{note} of type
! @code{NOTE_INSN_DELETED_LABEL}.
  
  In an RTL dump, this flag is represented as @samp{/s}.
  
*************** Usually that is the only mode for which 
*** 1080,1088 ****
  @findex label_ref
  @item (label_ref @var{label})
  Represents the value of an assembler label for code.  It contains one
! operand, an expression, which must be a @code{code_label} that appears
! in the instruction sequence to identify the place where the label
! should go.
  
  The reason for using a distinct expression type for code label
  references is so that jump optimization can distinguish them.
--- 1082,1090 ----
  @findex label_ref
  @item (label_ref @var{label})
  Represents the value of an assembler label for code.  It contains one
! operand, an expression, which must be a @code{code_label} or a @code{note}
! of type @code{NOTE_INSN_DELETED_LABEL} that appears in the instruction
! sequence to identify the place where the label should go.
  
  The reason for using a distinct expression type for code label
  references is so that jump optimization can distinguish them.
*************** When a @code{code_label} appears in an R
*** 2625,2630 ****
--- 2627,2635 ----
  appears within a @code{label_ref} which represents the address of
  the label, as a number.
  
+ Besides as a @code{code_label}, a label can also be represented as a
+ @code{note} of type @code{NOTE_INSN_DELETED_LABEL}.
+ 
  @findex LABEL_NUSES
  The field @code{LABEL_NUSES} is only defined once the jump optimization
  phase is completed and contains the number of times this label is
*************** must contain a null pointer):
*** 2667,2672 ****
--- 2672,2683 ----
  Such a note is completely ignorable.  Some passes of the compiler
  delete insns by altering them into notes of this kind.
  
+ @findex NOTE_INSN_DELETED_LABEL
+ @item NOTE_INSN_DELETED_LABEL
+ This marks what used to be a @code{code_label}, but was not used for other
+ purposes than taking its address and was transformed to mark that no
+ code jumps to it.
+ 
  @findex NOTE_INSN_BLOCK_BEG
  @findex NOTE_INSN_BLOCK_END
  @item NOTE_INSN_BLOCK_BEG
*************** of debugging information.
*** 2681,2687 ****
  @itemx NOTE_INSN_EH_REGION_END
  These types of notes indicate the position of the beginning and end of a
  level of scoping for exception handling.  @code{NOTE_BLOCK_NUMBER}
! identifies which @code{CODE_LABEL} is associated with the given region.
  
  @findex NOTE_INSN_LOOP_BEG
  @findex NOTE_INSN_LOOP_END
--- 2692,2699 ----
  @itemx NOTE_INSN_EH_REGION_END
  These types of notes indicate the position of the beginning and end of a
  level of scoping for exception handling.  @code{NOTE_BLOCK_NUMBER}
! identifies which @code{CODE_LABEL} or @code{note} of type
! @code{NOTE_INSN_DELETED_LABEL} is associated with the given region.
  
  @findex NOTE_INSN_LOOP_BEG
  @findex NOTE_INSN_LOOP_END
*************** last insns, respectively.
*** 2876,2882 ****
  
  @findex REG_LABEL
  @item REG_LABEL
! This insn uses @var{op}, a @code{code_label}, but is not a
  @code{jump_insn}, or it is a @code{jump_insn} that required the label to
  be held in a register.  The presence of this note allows jump
  optimization to be aware that @var{op} is, in fact, being used, and flow
--- 2888,2895 ----
  
  @findex REG_LABEL
  @item REG_LABEL
! This insn uses @var{op}, a @code{code_label} or a @code{note} of type
! @code{NOTE_INSN_DELETED_LABEL}, but is not a
  @code{jump_insn}, or it is a @code{jump_insn} that required the label to
  be held in a register.  The presence of this note allows jump
  optimization to be aware that @var{op} is, in fact, being used, and flow

brgds, H-P