What is "until" supposed to do?

[Daniel Jacobowitz <drow@false.org>]

The comment in infcmd.c:until_next_command says:

/* Proceed until we reach a different source line with pc greater than
   our current one or exit the function.  We skip calls in both cases.

   Note that eventually this command should probably be changed so
   that only source lines are printed out when we hit the breakpoint
   we set.  This may involve changes to wait_for_inferior and the
   proceed status code.  */

The documentation says:

     Continue running until a source line past the current line, in the
     current stack frame, is reached.  This command is used to avoid
     single stepping through a loop more than once.  It is like the
     `next' command, except that when `until' encounters a jump, it
     automatically continues execution until the program counter is
     greater than the address of the jump.

     This means that when you reach the end of a loop after single
     stepping though it, `until' makes your program continue execution
     until it exits the loop.  In contrast, a `next' command at the end
     of a loop simply steps back to the beginning of the loop, which
     forces you to step through the next iteration.

But then the documentation goes on to give an example that agrees with the
comment in until_next_command; it's about a PC greater than the current PC,
not a source line "past" the current line.  If the test at the end of a loop
has the line number of the beginning of the loop, an "until" at the end of
the loop will go to the earlier source line, and another "until" will take
you out of the loop (wow, there's lots of room for basic block reordering to
break this command...).

I think that the example and comment are correct, and only the documentation
is wrong (or at least confusing).  I'm not sure how to reword it though...

I noticed this problem because the mi-until.exp test case assumes the "past
the current line" behavior.  It tests a loop:
  while (i < 2)
    i++;
The ARM compiler I am testing marks the jump after the increment as being
associated with the first line of the loop rather than the second, which
makes good sense, but fails the test.

-- 
Daniel Jacobowitz
CodeSourcery, LLC