1README for the glibc Python pretty printers 2=========================================== 3 4Pretty printers are gdb extensions that allow it to print useful, human-readable 5information about a program's variables. For example, for a pthread_mutex_t 6gdb would usually output something like this: 7 8(gdb) print mutex 9$1 = { 10 __data = { 11 __lock = 22020096, 12 __count = 0, 13 __owner = 0, 14 __nusers = 0, 15 __kind = 576, 16 __spins = 0, 17 __elision = 0, 18 __list = { 19 __prev = 0x0, 20 __next = 0x0 21 } 22 }, 23 __size = "\000\000P\001", '\000' <repeats 12 times>, "@\002", '\000' <repeats 21 times>, 24 __align = 22020096 25} 26 27However, with a pretty printer gdb will output something like this: 28 29(gdb) print mutex 30$1 = pthread_mutex_t = { 31 Type = Normal, 32 Status = Not acquired, 33 Robust = No, 34 Shared = No, 35 Protocol = Priority protect, 36 Priority ceiling = 42 37} 38 39Before printing a value, gdb will first check if there's a pretty printer 40registered for it. If there is, it'll use it, otherwise it'll print the value 41as usual. Pretty printers can be registered in various ways; for our purposes 42we register them for the current objfile by calling 43gdb.printing.register_pretty_printer(). 44 45Currently our printers are based on gdb.RegexpCollectionPrettyPrinter, which 46means they'll be triggered if the type of the variable we're printing matches 47a given regular expression. For example, MutexPrinter will be triggered if 48our variable's type matches the regexp '^pthread_mutex_t$'. 49 50Besides the printers themselves, each module may have a constants file which the 51printers will import. These constants are generated from C headers during the 52build process, and need to be in the Python search path when loading the 53printers. 54 55 56Installing and loading 57---------------------- 58 59The pretty printers and their constant files may be installed in different paths 60for each distro, though gdb should be able to automatically load them by itself. 61When in doubt, you can use the 'info pretty-printer' gdb command to list the 62loaded pretty printers. 63 64If the printers aren't automatically loaded for some reason, you should add the 65following to your .gdbinit: 66 67python 68import sys 69sys.path.insert(0, '/path/to/constants/file/directory') 70end 71 72source /path/to/printers.py 73 74If you're building glibc manually, '/path/to/constants/file/directory' should be 75'/path/to/glibc-build/submodule', where 'submodule' is e.g. nptl. 76 77 78Testing 79------- 80 81The pretty printers come with a small test suite based on PExpect, which is a 82Python module with Expect-like features for spawning and controlling interactive 83programs. Each printer has a corresponding C program and a Python script 84that uses PExpect to drive gdb through the program and compare its output to 85the expected printer's. 86 87The tests run on the glibc host, which is assumed to have both gdb and PExpect; 88if any of those is absent the tests will fail with code 77 (UNSUPPORTED). 89Native builds can be tested simply by doing 'make check'; cross builds must use 90cross-test-ssh.sh as test-wrapper, like this: 91 92make test-wrapper='/path/to/scripts/cross-test-ssh.sh user@host' check 93 94(Remember to share the build system's filesystem with the glibc host's through 95NFS or something similar). 96 97Running 'make check' on a cross build will only compile the test programs, 98without running the scripts. 99 100 101Adding new pretty printers 102-------------------------- 103 104Adding new pretty printers to glibc requires following these steps: 105 1061. Identify which constants must be generated from C headers, and write the 107corresponding .pysym file. See scripts/gen-as-const.py for more information 108on how this works. The name of the .pysym file must be added to the 109'gen-py-const-headers' variable in your submodule's Makefile (without the .pysym 110extension). 111 1122. Write the pretty printer code itself. For this you can follow the gdb 113Python API documentation, and use the existing printers as examples. The printer 114code must import the generated constants file (which will have the same name 115as your .pysym file). The names of the pretty printer files must be added 116to the 'pretty-printers' variable in your submodule's Makefile (without the .py 117extension). 118 1193. Write the unit tests for your pretty printers. The build system calls each 120test script passing it the paths to the test program source, the test program 121binary, and the printer files you added to 'pretty-printers' in the previous 122step. The test scripts, in turn, must import scripts/test_printers_common 123and call the init_test function passing it, among other things, the name of the 124set of pretty printers to enable (as seen by running 'info pretty-printer'). 125You can use the existing unit tests as examples. 126 1274. Add the names of the pretty printer tests to the 'tests-printers' variable 128in your submodule's Makefile (without extensions). In addition, for each test 129program you must define a corresponding CFLAGS-* and CPPFLAGS-* variable and 130set it to $(CFLAGS-printers-tests) to ensure they're compiled correctly. For 131example, test-foo-printer.c requires the following: 132 133CFLAGS-test-foo-printer.c := $(CFLAGS-printers-tests) 134CPPFLAGS-test-foo-printer.c := $(CFLAGS-printers-tests) 135 136Finally, if your programs need to be linked with a specific library, you can add 137its name to the 'tests-printers-libs' variable in your submodule's Makefile. 138 139 140Known issues 141------------ 142 143* Pretty printers are inherently coupled to the code they're targetting, thus 144any changes to the target code must also update the corresponding printers. 145On the plus side, the printer code itself may serve as a kind of documentation 146for the target code. 147 148* There's no guarantee that the information the pretty printers provide is 149complete, i.e. some details might be left off. For example, the pthread_mutex_t 150printers won't report whether a thread is spin-waiting in an attempt to acquire 151the mutex. 152 153* Older versions of the gdb Python API have a bug where 154gdb.RegexpCollectionPrettyPrinter would not be able to get a value's real type 155if it was typedef'd. This would cause gdb to ignore the pretty printers for 156types like pthread_mutex_t, which is defined as: 157 158typedef union 159{ 160 ... 161} pthread_mutex_t; 162 163This was fixed in commit 1b588015839caafc608a6944a78aea170f5fb2f6, and released 164as part of gdb 7.8. However, typedef'ing an already typedef'd type may cause 165a similar issue, e.g.: 166 167typedef pthread_mutex_t mutex; 168mutex a_mutex; 169 170Here, trying to print a_mutex won't trigger the pthread_mutex_t printer. 171 172* The test programs must be compiled without optimizations. This is necessary 173because the test scripts rely on the C code structure being preserved when 174stepping through the programs. Things like aggressive instruction reordering 175or optimizing variables out may make this kind of testing impossible. 176