#ident	"%Z%%M%	%I%	%E% SMI"

lgroup option for pmap(1)

Jonathan Chew (Jonathan.Chew@sun.com)
Alexander Kolbasov (Alexander.Kolbasov@sun.com)

1. Summary

The PSARC case 2004/485 introduced extensions to the pmap(1) program for
observing lgroup memory placement.  The project team wants to amend this case
with few minor changes that modify the output format and the address range
specification:

- The lgroups backing the physical page is displayed in a single column as
  opposed to the multi-column output of the original proposal
- The address range format is extended to provide more flexibility.

2. Discussion.

The PSARC 2004/485 "lgroup option for pmap(1)" introduced the -L option for
the pmap(1) which displays lgroup information for each mapping and the -A
option to limit the potentially very long output of the pmap -L command.

We propose the following changes to PSARC 2004/485:

1) Change the output format to include a single column containing the lgroup
   ID

2) Do not allow -L option to be used with the -x option (as well as -S)

3) Extend -A address range specification

2.1. Output format changes.

The suggested output format had a single column for each lgroup and looked like
the following:

|    Example 6: Getting lgroup memory allocation per mapping
|
|    example$ pmap 704953
|    704953: /usr/sbin/nscd
|     Address	Kbytes	Lgrp 0	Lgrp 1	Lgrp 2	Mode	Mapped File
|    00010000      56K     56K       -       -  r-x--  /usr/sbin/nscd
|    0002E000       8K      8K       -       -  rwx--  /usr/sbin/nscd
|    00030000     560K    560K       -       -  rwx--    [ heap ]
|    FB4F8000      16K     16K       -       -  rw--R    [ anon ]
|    FB5F8000      16K     16K       -       -  rw--R    [ anon ]
|    FB6F8000      16K       -     16K       -  rw--R    [ stack tid=7954,lgrp=1 ]
|    FB7F8000      16K       -       -     16K  rw--R    [ stack tid=7953,lgrp=2 ]
|	.
|	.
|	.
|    FFBFE000       8K      8K       -       -  rw---    [ stack tid=1,lgrp=0 ]
|    total       3840K   2840K    128K    128K


This format has a variable number of columns depending on the type of machine
that the pmap command is running on.  On some modern systems, the total number
of lgroups may be quite large, considerably extending the width of the output.
Such wide and variable format is difficult to parse with automated tools like
awk(1) and perl(1).

We propose to change this format to a single column showing the lgroup ID for
each contiguous range of the virtual addresses belonging to the same segment
and lgroup, so the output will look like this:

     example$ pmap -L `pgrep nscd`
     100095: /usr/sbin/nscd
     00010000       8K r-x--   2 /usr/sbin/nscd
     00012000      48K r-x--   1 /usr/sbin/nscd
     0002E000       8K rwx--   2 /usr/sbin/nscd
     00030000      16K rwx--   2   [ heap ]
     00034000       8K rwx--   1   [ heap ]
         .
         .
         .
      total      2968K


This format is easier to interpret by both humans and automated tools like
awk(1) and perl(1) and is more compact. 

2.2. Options compatibility.

The original case suggested that the lgroup option to pmap(1) be available to
use with all the other pmap(1) options except -S.  We propose to amend this
statement and to limit the lgroup option to only work together with -r, -s, -l,
and -F.  Use of the lgroup option with the -x (which shows additional
information per mapping using extended maps) is not very useful since there is
no information about how these additional pieces of information (e.g. RSS and
Anon data) are split per lgroup.

2.3. Extended address range specification.

The third change is the extension of the address range specification proposed
in the original PSARC case.  The case proposed an address range either in the
form of <start address> or <start address>,<end address>.  We propose to extend
this syntax to specify "all addresses from the beginning to the given address"
and "all addresses from the given one to the end of address space".  The
proposed ways to specify this is by giving the address range as
"<start address>," or ",<end address>" respectively.

We also clarify the semantics of the address specified.  The address has the
granularity of a page with the lgroup option and the granularity of a segment
without it.  Any address within a page or a segment can be used to specify the
corresponding page/segment.  A single address matching the beginning of a
segment specifies the whole segment.

5. References.

PSARC 2004/485 lgroup option for pmap(1)

Project Web Page, including online documentation

http://www.opensolaris.org/os/community/performance/numa/observability/tools/pmap/

6. Updated manual pages

pmap(1).