1// Copyright (c) 2013 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef BASE_DEBUG_PROC_MAPS_LINUX_H_
6#define BASE_DEBUG_PROC_MAPS_LINUX_H_
7
8#include <stdint.h>
9
10#include <string>
11#include <vector>
12
13#include "base/base_export.h"
14
15namespace base {
16namespace debug {
17
18// Describes a region of mapped memory and the path of the file mapped.
19struct MappedMemoryRegion {
20  enum Permission {
21    READ = 1 << 0,
22    WRITE = 1 << 1,
23    EXECUTE = 1 << 2,
24    PRIVATE = 1 << 3,  // If set, region is private, otherwise it is shared.
25  };
26
27  // The address range [start,end) of mapped memory.
28  uintptr_t start;
29  uintptr_t end;
30
31  // Byte offset into |path| of the range mapped into memory.
32  unsigned long long offset;
33
34  // Bitmask of read/write/execute/private/shared permissions.
35  uint8_t permissions;
36
37  // Name of the file mapped into memory.
38  //
39  // NOTE: path names aren't guaranteed to point at valid files. For example,
40  // "[heap]" and "[stack]" are used to represent the location of the process'
41  // heap and stack, respectively.
42  std::string path;
43};
44
45// Reads the data from /proc/self/maps and stores the result in |proc_maps|.
46// Returns true if successful, false otherwise.
47//
48// There is *NO* guarantee that the resulting contents will be free of
49// duplicates or even contain valid entries by time the method returns.
50//
51//
52// THE GORY DETAILS
53//
54// Did you know it's next-to-impossible to atomically read the whole contents
55// of /proc/<pid>/maps? You would think that if we passed in a large-enough
56// buffer to read() that It Should Just Work(tm), but sadly that's not the case.
57//
58// Linux's procfs uses seq_file [1] for handling iteration, text formatting,
59// and dealing with resulting data that is larger than the size of a page. That
60// last bit is especially important because it means that seq_file will never
61// return more than the size of a page in a single call to read().
62//
63// Unfortunately for a program like Chrome the size of /proc/self/maps is
64// larger than the size of page so we're forced to call read() multiple times.
65// If the virtual memory table changed in any way between calls to read() (e.g.,
66// a different thread calling mprotect()), it can make seq_file generate
67// duplicate entries or skip entries.
68//
69// Even if seq_file was changed to keep flushing the contents of its page-sized
70// buffer to the usermode buffer inside a single call to read(), it has to
71// release its lock on the virtual memory table to handle page faults while
72// copying data to usermode. This puts us in the same situation where the table
73// can change while we're copying data.
74//
75// Alternatives such as fork()-and-suspend-the-parent-while-child-reads were
76// attempted, but they present more subtle problems than it's worth. Depending
77// on your use case your best bet may be to read /proc/<pid>/maps prior to
78// starting other threads.
79//
80// [1] http://kernelnewbies.org/Documents/SeqFileHowTo
81BASE_EXPORT bool ReadProcMaps(std::string* proc_maps);
82
83// Parses /proc/<pid>/maps input data and stores in |regions|. Returns true
84// and updates |regions| if and only if all of |input| was successfully parsed.
85BASE_EXPORT bool ParseProcMaps(const std::string& input,
86                               std::vector<MappedMemoryRegion>* regions);
87
88}  // namespace debug
89}  // namespace base
90
91#endif  // BASE_DEBUG_PROC_MAPS_LINUX_H_
92