doc_getProcMem.txt

About getProcMem.py

1. Objective: Assess how memory is being used in ChromeOS

TODO
2. Background

3. Script
NOTE: script must be run as root, as some files have only root access
3.1 smaps
/proc/<pid>/smaps gives a detailed per page mapping memory usage of a
process. Further information on smaps can be found in reference.txt.
The script uses smaps to sum the total memory being used by each process
per type of memory (PSS, RSS, etc). Furthermore, it is also able to
summarize how each page mapping is being used per process per type of
memory.

3.1.1 getSmaps()
Returns tuple with PID:memory_type dictionary and page:PID dictionary,
divided into Chrome and Non-Chrome processes.

3.1.2 PID:memory_type dictionary
Possess signature {PID:{memory type:how much memory is used}}

3.1.3 page:PID dictionary
Possess signature {page mapping address:{PIDs using it:{memory type:
how much memory is used}}}
Though this dictionary is implemented, it is not being currently used
in other parts of the code.

3.1.4 isChrome()
Function responsible for deciding whether a process is a Chrome processes
or not. This is done through checking if /proc/<pid>/comm starts with
"chrome". It was found through examination that all processes in
Chrome's about:memory are reported as being a Chrome processes through
this function. However, it was discovered there is a process being reported
as Chrome which does not show up in about:memory. This process has PID
equal to one less than the chrome zygote, and, as a guess, should probably
be the sandbox zygote.
TODO: Figure out what this process is.

3.1.5 Options
3.1.5.1 proc
proc is referent to the directory containing all the information required
by getSmaps to work. It defaults to "/proc". If a test directory is created,
it should contain the PIDs as subfolders containing smaps and comm files.

3.1.5.2 chrome_only
This option, when set True, disables the data collection and processing
for non-Chrome processes, besides for finding their PIDs. This decreases
the execution time significantly. It defaults to False

3.2 Total Memory usage in the System
/proc/meminfo gives a overview of how the memory is used. This info is mostly
used to see the total available memory of the system.
TODO: document how meminfo works
TODO: use meminfo to confirm memory usage report by other tools

3.2.1 getMemInfo()
See docstring

3.2.2 Options
"source" directory must have a meminfo file in it. Defaults to "/proc"

3.3 GPU memory
GPU holds memory into SHMEM. In order to find how much of that memory belongs
to the GPU, it is required to check inside
/sys/kernel/debug/dri/0/i915_gem_objects. This gives back a file containing
information regarding the objects that the GPU holds, what has gone by the gtt
and the current amount of objects in the gtt, among other information. Note:
this file is specific to ChromeOS.

3.3.1 getGPUMem()
Refer to docstring

3.3.2 i915_gem_objects
First line = total objects held by GPU
Second line = objects that have passed by the gtt; inside [] = currently in the
gtt
Sample Output:
374 objects, 289271808 bytes
336 [316] objects, 285745152 [219258880] bytes in gtt
  20 [17] active objects, 17235968 [6225920] bytes
  6 [6] pinned objects, 12640256 [12640256] bytes
  310 [293] inactive objects, 255868928 [200392704] bytes
  0 [0] freed objects, 0 [0] bytes
6 pinned mappable objects, 12640256 bytes
270 fault mappable objects, 177713152 bytes
536866816 [268435456] gtt total

3.3.3 Total GPU memory
TODO: find out how total memory held by GPU, current objects in the gtt and
total memory by the GPU process shown in smaps correlate.
Sample Output, when tabs of google maps + WebGL experiment open:
Smaps results, in kBs
PID          Pss     Chrome %      Total %         Type
22737       123311        9.912        6.372  gpu-process

GPU memory usage, in kBs
Current GPU memory use: 214120
Total memory allocated for the GPU: 282494