+file. This calls DF_DUMP_START, to print the information that is not
+basic block specific, and then calls DF_DUMP_TOP and DF_DUMP_BOTTOM
+for each block to print the basic specific information. These parts
+can all be called separately as part of a larger dump function.
+
+
+DF_FINISH_PASS causes df_remove_problem to be called on all of the
+optional problems. It also causes any insns whose scanning has been
+deferred to be rescanned as well as clears all of the changeable flags.
+Setting the pass manager TODO_df_finish flag causes this function to
+be run. However, the pass manager will call df_finish_pass AFTER the
+pass dumping has been done, so if you want to see the results of the
+optional problems in the pass dumps, use the TODO flag rather than
+calling the function yourself.
+
+INCREMENTAL SCANNING
+
+There are four ways of doing the incremental scanning:
+
+1) Immediate rescanning - Calls to df_insn_rescan, df_notes_rescan,
+ df_bb_delete, df_insn_change_bb have been added to most of
+ the low level service functions that maintain the cfg and change
+ rtl. Calling and of these routines many cause some number of insns
+ to be rescanned.
+
+ For most modern rtl passes, this is certainly the easiest way to
+ manage rescanning the insns. This technique also has the advantage
+ that the scanning information is always correct and can be relied
+ upon even after changes have been made to the instructions. This
+ technique is contra indicated in several cases:
+
+ a) If def-use chains OR use-def chains (but not both) are built,
+ using this is SIMPLY WRONG. The problem is that when a ref is
+ deleted that is the target of an edge, there is not enough
+ information to efficiently find the source of the edge and
+ delete the edge. This leaves a dangling reference that may
+ cause problems.
+
+ b) If def-use chains AND use-def chains are built, this may
+ produce unexpected results. The problem is that the incremental
+ scanning of an insn does not know how to repair the chains that
+ point into an insn when the insn changes. So the incremental
+ scanning just deletes the chains that enter and exit the insn
+ being changed. The dangling reference issue in (a) is not a
+ problem here, but if the pass is depending on the chains being
+ maintained after insns have been modified, this technique will
+ not do the correct thing.
+
+ c) If the pass modifies insns several times, this incremental
+ updating may be expensive.
+
+ d) If the pass modifies all of the insns, as does register
+ allocation, it is simply better to rescan the entire function.
+
+2) Deferred rescanning - Calls to df_insn_rescan, df_notes_rescan, and
+ df_insn_delete do not immediately change the insn but instead make
+ a note that the insn needs to be rescanned. The next call to
+ df_analyze, df_finish_pass, or df_process_deferred_rescans will
+ cause all of the pending rescans to be processed.
+
+ This is the technique of choice if either 1a, 1b, or 1c are issues
+ in the pass. In the case of 1a or 1b, a call to df_finish_pass
+ (either manually or via TODO_df_finish) should be made before the
+ next call to df_analyze or df_process_deferred_rescans.
+
+ This mode is also used by a few passes that still rely on note_uses,
+ note_stores and for_each_rtx instead of using the DF data. This
+ can be said to fall under case 1c.
+
+ To enable this mode, call df_set_flags (DF_DEFER_INSN_RESCAN).
+ (This mode can be cleared by calling df_clear_flags
+ (DF_DEFER_INSN_RESCAN) but this does not cause the deferred insns to
+ be rescanned.
+
+3) Total rescanning - In this mode the rescanning is disabled.
+ Only when insns are deleted is the df information associated with
+ it also deleted. At the end of the pass, a call must be made to
+ df_insn_rescan_all. This method is used by the register allocator
+ since it generally changes each insn multiple times (once for each ref)
+ and does not need to make use of the updated scanning information.
+
+4) Do it yourself - In this mechanism, the pass updates the insns
+ itself using the low level df primitives. Currently no pass does
+ this, but it has the advantage that it is quite efficient given
+ that the pass generally has exact knowledge of what it is changing.
+
+DATA STRUCTURES