OpenSolaris

lgroup option for pmap(1)

Summary

The PSARC case 2004/485 introduced extensions pmap(1) program to provide memory
placement visibility. The project team wants to ammend 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 and the address range format is
extended to provide more flexibility.

Discussion

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

We propose to add four changes to the PSARC 2004/485 case:

• Change the output format to include a single column containing the lgroup ID.
• Do not allow -L option together with -x option.
• Extend -A address range specification.

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
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
     100107: /usr/sbin/nscd
     08046000       8K rw--   1   [ stack ]
     08050000      48K r-x--    1 /usr/sbin/nscd
     0806C000       8K rw--   1 /usr/sbin/nscd
     0806E000     132K rw--   1   [ heap ]
     0808F000       4K rw--   3   [ heap ]
     08090000       4K rw--   -   [ heap ]
     08091000       4K rw--   3   [ heap ]
     .
     .
     .
      total      4284K
    

This format is easy to interpret by both humans and automated tools like awk(1)
and perl(1) and is more compact. Virtual addresses that are unmapped show dash
instead of lgroup ID in the corresponding column.

Options compatibility

Also, the original case suggested that the lgroup option to pmap(1) will be
available to use with all the other pmap(1) options except -S. We propose to
ammend this statement and to limit the lgroup option to only work together with 

, -s 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.

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". This is achieved
by allowing address ranges in the <start address>, and ,<end address> forms.

We also clarify the semantics of the address specified. The address has the
granularity of a page with the -L 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.

References

PSARC 2004/485 lgroup option for pmap(1)

Updated manual pages

pmap(1)