From 1f8e41d01966ef337bc252bffb181d0acc0c8751 Mon Sep 17 00:00:00 2001 From: Jim Warner Date: Thu, 17 Mar 2016 00:00:00 -0500 Subject: [PATCH] top: add additional memory information to the man page [ patch has been adapted expressly for newlib branch ] In response to Issue #21, the commit referred to below provided some much needed improvements and corrections to topic `3a. DESCRIPTIONS of Fields' in the man page. However, it assumed a reader possessed much background knowledge that may not, in truth, actually be present. So without, hopefully, insulting anyone's intelligence this patch offers an expanded discussion of some terms and concepts within a separate section under OVERVIEW. [ plus it affords an opportunity to incorporate that ] [ extremely useful table from Florent Bruneau's post ] Reference(s): commit 6a36bd7afd78195e8f5e556a5c28d58057e912d3 https://techtalk.intersec.com/2013/07/memory-part-1-memory-types/ Signed-off-by: Jim Warner --- top/top.1 | 103 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 93 insertions(+), 10 deletions(-) diff --git a/top/top.1 b/top/top.1 index 13c413ab..77b57507 100644 --- a/top/top.1 +++ b/top/top.1 @@ -42,6 +42,7 @@ .ds KA arrow key .ds KS scrolling key .ds MP physical memory +.ds MS swap file .ds MV virtual memory .ds NT \fBNote\fR: .ds PU CPU @@ -64,6 +65,7 @@ .ds Xc see the .ds XT See topic .ds Xt see topic +.ds XX See `OVERVIEW, Linux Memory Types' for additional details . .\" Document ///////////////////////////////////////////////////////////// .\" ---------------------------------------------------------------------- @@ -109,6 +111,10 @@ display and used when reading and writing a \*(CF. The remaining Table of Contents .nf + OVERVIEW + Operation + Startup Defaults + Linux Memory Types 1. COMMAND\-LINE Options 2. SUMMARY Display a. UPTIME and LOAD Averages @@ -263,6 +269,68 @@ All are explained in detail in the sections that follow. z \- color/mono On (show colors) .fi +.\" ...................................................................... +.SS Linux Memory Types +.\" ---------------------------------------------------------------------- +For our purposes there are three types of memory, and one is optional. +First is \*(MP, a limited resource where code and data must +reside when executed or referenced. +Next is the optional \*(MS, where modified (dirty) memory can be saved +and later retrieved if too many demands are made on \*(MP. +Lastly we have \*(MV, a nearly unlimited resource serving the +following goals: + +.nf + 1. abstraction, free from physical memory addresses/limits + 2. isolation, every process in a separate address space + 3. sharing, a single mapping can serve multiple needs + 4. flexibility, assign a virtual address to a file +.fi + +Regardless of which of these forms memory may take, all are managed as +pages (typically 4096 bytes) but expressed by default in \*(We as +KiB (kibibyte). +The memory discussed under topic `2c. MEMORY Usage' deals with \*(MP +and the \*(MS for the system as a whole. +The memory reviewed in topic `3. FIELDS / Columns Display' +embraces all three memory types, but for individual processes. + +For each such process, every memory page is restricted to a single +quadrant from the table below. +Both \*(MP and \*(MV can include any of the four, while the \*(MS only +includes #1 through #3. +The memory in quadrant #4, when modified, acts as its own dedicated \*(MS. + +.nf + \fBPrivate\fR | \fBShared\fR + \fB1\fR | \fB2\fR + \fBAnonymous\fR . stack | + . malloc() | + . brk()/sbrk() | + . mmap(PRIVATE, ANON) | . mmap(SHARED, ANON) + -----------------------+---------------------- + . mmap(PRIVATE, fd) | . mmap(SHARED, fd) + \fBFile-backed\fR . pgms/shared libs | + \fB3\fR | \fB4\fR +.fi + +The following may help in interpreting process level memory values displayed +as columns and discussed in topic `3a. DESCRIPTIONS of Fields'. +.nf + %MEM \- simply RES divided by total \*(MP + CODE \- the `pgms' portion of quadrant \fB3\fR + DATA \- the quadrant \fB1\fR portion of VIRT + RES \- anything occupying \*(MP (all quadrants) + SHR \- subset of RES (excludes \fB1\fR, includes all \fB2\fR & \fB4\fR, some \fB3\fR) + SWAP \- excludes quadrant \fB4\fR + USED \- simply the sum of RES and SWAP + VIRT \- everything in-use and/or reserved (all quadrants) +.fi + +\*(NT Even though program images and shared libraries are considered +\fIprivate\fR to a process, they will be accounted for as \fIshared\fR +(SHR) by the kernel. + .\" ---------------------------------------------------------------------- .SH 1. COMMAND-LINE Options .\" ---------------------------------------------------------------------- @@ -549,7 +617,9 @@ You toggle Irix/Solaris modes with the `I' \*(CI. .TP 4 2.\fB %MEM \*(Em Memory Usage (RES) \fR -A task's currently used share of available \*(MP. +A task's currently resident share of available \*(MP. + +\*(XX. .TP 4 3.\fB CGNAME \*(Em Control Group Name \fR @@ -583,8 +653,10 @@ any truncated data. .TP 4 5.\fB CODE \*(Em Code Size (KiB) \fR -The amount of \*(MP devoted to executable code, also known as -the Text Resident Set size or TRS. +The amount of \*(MP currently devoted to executable code, also known +as the Text Resident Set size or TRS. + +\*(XX. .TP 4 6.\fB COMMAND \*(Em Command\fB Name\fR or Command\fB Line \fR @@ -617,6 +689,8 @@ It is also known as the Data Resident Set or DRS. Such memory may not yet be mapped to \*(MP (RES) but will always be included in the \*(MV (VIRT) amount. +\*(XX. + .TP 4 8.\fB ENVIRON \*(Em Environment variables \fR Display all of the environment variables, if any, as seen by the @@ -707,13 +781,14 @@ And while the 2.6 kernel can be made mostly preemptible, it is not always so. 19.\fB RES \*(Em Resident Memory Size (KiB) \fR A subset of the virtual address space (VIRT) representing the non-swapped \*(MP a task is currently using. - It can include private anonymous pages, private pages mapped to files (including program images and shared libraries) plus shared anonymous pages. -All such memory is backed by the swap file represented separately under SWAP. +All such memory is backed by the \*(MS represented separately under SWAP. Lastly, this field may also include shared file-backed pages which, when -modified, act as a dedicated swap file and thus will never impact SWAP. +modified, act as a dedicated \*(MS and thus will never impact SWAP. + +\*(XX. .TP 4 20.\fB RUID \*(Em Real User Id \fR @@ -741,11 +816,12 @@ depending on \*(We's delay interval and nice value. .TP 4 23.\fB SHR \*(Em Shared Memory Size (KiB) \fR A subset of resident memory (RES) that may be used by other processes. - It will include shared anonymous pages and shared file-backed pages. It also includes \fIprivate\fR pages mapped to files representing program images and shared libraries. +\*(XX. + .TP 4 24.\fB SID \*(Em Session Id \fR A session is a collection of process groups (\*(Xa PGRP), @@ -791,7 +867,10 @@ The\fI saved\fR user name. .TP 4 29.\fB SWAP \*(Em Swapped Size (KiB) \fR -The non-resident portion of a task's address space. +The formerly resident portion of a task's address space written +to the \*(MS when \*(MP becomes over committed. + +\*(XX. .TP 4 30.\fB TGID \*(Em Thread Group Id \fR @@ -833,8 +912,10 @@ The\fI effective\fR user ID of the task's owner. .TP 4 36.\fB USED \*(Em Memory in Use (KiB) \fR -This field represents the non-swapped \*(MP a task has used (RES) plus -the non-resident portion of its address space (SWAP). +This field represents the non-swapped \*(MP a task is using (RES) plus +the swapped out portion of its address space (SWAP). + +\*(XX. .TP 4 37.\fB USER \*(Em User Name \fR @@ -846,6 +927,8 @@ The total amount of \*(MV used by the task. It includes all code, data and shared libraries plus pages that have been swapped out and pages that have been mapped but not used. +\*(XX. + .TP 4 39.\fB WCHAN \*(Em Sleeping in Function \fR This field will show the name of the kernel function in which the task