Status field STATE in top(1) interactive mode

[Giorgos Keramidas]

On Sat, 7 Mar 2009 07:44:23 +0100, Polytropon <freebsd at edvax.de> wrote:
> Hi list,
>
> in order to find out why Opera often keeps hanging (doing nothing),
> often for several minutes, I checked its top(1) output.
>
> Reading "man top", I found the following explaination:
>
> 	[...] STATE is the current state (one of "START", "RUN"
> 	(shown as "CPUn" on SMP systems), "SLEEP", "STOP", "ZOMB",
> 	"WAIT", "LOCK"  or  the  event  on  which  the  process
> 	waits) [...]
>
> When Opera just hangs(TM) :-), it is in one of the states "ucond"
> or "umtxn" - and sucking up to 100% WCPU.
>
> Here is my question: Is there an explainative list that gives a
> clue about what this state indicates? Where are these "event[s]
> on which the process waits" documented?
>
> When I could guess, then I'd say that "ucond" means "unconditioned",
> "in no condition" (which would be a very strage state - the absense of
> any state), and "umtxn"... um... USB mass storage transmit number?  No
> idea.
>
> Other states that I see have a more descriptive name, such as "pause",
> "select" or "getblk" and even "kqread".

"umtx lock", "umtx", "umtxn", "umtxpi" and "umtxpp" are internal kernel
strings that are used to identify particular locks and wait conditions
where a process may block while running inside the kernel.  A recent
FreeBSD 8.0-CURRENT kernel shows:

  keramida at kobe:/usr/src/sys$ fgrep -r '"umtx' .
  ./kern/kern_umtx.c:static MALLOC_DEFINE(M_UMTX, "umtx", "UMTX queue memory");
  ./kern/kern_umtx.c:SYSCTL_NODE(_debug, OID_AUTO, umtx, CTLFLAG_RW, 0, "umtx debug");
  ./kern/kern_umtx.c:     umtx_pi_zone = uma_zcreate("umtx pi", sizeof(struct umtx_pi),
  ./kern/kern_umtx.c:                     mtx_init(&umtxq_chains[i][j].uc_lock, "umtxql", NULL,
  ./kern/kern_umtx.c:     mtx_init(&umtx_lock, "umtx lock", NULL, MTX_SPIN);
  ./kern/kern_umtx.c:                     msleep(uc, &uc->uc_lock, 0, "umtxqb", 0);
  ./kern/kern_umtx.c:                     error = umtxq_sleep(uq, "umtx", timo);
  ./kern/kern_umtx.c:                     error = umtxq_sleep(uq, "umtx", timo);
  ./kern/kern_umtx.c:                     error = umtxq_sleep(uq, "umtxn", timo);
  ./kern/kern_umtx.c:                              "umtxpi", timo);
  ./kern/kern_umtx.c:             error = umtxq_sleep(uq, "umtxpp", timo);
  ./kern/kern_umtx.c:             error = umtxq_sleep(uq, "umtxpp", 0);
  ./kern/subr_witness.c:  { "umtx lock", &lock_class_mtx_spin },
  keramida at kobe:/usr/src/sys$

AFAIK, there is no automated way of generating a list of kernel wait
states for all possible locks and wait conditions in the kernel, and
even if there was it would be a bit tricky to update the top(1) manpage
to automagically include all of them.  One of the reasons why this is a
relatively Sisyphean effort is that you can run often run an old top(1)
binary with both a matching kernel *and* a kernel that is a few
snapshots newer.  When this happens the new kernel may support wait
states that are not included in the top(1) manpage at all.