Updates.
[external/binutils.git] / gdb / TODO
1 If you find inaccuracies in this list, please send mail to
2 gdb-patches@sourceware.cygnus.com.  If you would like to work on any
3 of these, you should consider sending mail to the same address, to
4 find out whether anyone else is working on it.
5
6
7                 Known problems in GDB 5.0
8                 =========================
9
10 Below is a list of problems identified during the GDB 5.0 release
11 cycle.  People hope to have these problems fixed in a follow-on
12 release.
13
14 --
15
16 The BFD directory requires bug-fixed AUTOMAKE et.al.
17
18 AUTOMAKE 1.4 incorrectly set the TEXINPUTS environment variable.  It
19 contained the full path to texinfo.tex when it should have only
20 contained the directory.  The bug has been fixed in the current
21 AUTOMAKE sources.  Automake snapshots can be found in:
22         ftp://sourceware.cygnus.com/pub/gdb/snapshots
23 and     ftp://sourceware.cygnus.com/pub/binutils
24
25 --
26
27 RFD: infrun.c: No bpstat_stop_status call after proceed over break?
28 http://sourceware.cygnus.com/ml/gdb-patches/2000-q1/msg00665.html
29
30 GDB misses watchpoint triggers after proceeding over a breakpoint on
31 x86 targets.
32
33 --
34
35 x86 linux GDB and SIGALRM (???)
36 http://sourceware.cygnus.com/ml/gdb/2000-q1/msg00803.html
37
38 This problem has been fixed, but a regression test still needs to be
39 added to the testsuite:
40 http://sourceware.cygnus.com/ml/gdb-patches/2000-05/msg00309.html
41
42 Mark
43
44 --
45
46 Revised UDP support (was: Re: [Fwd: [patch] UDP transport support])
47 http://sourceware.cygnus.com/ml/gdb-patches/2000-04/msg00000.html
48
49 (Broken) support for GDB's remote protocol across UDP is to be
50 included in the follow-on release.
51
52 It should be noted that UDP can only work when the [Gg] packet fits in
53 a single UDP packet.
54
55 --
56
57 Can't build IRIX -> arm GDB.
58 http://sourceware.cygnus.com/ml/gdb-patches/2000-04/msg00356.html
59
60 David Whedon writes:
61 > Now I'm building for an embedded arm target.  If there is a way of turning
62 > remote-rdi off, I couldn't find it. It looks like it gets built by default
63 > in gdb/configure.tgt(line 58) Anyway, the build dies in
64 > gdb/rdi-share/unixcomm.c.  SERPORT1 et. al. never get defined because we
65 > aren't one of the architectures supported.
66
67 --
68
69 Problem with weak functions
70 http://sourceware.cygnus.com/ml/gdb/2000-05/msg00060.html
71
72 Dan Nicolaescu writes:
73 > It seems that gdb-4.95.1  does not display correctly the function when
74 > stoping in weak functions. 
75
76 > It stops in a function that is defined as weak, not in the function
77 > that is actualy run... 
78
79 --
80
81 GDB 5.0 doesn't work on Linux/SPARC
82
83 --
84
85                 Code Cleanups: Next Release
86                 ===========================
87
88 The following are small cleanups that will hopefully be completed by
89 the follow on to 5.0.
90
91 --
92
93 Delete macro TARGET_BYTE_ORDER_SELECTABLE.
94
95 Patches in the database.
96
97 --
98
99 Purge PARAMS.
100
101 Eliminate all uses of PARAMS in GDB's source code.
102
103 --
104
105 Fix copyright notices.
106
107 Turns out that ``1998-2000'' isn't considered valid :-(
108
109 http://sourceware.cygnus.com/ml/gdb-patches/2000-05/msg00467.html
110
111 --
112
113 Find something better than DEFAULT_BFD_ARCH, DEFAULT_BFD_VEC to
114 determine the default isa/byte-order.
115
116 --
117
118 Rely on BFD_BIG_ENDIAN and BFD_LITTLE_ENDIAN instead of host dependant
119 BIG_ENDIAN and LITTLE_ENDIAN.
120
121 --
122
123 printcmd.c (print_address_numeric):
124
125 NOTE: This assumes that the significant address information is kept in
126 the least significant bits of ADDR - the upper bits were either zero
127 or sign extended.  Should ADDRESS_TO_POINTER() or some
128 ADDRESS_TO_PRINTABLE() be used to do the conversion?
129
130 --
131
132                 Code Cleanups: General
133                 ======================
134
135 The following are more general cleanups and fixes.  They are not tied
136 to any specific release.
137
138 --
139
140 Eliminate more compiler warnings.
141
142 Of course there also needs to be the usual debate over which warnings
143 are valid and how to best go about this.
144
145 One method: choose a single option; get agreement that it is
146 reasonable; try it out to see if there isn't anything silly about it
147 (-Wunused-parameters is an example of that) then incrementally hack
148 away.
149
150 The other method is to enable all warnings and eliminate them from one
151 file at a time.
152
153 --
154
155 Elimination of ``(catch_errors_ftype *) func''.
156
157 Like make_cleanup_func it isn't portable.
158 http://sourceware.cygnus.com/ml/gdb-patches/2000-q1/msg00791.html
159 http://sourceware.cygnus.com/ml/gdb-patches/2000-q1/msg00814.html
160
161
162 --
163
164 Nuke USG define.
165
166 --
167
168 [PATCH/5] src/intl/Makefile.in:distclean additions
169 http://sourceware.cygnus.com/ml/gdb-patches/2000-04/msg00363.html
170
171 Do not forget to merge the patch back into the trunk.
172
173 --
174
175 Rationalize the host-endian code (grep for HOST_BYTE_ORDER).
176
177 At present defs.h includes <endian.h> (which is linux specific) yet
178 almost nothing depends on it.  Suggest "gdb_endian.h" which can also
179 handle <machine/endian.h> and only include that where it is really
180 needed.
181
182 --
183
184 Replace asprintf() calls with xasprintf() calls.
185
186 As with things like strdup() most calls to asprintf() don't check the
187 return value.
188
189 --
190
191 Replace strsave() + mstrsave() with libiberty:xstrdup().
192
193 --
194
195 Replace savestring() with something from libiberty.
196
197 An xstrldup()? but that would have different semantics.
198
199 --
200
201 Rationalize use of floatformat_unknown in GDB sources.
202
203 Instead of defaulting to floatformat_unknown, should hosts/targets
204 specify the value explicitly?
205
206 http://sourceware.cygnus.com/ml/gdb-patches/2000-05/msg00447.html
207
208 --
209
210 Add a ``name'' member to include/floatformat.h:struct floatformat.
211 Print that name in gdbarch.c.
212
213 --
214
215 Sort out the harris mess in include/floatformat.h (it hardwires two
216 different floating point formats).
217
218 --
219
220 See of the GDB local floatformat_do_doublest() and libiberty's
221 floatformat_to_double (which was once GDB's ...) can be merged some
222 how.
223
224 --
225
226 Eliminate mmalloc() from GDB.
227
228 Also eliminate it from defs.h.
229
230 --
231
232 Eliminate PTR.  ISO-C allows ``void *''.
233
234 --
235
236 Eliminate abort ().
237
238 GDB should never abort.  GDB should either throw ``error ()'' or
239 ``internal_error ()''.  Better still GDB should naturally unwind with
240 an error status.
241
242 --
243
244 GDB probably doesn't build on FreeBSD pre 2.2.x
245 http://sourceware.cygnus.com/ml/gdb-patches/2000-05/msg00378.html
246
247 Fixes to get FreeBSD working on 2.2.x, 3.x and 4.x caused the code to
248 suffer bit rot.
249
250 --
251
252 Deprecate "fg".  Apparently ``fg'' is actually continue.
253
254 http://sourceware.cygnus.com/ml/gdb-patches/2000-05/msg00417.html
255
256 --
257
258 Deprecate current use of ``floatformat_unknown''.
259
260 Require all targets to explicitly provide their float format instead
261 of defaulting to floatformat unknown.  Doing the latter leads to nasty
262 bugs.
263
264 http://sourceware.cygnus.com/ml/gdb-patches/2000-05/msg00447.html
265
266 --
267
268 Rationalize floatformat_to_double() vs floatformat_to_doublest().
269
270 Looks like GDB migrated floatformat_to_double() to libiberty but then
271 turned around and created a ..._to_doublest() the latter containing
272 several bug fixes.
273
274 http://sourceware.cygnus.com/ml/gdb-patches/2000-05/msg00472.html
275
276 --
277
278 Move floatformat_ia64_ext to libiberty/include floatformat.[ch].
279
280 http://sourceware.cygnus.com/ml/gdb-patches/2000-05/msg00466.html
281
282 --
283
284 Follow through `make check' with --enable-shared.
285
286 When the srcware tree is configured with --enable-shared, the `expect'
287 program won't run properly.  Jim Wilson found out gdb has a local hack
288 to set LD_LIBRARY_PATH, but, AFAIK, no other project has been hacked
289 similarly.
290
291 http://sourceware.cygnus.com/ml/gdb/2000-q1/msg00845.html
292
293 --
294
295 The ``maintenance deprecate set endian big'' command doesn't notice
296 that it is deprecating ``set endian'' and not ``set endian big'' (big
297 is implemented using an enum).  Is anyone going to notice this?
298
299 --
300
301 When tab expanding something like ``set arch<tab>'' ignore the
302 deprecated ``set archdebug'' and expand to ``set architecture''.
303
304 --
305
306 Eliminate ``arm_register_names[j] = (char *) regnames[j]'' and the
307 like from arm-tdep.c.
308
309 --
310
311 Fix uses of ->function.cfunc = set_function().
312
313 The command.c code calls sfunc() when a set command.  Rather than
314 change it suggest fixing the callback function so that it is more
315 useful.  See:
316
317 http://sourceware.cygnus.com/ml/gdb-patches/2000-06/msg00062.html
318
319 See also ``Fix implementation of  ``target xxx''.'' below.
320
321 --
322
323 IRIX 3.x support is probably broken.
324
325 --
326
327 Delete sim/SIM_HAVE_BREAKPOINTS and gdb/SIM_HAS_BREAKPOINTS.
328 http://sourceware.cygnus.com/ml/gdb-patches/2000-07/msg00042.html
329
330 Apart from the d30v, are there any sim/common simulators that make use
331 of this?
332
333 A brief summary of what happended is that sim/common/sim-break.c was
334 created as a good idea.  It turned out a better idea was to use
335 SIM_SIGBREAK and have GDB pass back sim_resume (..., SIGBREAK).
336
337 --
338
339 parse.c:build_parse() has a buffer overrun.
340
341 --
342
343                         New Features and Fixes
344                         ======================
345
346 These are harder than cleanups but easier than work involving
347 fundamental architectural change.
348
349 --
350
351 Add built-by, build-date, tm, xm, nm and anything else into gdb binary
352 so that you can see how the GDB was created.
353
354 Some of these (*m.h) would be added to the generated config.h.  That
355 in turn would fix a long standing bug where by the build process many
356 not notice a changed tm.h file.  Since everything depends on config.h,
357 a change to *m.h forces a change to config.h and, consequently forces
358 a rebuild.
359
360 --
361
362 Add an "info bfd" command that displays supported object formats,
363 similarly to objdump -i.
364
365 Is there a command already?
366
367 --
368
369 Fix ``I'm sorry, Dave, I can't do that.'' from symfile.c.
370
371 This requires internationalization.
372
373 --
374
375 Add support for:
376  
377 (gdb) p fwprintf(stdout,L"%S\n", f)
378 No symbol "L" in current context.
379
380 --
381
382 Convert GDB build process to AUTOMAKE.
383
384 See also sub-directory configure below.
385
386 The current convention is (kind of) to use $(<header>_h) in all
387 dependency lists.  It isn't done in a consistent way.
388
389 --
390
391 Cleanup configury support for optional sub-directories.
392
393 Check how GCC handles multiple front ends for an example of how things
394 could work.  A tentative first step is to rationalize things so that
395 all sub directories are handled in a fashion similar to gdb/mi.
396
397 See also automake above.
398
399 --
400
401 Restructure gdb directory tree so that it avoids any 8.3 and 14
402 filename problems.
403
404 --
405
406 Add a transcript mechanism to GDB.
407
408 Such a mechanism might log all gdb input and output to a file in a
409 form that would allow it to be replayed.  It could involve ``gdb
410 --transcript=FILE'' or it could involve ``(gdb) transcript file''.
411
412 --
413
414 Can the xdep files be replaced by autoconf?
415
416 --
417
418 Document trace machinery
419
420 --
421
422 Document ui-out and ui-file.
423
424 http://sourceware.cygnus.com/ml/gdb/2000-04/msg00121.html
425
426 --
427
428 Update texinfo.tex to latest?
429
430
431
432 --
433
434 Incorporate agentexpr.texi into gdb.texinfo
435
436 agentexpr.texi mostly describes the details of the byte code used for
437 tracepoints, not the internals of the support for this in GDB.  So it
438 looks like gdb.texinfo is a better place for this information.
439
440 http://sourceware.cygnus.com/ml/gdb-patches/2000-04/msg00566.html
441
442 --
443
444 Document overlay machinery.
445
446 --
447
448 ``(gdb) catch signal SIGNAL''
449
450 Overlaps with ``handle SIGNAL'' but the implied behavour is different.
451 You can attach commands to a catch but not a handle.  A handle has a
452 limited number of hardwired actions.
453
454 --
455
456 Get the TUI working on all platforms.
457
458 --
459
460 Add support for ``gdb --- PROGRAM ARGS ...''.
461 Add support for ``gdb -cmd=...''
462
463 Along with many variations.  Check:
464
465 ????? for a full discussion.
466
467 for a discussion.
468
469 --
470
471 Implement ``(gdb) !ls''.
472
473 Which is very different from ``(gdb) ! ls''.  Implementing the latter
474 is trivial.
475
476 http://sourceware.cygnus.com/ml/gdb/2000-q1/msg00034.html
477
478 --
479
480 Change the (char *list[]) to (const char (*)[]) so that dynamic lists can
481 be passed.
482
483 --
484
485 When tab expanding something like ``set arch<tab>'' ignore the
486 deprecated ``set archdebug'' and expand to ``set architecture''.
487
488 --
489
490 Replace the code that uses the host FPU with an emulator of the target
491 FPU.
492
493 --
494
495                         Thread Support
496                         ==============
497
498 --
499
500 Generic: lin-thread cannot handle thread exit (Mark Kettenis, Michael
501 Snyder) http://sourceware.cygnus.com/ml/gdb/2000-q1/msg00525.html
502
503 The thread_db assisted debugging code doesn't handle exiting threads
504 properly, at least in combination with glibc 2.1.3 (the framework is
505 there, just not the actual code).  There are at least two problems
506 that prevent this from working.
507
508 As an additional reference point, the pre thread_db code did not work
509 either.
510
511 --
512
513 GNU/Linux/x86 and random thread signals (and Solaris/SPARC but not
514 Solaris/x86).
515 http://sourceware.cygnus.com/ml/gdb/2000-q1/msg00336.html
516
517 Christopher Blizzard writes:
518
519 So, I've done some more digging into this and it looks like Jim
520 Kingdon has reported this problem in the past:
521
522 http://sourceware.cygnus.com/ml/bug-gdb/1999-10/msg00058.html
523
524 I can reproduce this problem both with and without Tom's patch.  Has
525 anyone seen this before?  Maybe have a solution for it hanging around?
526 :)
527
528 There's a test case for this documented at:
529
530 when debugging threaded applications you get extra SIGTRAPs
531 http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=9565
532
533 [There should be a GDB testcase - cagney]
534
535 --
536
537 GDB5 TOT on unixware 7
538 http://sourceware.cygnus.com/ml/gdb/2000-04/msg00119.html
539
540 Robert Lipe writes:
541 > I just spun the top of tree of the GDB5 branch on UnixWare 7.  As a
542 > practical matter, the current thread support is somewhat more annoying
543 > than when GDB was thread-unaware.
544
545 --
546
547 Migrate qfThreadInfo packet -> qThreadInfo. (Andrew Cagney)
548
549 Add support for packet enable/disable commands with these thread
550 packets.  General cleanup.
551
552 [PATCH] Document the ThreadInfo remote protocol queries
553 http://sourceware.cygnus.com/ml/gdb-patches/2000-q1/msg00832.html
554
555 [PATCH] "info threads" queries for remote.c
556 http://sourceware.cygnus.com/ml/gdb-patches/2000-q1/msg00831.html
557
558 --
559
560                         Language Support
561                         ================
562
563 New languages come onto the scene all the time.
564
565 --
566
567 Pascal (Pierre Muller, David Taylor)
568
569 Pierre Muller has contributed patches for adding Pascal Language
570 support to GDB.
571
572 2 pascal language patches inserted in database
573 http://sourceware.cygnus.com/ml/gdb/2000-q1/msg00521.html
574
575 Indent -gnu ?
576 http://sourceware.cygnus.com/ml/gdb/2000-q1/msg00496.html
577
578 --
579
580 Java (Anthony Green, David Taylor)
581
582 Anthony Green has a number of Java patches that did not make it into
583 the 5.0 release.  The first two are in cvs now, but the third needs
584 some fixing up before it can go in.
585
586 Patch: java tests
587 http://sourceware.cygnus.com/ml/gdb-patches/2000-q1/msg00512.html
588
589 Patch: java booleans
590 http://sourceware.cygnus.com/ml/gdb-patches/2000-q1/msg00515.html
591
592 Patch: handle N_MAIN stab
593 http://sourceware.cygnus.com/ml/gdb-patches/2000-q1/msg00527.html
594
595 --
596
597 [Comming...]
598
599 Modify gdb to work correctly with Pascal.
600
601 --
602
603 Re: Various C++ things
604
605 value_headof/value_from_vtable_info are worthless, and should be
606 removed.  The one place in printcmd.c that uses it should use the RTTI
607 functions.
608
609 RTTI for g++ should be using the typeinfo functions rather than the
610 vtables.  The typeinfo functions are always at offset 4 from the
611 beginning of the vtable, and are always right. The vtables will have
612 weird names like E::VB sometimes.  The typeinfo function will always
613 be "E type_info function", or somesuch.
614
615 value_virtual_fn_field needs to be fixed so there are no failures for
616 virtual functions for C++ using g++.
617
618 Testsuite cases are the major priority right now for C++ support,
619 since i have to make a lot of changes that could potentially break
620 each other.
621
622 --
623
624 Add support for Modula3
625
626 Get DEC/Compaq to contribute their Modula-3 support.
627
628 --
629
630                 Remote Protocol Support
631                 =======================
632
633 --
634
635 set/show remote X-packet ...
636
637 ``(gdb) help set remote X-packet'' doesn't list the applicable
638 responses.  The help message needs to be expanded.
639
640 --
641
642 Remote protocol doco feedback.
643
644 Too much feedback to mention needs to be merged in (901660).  Search
645 for the word ``remote''.
646
647
648 http://sourceware.cygnus.com/ml/gdb/2000-q1/msg00023.html
649 http://sourceware.cygnus.com/ml/gdb/2000-q1/msg00056.html
650 http://sourceware.cygnus.com/ml/gdb/2000-q1/msg00382.html
651
652 --
653
654 GDB doesn't recover gracefully from remote protocol errors.
655
656 GDB wasn't checking for NAKs from the remote target.  Instead a NAK is
657 ignored and a timeout is required before GDB retries.  A pre-cursor to
658 fixing this this is making GDB's remote protocol packet more robust.
659
660 While downloading to a remote protocol target, gdb ignores packet
661 errors in so far as it will continue to edownload with chunk N+1 even
662 if chunk N was not correctly sent.  This causes gdb.base/remote.exp to
663 take a painfully long time to run.  As a PS that test needs to be
664 fixed so that it builds on 16 bit machines.
665
666 --
667
668 Add the cycle step command.
669
670 http://sourceware.cygnus.com/ml/gdb/2000-q1/msg00237.html
671
672 --
673
674 Resolve how to scale things to support very large packets.
675
676 --
677
678 Resolve how to handle a target that changes things like its endianess
679 on the fly - should it be returned in the ``T'' packet?
680
681 Underlying problem is that the register file is target endian.  If the
682 target endianess changes gdb doesn't know.
683
684 --
685
686 Use the recently added add_set_auto_boolean_cmd() function to
687 implement the X-packet commands.
688
689 --
690
691 Rename read_register{,_pid}() to read_unsigned_register{,_pid}().
692
693 --
694
695                         Symbol Support
696                         ==============
697
698 If / when GDB starts to support the debugging of multi-processor
699 (rather than multi-thread) applications the symtab code will need to
700 be updated a little so that several independant symbol tables are
701 active at a given time.
702
703 The other interesting change is a clarification of the exact meaning
704 of CORE_ADDR and that has had consequences for a few targets (that
705 were abusing that data type).
706
707 --
708
709 Investiagate ways of reducing memory.
710
711 --
712
713 Investigate ways of improving load time.
714
715 --
716
717 Get the d10v to use POINTER_TO_ADDRESS and ADDRESS_TO_POINTER.
718
719 Consequence of recent symtab clarification.  No marks for figuring out
720 who maintains the d10v.
721
722 --
723
724 Get the MIPS to correctly sign extend all address <-> pointer
725 conversions.
726
727 Consequence of recent symtab clarification.  No marks for figuring out
728 who maintains the MIPS.
729
730 --
731
732 GDB truncates 64 bit enums.
733
734 http://sourceware.cygnus.com/ml/gdb-patches/2000-06/msg00290.html
735
736 --
737
738                         Testsuite Support
739                         =================
740
741 There are never to many testcases.
742
743 --
744
745 Better thread testsuite.
746
747 --
748
749 Better C++ testsuite.
750
751 --
752
753 Look at adding a GDB specific testsuite directory so that white box
754 tests of key internals can be added (eg ui_file).
755
756 --
757
758 Separate out tests that involve the floating point (FP).
759
760 (Something for people brining up new targets).  FP and non-fp tests
761 are combined.  I think there should be set of basic tests that
762 exercise pure integer support and then a more expanded set that
763 exercise FP and FP/integer interactions.
764
765 As an example, the MIPS, for n32 as problems with passing FP's and
766 structs.  Since most inferior call tests include FP it is difficult to
767 determine of the integer tests are ok.
768
769 --
770
771                 Architectural Changes: General
772                 ==============================
773
774 These are harder than simple cleanups / fixes and, consequently
775 involve more work.  Typically an Architectural Change will be broken
776 down into a more digestible set of cleanups and fixes.
777
778 --
779
780 Cleanup software single step.
781
782 At present many targets implement software single step by directly
783 blatting memory (see rs6000-tdep.c).  Those targets should register
784 the applicable breakpoints using the breakpoint framework.  Perhaphs a
785 new internal breakpoint class ``step'' is needed.
786
787 --
788
789 Replace READ_FP() with FRAME_HANDLE().
790
791 READ_FP() is a hangover from the days of the vax when the ABI really
792 did have a frame pointer register.  Modern architectures typically
793 construct a virtual frame-handle from the stack pointer and various
794 other bits of string.
795
796 Unfortunatly GDB still treats this synthetic FP register as though it
797 is real.  That in turn really confuses users (arm and ``print $fp'' VS
798 ``info registers fp'').  The synthetic FP should be separated out of
799 the true register set presented to the user.
800
801 --
802
803 Register Cache Cleanup (below from Andrew Cagney)
804
805 I would depict the current register architecture as something like:
806
807         High GDB  -->   Low GDB
808             |              |
809            \|/            \|/
810             --- REG NR -----
811                    |
812     register + REGISTER_BYTE(reg_nr)
813                    |
814                   \|/
815         -------------------------
816         |  extern register[]    |
817         -------------------------
818
819 where neither the high (valops.c et.al.) or low gdb (*-tdep.c) are
820 really clear on what mechanisms they should be using to manipulate that
821 buffer.   Further, much code assumes, dangerously, that registers are
822 contigious.  Having got mips-tdep.c to support multiple ABIs, believe
823 me, that is a bad assumption.  Finally, that register cache layout is
824 determined by the current remote/local target and _not_ the less
825 specific target ISA.  In fact, in many cases it is determined by the
826 somewhat arbitrary layout of the [gG] packets!
827
828
829 How I would like the register file to work is more like:
830
831
832           High GDB
833              |
834             \|/
835        pseudo reg-nr
836              |
837         map pseudo <->
838         random cache
839         bytes       
840              |
841             \|/
842         ------------
843         | register |
844         |  cache   |
845         ------------
846             /|\
847              |
848         map random cache
849         bytes to target
850         dependant i-face
851             /|\
852              |
853        target dependant
854         such as [gG] packet
855         or ptrace buffer
856
857 The main objectives being:
858
859         o       a clear separation between the low
860                 level target and the high level GDB
861
862         o       a mechanism that solves the general
863                 problem of register aliases, overlaps
864                 etc instead of treating them as optional
865                 extras that can be wedged in as an after
866                 thought (that is a reasonable description
867                 of the current code).
868
869                 Identify then solve the hard case and the
870                 rest just falls out.  GDB solved the easy
871                 case and then tried to ignore the real
872                 world :-)
873
874         o       a removal of the assumption that the
875                 mapping between the register cache
876                 and virtual registers is largely static.
877                 If you flip the USR/SSR stack register
878                 select bit in the status-register then
879                 the corresponding stack registers should
880                 reflect the change.
881
882         o       a mechanism that clearly separates the
883                 gdb internal register cache from any
884                 target (not architecture) dependant
885                 specifics such as [gG] packets.
886
887 Of course, like anything, it sounds good in theory.  In reality, it
888 would have to contend with many<->many relationships at both the
889 virt<->cache and cache<->target level.  For instance:
890
891         virt<->cache
892                 Modifying an mmx register may involve
893                 scattering values across both FP and
894                 mmpx specific parts of a buffer
895
896         cache<->target
897                 When writing back a SP it may need to
898                 both be written to both SP and USP.
899
900
901 Hmm,
902
903 Rather than let this like the last time it was discussed, just slip, I'm
904 first going to add this e-mail (+ references) to TODO.  I'd then like to
905 sketch out a broad strategy I think could get us there.
906
907
908 First thing I'd suggest is separating out the ``extern registers[]''
909 code so that we can at least identify what is using it.  At present
910 things are scattered across many files.  That way we can at least
911 pretend that there is a cache instead of a global array :-)
912
913 I'd then suggest someone putting up a proposal for the pseudo-reg /
914 high-level side interface so that code can be adopted to it.  For old
915 code, initially a blanket rename of write_register_bytes() to
916 deprecated_write_register_bytes() would help.
917
918 Following that would, finaly be the corresponding changes to the target.
919
920 --
921
922 Check that GDB can handle all BFD architectures (Andrew Cagney)
923
924 There should be a test that checks that BFD/GDB are in sync with
925 regard to architecture changes.  Something like a test that first
926 queries GDB for all supported architectures and then feeds each back
927 to GDB..  Anyone interested in learning how to write tests?  :-)
928
929 --
930
931                 Architectural Change: Multi-arch et al.
932                 =======================================
933
934 The long term objective is to remove all assumptions that there is a
935 single target with a single address space with a single instruction
936 set architecture and single application binary interface.
937
938 This is an ongoing effort.  The first milestone is to enable
939 ``multi-arch'' where by all architectural decisions are made at
940 runtime.
941
942 It should be noted that ``gdbarch'' is really ``gdbabi'' and
943 ``gdbisa''.  Once things are multi-arched breaking that down correctly
944 will become much easier.
945
946 --
947
948 GDBARCH cleanup (Andrew Cagney)
949
950 The non-generated parts of gdbarch.{sh,h,c} should be separated out
951 into arch-utils.[hc].
952
953 Document that gdbarch_init_ftype could easily fail because it didn't
954 identify an architecture.
955
956 --
957
958 Fix BELIEVE_PPC_PROMOTION.  Change it to BELIEVE_PPC_PROMOTION_P?
959
960 At present there is still #ifdef BELIEVE_PPC_PROMOTION code in the
961 symtab file.
962
963 --
964
965 Fix target_signal_from_host() etc.
966
967 The name is wrong for starters.  ``target_signal'' should probably be
968 ``gdb_signal''.  ``from_host'' should be ``from_target_signal''.
969 After that it needs to be multi-arched and made independant of any
970 host signal numbering.
971
972 --
973
974 Update ALPHA so that it uses ``struct frame_extra_info'' instead of
975 EXTRA_FRAME_INFO.
976
977 This is a barrier to replacing mips_extra_func_info with something
978 that works with multi-arch.
979
980 --
981
982 Multi-arch  mips_extra_func_info.
983
984 This first needs the alpha to be updated so that it uses ``struct
985 frame_extra_info''.
986
987 --
988
989 Rationalize TARGET_SINGLE_FORMAT and TARGET_SINGLE_BIT et al.
990
991 Surely one of them is redundant.
992
993 --
994
995 Convert ALL architectures to MULTI-ARCH.
996
997 --
998
999 Select the initial multi-arch ISA / ABI based on --target or similar.
1000
1001 At present the default is based on what ever is first in the BFD
1002 archures table.  It should be determined based on the ``--target=...''
1003 name.
1004
1005 --
1006
1007 Make MIPS pure multi-arch.
1008
1009 It is only at the multi-arch enabled stage.
1010
1011 --
1012
1013 Truly multi-arch.
1014
1015 Enable the code to recognize --enable-targets=.... like BINUTILS does.
1016
1017 Can the tm.h and nm.h files be eliminated by multi-arch.
1018
1019 --
1020
1021         Architectural Change: MI, LIBGDB and scripting languages
1022         ========================================================
1023
1024 See also architectural changes related to the event loop.  LIBGDB
1025 can't be finished until there is a generic event loop being used by
1026 all targets.
1027
1028 The long term objective is it to be possible to integrate GDB into
1029 scripting languages.
1030
1031 --
1032
1033 Implement generic ``(gdb) commmand > file''
1034
1035 Once everything is going through ui_file it should be come fairly
1036 easy.
1037
1038 http://sourceware.cygnus.com/ml/gdb/2000-04/msg00104.html
1039
1040 --
1041
1042 Replace gdb_stdtarg with gdb_targout (and possibly gdb_targerr).
1043
1044 gdb_stdtarg is easily confused with gdb_stdarg.
1045
1046 --
1047
1048 Extra ui_file methods - dump.
1049
1050 Very useful for whitebox testing.
1051
1052 --
1053
1054 Eliminate error_begin().
1055
1056 With ui_file, there is no need for the statefull error_begin ()
1057 function.
1058
1059 --
1060
1061 Send normal output to gdb_stdout.
1062 Send error messages to gdb_stderror.
1063 Send debug and log output log gdb_stdlog.
1064
1065 GDB still contains many cases where (f)printf or printf_filtered () is
1066 used when it should be sending the messages to gdb_stderror or
1067 gdb_stdlog.  The thought of #defining printf to something has crossed
1068 peoples minds ;-)
1069
1070 --
1071
1072 Re-do GDB's output pager.
1073
1074 GDB's output pager still relies on people correctly using *_filtered
1075 for gdb_stdout and *_unfiltered for gdb_stdlog / gdb_stderr.
1076 Hopefully, with all normal output going to gdb_stdout, the pager can
1077 just look at the ui_file that the output is on and then use that to
1078 decide what to do about paging.  Sounds good in theory.
1079
1080 --
1081
1082 Check/cleanup MI documentation.
1083
1084 The list of commands specified in the documentation needs to be
1085 checked against the mi-cmds.c table in a mechanical way (so that they
1086 two can be kept up-to-date).
1087
1088 --
1089
1090 Convert MI into libgdb
1091
1092 MI provides a text interface into what should be many of the libgdb
1093 functions.  The implementation of those functions should be separated
1094 into the MI interface and the functions proper.  Those functions being
1095 moved to gdb/lib say.
1096
1097 --
1098
1099 Create libgdb.h
1100
1101 The first part can already be found in defs.h.
1102
1103 --
1104
1105 MI's input does not use buffering.
1106
1107 At present the MI interface reads raw characters of from an unbuffered
1108 FD.  This is to avoid several nasty buffer/race conditions.  That code
1109 should be changed so that it registers its self with the event loop
1110 (on the input FD) and then push commands up to MI as they arrive.
1111
1112 The serial code already does this.
1113
1114 --
1115
1116 Make MI interface accessable from existing CLI.
1117
1118 --
1119
1120 Add a breakpoint-edit command to MI.
1121
1122 It would be similar to MI's breakpoint create but would apply to an
1123 existing breakpoint.  It saves the need to delete/create breakpoints
1124 when ever they are changed.
1125
1126 --
1127
1128 Add directory path to MI breakpoint.
1129
1130 That way the GUI's task of finding the file within which the
1131 breakpoint was set is simplified.
1132
1133 --
1134
1135 Add a mechanism to reject certain expression classes to MI
1136
1137 There are situtations where you don't want GDB's expression
1138 parser/evaluator to perform inferior function calls or variable
1139 assignments.  A way of restricting the expression parser so that such
1140 operations are not accepted would be very helpful.
1141
1142 --
1143
1144 Remove sideffects from libgdb breakpoint create function.
1145
1146 The user can use the CLI to create a breakpoint with partial
1147 information - no file (gdb would use the file from the last
1148 breakpoint).
1149
1150 The libgdb interface currently affects that environment which can lead
1151 to confusion when a user is setting breakpoints via both the MI and
1152 the CLI.
1153
1154 This is also a good example of how getting the CLI ``right'' will be
1155 hard.
1156
1157 --
1158
1159 Move gdb_lasterr to ui_out?
1160
1161 The way GDB throws errors and records them needs a re-think.  ui_out
1162 handles the correct output well.  It doesn't resolve what to do with
1163 output / error-messages when things go wrong.
1164
1165 --
1166
1167 do_setshow_command contains a 1024 byte buffer.
1168
1169 The function assumes that there will never be any more than 1024 bytes
1170 of enum.  It should use mem_file.
1171
1172 --
1173
1174 Should struct cmd_list_element . completer take the command as an
1175 argument?
1176
1177 --
1178
1179 Should the bulk of top.c:line_completion_function() be moved to
1180 command.[hc]?  complete_on_cmdlist() and complete_on_enums() could
1181 then be made private.
1182
1183 --
1184
1185 top.c (execute_command): Should a command being valid when the target
1186 is running be made an attribute (predicate) to the command rather than
1187 an explicit set of tests.
1188
1189 --
1190
1191 top.c (execute_command): Should the bulk of this function be moved
1192 into command.[hc] so that top.c doesn't grub around in the command
1193 internals?
1194
1195 --
1196
1197                 Architectural Change: Async
1198                 ===========================
1199
1200 While GDB uses an event loop when prompting the user for input.  That
1201 event loop is not exploited by targets when they allow the target
1202 program to continue.  Typically targets still block in (target_wait())
1203 until the program again halts.
1204
1205 The closest a target comes to supporting full asynchronous mode are
1206 the remote targets ``async'' and ``extended-async''.
1207
1208 --
1209
1210 Asynchronous expression evaluator
1211
1212 Inferior function calls hang GDB.
1213
1214 --
1215
1216 Fix implementation of  ``target xxx''.
1217
1218 At present when the user specifies ``target xxxx'', the CLI maps that
1219 directly onto a target open method.  It is then assumed that the
1220 target open method should do all sorts of complicated things as this
1221 is the only chance it has.  Check how the various remote targets
1222 duplicate the target operations.  Check also how the various targets
1223 behave differently for purely arbitrary reasons.
1224
1225 What should happen is that ``target xxxx'' should call a generic
1226 ``target'' function and that should then co-ordinate the opening of
1227 ``xxxx''.  This becomes especially important when you're trying to
1228 open an asynchronous target that may need to perform background tasks
1229 as part of the ``attach'' phase.
1230
1231 Unfortunatly, due to limitations in the old/creaking command.h
1232 interface, that isn't possible.  The function being called isn't told
1233 of the ``xxx'' or any other context information.
1234
1235 Consequently a precursor to fixing ``target xxxx'' is to clean up the
1236 CLI code so that it passes to the callback function (attatched to a
1237 command) useful information such as the actual command and a context
1238 for that command.  Other changes such as making ``struct command''
1239 opaque may also help.
1240
1241 See also:
1242 http://sourceware.cygnus.com/ml/gdb-patches/2000-06/msg00062.html
1243
1244 --
1245
1246 Make "target xxx" command interruptible.
1247
1248 As things become async this becomes possible.  A target would start
1249 the connect and then return control to the event loop.  A cntrl-c
1250 would notify the target that the operation is to be abandoned and the
1251 target code could respond.
1252
1253 --
1254
1255 Add a "suspend" subcommand of the "continue" command to suspend gdb
1256 while continuing  execution of the subprocess.  Useful when you are
1257 debugging servers and you want to dodge out and initiate a connection
1258 to a server running under gdb.
1259
1260 [hey async!!]
1261
1262 --
1263
1264                         TODO FAQ
1265                         ========
1266
1267 Frequently requested but not approved requests.
1268
1269 --
1270
1271 Eliminate unused argument warnings using ATTRIBUTE_UNUSED.
1272
1273 The benefits on this one are thought to be marginal - GDBs design
1274 means that unused parameters are very common.  GCC 3.0 will also
1275 include the option -Wno-unused-parameter which means that ``-Wall
1276 -Wno-unused-parameters -Werror'' can be specified.
1277
1278 --
1279
1280
1281
1282                         Legacy Wish List
1283                         ================
1284
1285 This list is not up to date, and opinions vary about the importance or
1286 even desirability of some of the items.  If you do fix something, it
1287 always pays to check the below.
1288
1289 --
1290
1291 @c This does not work (yet if ever).  FIXME.
1292 @c @item --parse=@var{lang} @dots{}
1293 @c Configure the @value{GDBN} expression parser to parse the listed languages.
1294 @c @samp{all} configures @value{GDBN} for all supported languages.  To get a
1295 @c list of all supported languages, omit the argument.  Without this
1296 @c option, @value{GDBN} is configured to parse all supported languages.
1297
1298 --
1299
1300 START_INFERIOR_TRAPS_EXPECTED need never be defined to 2, since that
1301 is its default value.  Clean this up.
1302
1303 --
1304
1305 It should be possible to use symbols from shared libraries before we know
1306 exactly where the libraries will be loaded.  E.g. "b perror" before running
1307 the program.  This could maybe be done as an extension of the "breakpoint
1308 re-evaluation" after new symbols are loaded.
1309
1310 --
1311
1312 Make single_step() insert and remove breakpoints in one operation.
1313
1314 [If this is talking about having single_step() insert the breakpoints,
1315 run the target then pull the breakpoints then it is wrong.  The
1316 function has to return as control has to eventually be passed back to
1317 the main event loop.]
1318
1319 --
1320
1321 Speed up single stepping by avoiding extraneous ptrace calls.
1322
1323 --
1324
1325 Speed up single stepping by not inserting and removing breakpoints
1326 each time the inferior starts and stops.
1327
1328 Breakpoints should not be inserted and deleted all the time.  Only the
1329 one(s) there should be removed when we have to step over one.  Support
1330 breakpoints that don't have to be removed to step over them.
1331
1332 [this has resulted in numerous debates.  The issue isn't clear cut]
1333
1334 --
1335
1336 Provide "voodoo" debugging of core files.  This creates a zombie
1337 process as a child of the debugger, and loads it up with the data,
1338 stack, and regs of the core file.  This allows you to call functions
1339 in the executable, to manipulate the data in the core file.
1340
1341 [you wish]
1342
1343 --
1344
1345 GDB reopens the source file on every line, as you "next" through it.
1346
1347 [still true? I've a memory of this being fixed]
1348
1349 --
1350
1351 Perhaps "i source" should take an argument like that of "list".
1352
1353 --
1354
1355 Remove "at 0xnnnn" from the "b foo" response, if `print address off' and if
1356 it matches the source line indicated.
1357
1358 --
1359
1360 The prompt at end of screen should accept space as well as CR.
1361
1362 --
1363
1364 Backtrace should point out what the currently selected frame is, in
1365 its display, perhaps showing "@3 foo (bar, ...)" or ">3 foo (bar,
1366 ...)" rather than "#3 foo (bar, ...)".
1367
1368 --
1369
1370 "i program" should work for core files, and display more info, like what
1371 actually caused it to die.
1372
1373 --
1374
1375 "x/10i" should shorten the long name, if any, on subsequent lines.
1376
1377 --
1378
1379 "next" over a function that longjumps, never stops until next time you happen
1380 to get to that spot by accident.  E.g. "n" over execute_command which has
1381 an error.
1382
1383 --
1384
1385 "set zeroprint off", don't bother printing members of structs which
1386 are entirely zero.  Useful for those big structs with few useful
1387 members.
1388
1389 --
1390
1391 GDB does four ioctl's for every command, probably switching terminal modes
1392 to/from inferior or for readline or something.
1393
1394 --
1395
1396 terminal_ours versus terminal_inferior: cache state.  Switch should be a noop
1397 if the state is the same, too.
1398
1399 --
1400
1401 "i frame" shows wrong "arglist at" location, doesn't show where the args
1402 should be found, only their actual values.
1403
1404 --
1405
1406 There should be a way for "set" commands to validate the new setting
1407 before it takes effect.
1408
1409 --
1410
1411 "ena d" is ambiguous, why?  "ena delete" seems to think it is a command!
1412
1413 --
1414
1415 i line VAR produces "Line number not known for symbol ``var''.".  I
1416 thought we were stashing that info now!
1417
1418 --
1419
1420 We should be able to write to random files at hex offsets like adb.
1421
1422 --
1423
1424 [elena - delete this]
1425
1426 Handle add_file with separate text, data, and bss addresses.  Maybe
1427 handle separate addresses for each segment in the object file?
1428
1429 --
1430
1431 [Jimb/Elena delete this one]
1432
1433 Handle free_named_symtab to cope with multiply-loaded object files
1434 in a dynamic linking environment.  Should remember the last copy loaded,
1435 but not get too snowed if it finds references to the older copy.
1436
1437 --
1438
1439 [elena delete this also]
1440
1441 Remove all references to:
1442         text_offset
1443         data_offset
1444         text_data_start
1445         text_end
1446         exec_data_offset
1447         ...
1448 now that we have BFD.  All remaining are in machine dependent files.
1449
1450 --
1451
1452 Re-organize help categories into things that tend to fit on a screen
1453 and hang together.
1454
1455 --
1456
1457 Add in commands like ADB's for searching for patterns, etc.  We should
1458 be able to examine and patch raw unsymboled binaries as well in gdb as
1459 we can in adb.  (E.g. increase the timeout in /bin/login without source).
1460
1461 [actually, add ADB interface :-]
1462
1463 --
1464
1465 When doing "step" or "next", if a few lines of source are skipped between
1466 the previous line and the current one, print those lines, not just the
1467 last line of a multiline statement.
1468
1469 --
1470
1471 Handling of "&" address-of operator needs some serious overhaul
1472 for ANSI C and consistency on arrays and functions.
1473   For "float point[15];":
1474 ptype &point[4]   ==> Attempt to take address of non-lvalue.
1475   For "char *malloc();":
1476 ptype malloc      ==> "char *()";  should be same as
1477 ptype &malloc     ==> "char *(*)()"
1478 call printf ("%x\n", malloc)   ==> weird value, should be same as
1479 call printf ("%x\n", &malloc)  ==> correct value
1480
1481 --
1482
1483 Fix dbxread.c symbol reading in the presence of interrupts.  It
1484 currently leaves a cleanup to blow away the entire symbol table when a
1485 QUIT occurs.  (What's wrong with that? -kingdon, 28 Oct 1993).
1486
1487 [I suspect that the grype was that, on a slow system, you might want
1488 to cntrl-c and get just half the symbols and then load the rest later
1489 - scary to be honest]
1490
1491 --
1492
1493 Mipsread.c reads include files depth-first, because the dependencies
1494 in the psymtabs are way too inclusive (it seems to me).  Figure out what
1495 really depends on what, to avoid recursing 20 or 30 times while reading
1496 real symtabs.
1497
1498 --
1499
1500 value_add() should be subtracting the lower bound of arrays, if known,
1501 and possibly checking against the upper bound for error reporting.
1502
1503 --
1504
1505 When listing source lines, check for a preceding \n, to verify that
1506 the file hasn't changed out from under us.
1507
1508 [fixed by some other means I think.  That hack wouldn't actually work
1509 reliably - the file might move such that another \n appears. ]
1510
1511 --
1512
1513 Get all the remote systems (where the protocol allows it) to be able to
1514 stop the remote system when the GDB user types ^C (like remote.c
1515 does).  For ebmon, use ^Ak.
1516
1517 --
1518
1519 Possible feature: A version of the "disassemble" command which shows
1520 both source and assembly code ("set symbol-filename on" is a partial
1521 solution).
1522
1523 [has this been done?  It was certainly done for MI and GDBtk]
1524
1525 --
1526
1527 investigate "x/s 0" (right now stops early) (I think maybe GDB is
1528 using a 0 address for bad purposes internally).
1529
1530 --
1531
1532 Make "info path" and path_command work again (but independent of the
1533 environment either of gdb or that we'll pass to the inferior).
1534
1535 --
1536
1537 Make GDB understand the GCC feature for putting octal constants in
1538 enums.  Make it so overflow on an enum constant does not error_type
1539 the whole type.  Allow arbitrarily large enums with type attributes.
1540 Put all this stuff in the testsuite.
1541
1542 --
1543
1544 Make TYPE_CODE_ERROR with a non-zero TYPE_LENGTH more useful (print
1545 the value in hex; process type attributes).  Add this to the
1546 testsuite.  This way future compilers can add new types and old
1547 versions of GDB can do something halfway reasonable.
1548
1549 --
1550
1551 Fix mdebugread.c:parse_type to do fundamental types right (see
1552 rs6000_builtin_type in stabsread.c for what "right" is--the point is
1553 that the debug format fixes the sizes of these things and it shouldn't
1554 depend on stuff like TARGET_PTR_BIT and so on.  For mdebug, there seem
1555 to be separate bt* codes for 64 bit and 32 bit things, and GDB should
1556 be aware of that).  Also use a switch statement for clarity and speed.
1557
1558 --
1559
1560 Investigate adding symbols in target_load--some targets do, some
1561 don't.
1562
1563 --
1564
1565 Put dirname in psymtabs and change lookup*symtab to use dirname (so
1566 /foo/bar.c works whether compiled by cc /foo/bar.c, or cd /foo; cc
1567 bar.c).
1568
1569 --
1570
1571 Merge xcoffread.c and coffread.c.  Use breakpoint_re_set instead of
1572 fixup_breakpoints.
1573
1574 --
1575
1576 Make a watchpoint which contains a function call an error (it is
1577 broken now, making it work is probably not worth the effort).
1578
1579 --
1580
1581 New test case based on weird.exp but in which type numbers are not
1582 renumbered (thus multiply defining a type).  This currently causes an
1583 infinite loop on "p v_comb".
1584
1585 --
1586
1587 [Hey! Hint Hint Delete Delete!!!]
1588
1589 Fix 386 floating point so that floating point registers are real
1590 registers (but code can deal at run-time if they are missing, like
1591 mips and 68k).  This would clean up "info float" and related stuff.
1592
1593 --
1594
1595 gcc -g -c enummask.c then gdb enummask.o, then "p v".  GDB complains
1596 about not being able to access memory location 0.
1597
1598 -------------------- enummask.c
1599 enum mask
1600 {
1601   ANIMAL = 0,
1602   VEGETABLE = 1,
1603   MINERAL = 2,
1604   BASIC_CATEGORY = 3,
1605
1606   WHITE = 0,
1607   BLUE = 4,
1608   GREEN = 8,
1609   BLACK = 0xc,
1610   COLOR = 0xc,
1611
1612   ALIVE = 0x10,
1613
1614   LARGE = 0x20
1615 } v;
1616
1617 --
1618
1619 If try to modify value in file with "set write off" should give
1620 appropriate error not "cannot access memory at address 0x65e0".
1621
1622 --
1623
1624 Allow core file without exec file on RS/6000.
1625
1626 --
1627
1628 Make sure "shell" with no arguments works right on DOS.
1629
1630 --
1631
1632 Make gdb.ini (as well as .gdbinit) be checked on all platforms, so
1633 the same directory can be NFS-mounted on unix or DOS, and work the
1634 same way.
1635
1636 --
1637
1638 [Is this another delete???]
1639
1640 Get SECT_OFF_TEXT stuff out of objfile_relocate (might be needed to
1641 get RS/6000 to work right, might not be immediately relevant).
1642
1643 --
1644
1645 Work out some kind of way to allow running the inferior to be done as
1646 a sub-execution of, eg. breakpoint command lists.  Currently running
1647 the inferior interupts any command list execution.  This would require
1648 some rewriting of wait_for_inferior & friends, and hence should
1649 probably be done in concert with the above.
1650
1651 --
1652
1653 Add function arguments to gdb user defined functions.
1654
1655 --
1656
1657 Add convenience variables that refer to exec file, symbol file,
1658 selected frame source file, selected frame function, selected frame
1659 line number, etc.
1660
1661 --
1662
1663 Modify the handling of symbols grouped through BINCL/EINCL stabs to
1664 allocate a partial symtab for each BINCL/EINCL grouping.  This will
1665 seriously decrease the size of inter-psymtab dependencies and hence
1666 lessen the amount that needs to be read in when a new source file is
1667 accessed. 
1668
1669 --
1670
1671 Add a command for searching memory, a la adb.  It specifies size,
1672 mask, value, start address.  ADB searches until it finds it or hits
1673 an error (or is interrupted).
1674
1675 --
1676
1677 Remove the range and type checking code and documentation, if not
1678 going to implement.
1679
1680 # Local Variables:
1681 # mode: text
1682 # End: