How to get around in the source code tree?

There exists a number of tools (some proprietary, some FOSS, some with IDEs..etc. Which one is the best?...

You might be aware of a number of tools that gives you easy access to source trees. But the one I have found best is, without surprise vim/emacs and grep. Mix it with cscope and tags, you don't need anything else.

You can also browse the kernel with lxr.

cscope

Set up cscope with the make target cscope

$ pwd
/home/om/src
$ make cscope
$ ls cscope*
308K cscope.files   24M cscope.in.out  134M cscope.out  190M cscope.po.out
$ cscope -d    # starts cscope

ctags

Set up ctags with the make target tags

$ pwd
/home/om/src
$ make tags
$ ls tags
61M tags

Once you launch [g]vim editor (emacs should work too, I don't know much about it), make sure tags are set right.

<ESC>:set tags?
  tags=./tags,./TAGS,tags,TAGS

GREP and Regular Expressions

REs pack a lot of power. The best reason for using them is, that it is not easy. Secondly, the more REs you use, the more familiar with them you grow. Moreover, you would grow more familiar with the source code too.

For example, I want to get to the definition of struct task_struct. I can use cscope, and in my setup, it returns around 30 entries. I can go through all and finally find out it is defined in sched.h. Similarly, using ctags, I get almost the same number of entries.

Now since I am trying to use grep, let's see how many entries can I see using grep.

$ type findc
findc is a function
findc ()
{
    find $1 -name '*.[ch]'
}
[om@testserv ~/src]
$ findc | xargs grep task_struct | wc -l
3738

3738 lines?... if you think searching among 30 lines is a lot better, I agree with you. But wait a bit, what I did was not really correct. I just searched for occurrences of task_struct instead of definition. If I can't reduce the number of lines I have to search for definition to around 2-3, there may not much point to using grep. How can I grep for definition of task_struct? Here is where REs comes in handy.

BTW, findc is a function I use to avoid typing some number of characters.

Let's see, we can reasonably assume that the keyword struct would precede the task_struct where it is defined. So, let's grep for that.

$ findc | xargs grep -EnH "struct task_struct" | wc -l
3456

That is not helping either. The reason is every function definition, extern declarations ..etc of task_struct would have the keyword struct preceding it.

Hmm... Okay. In definition of task_struct, { should succeed task_struct, i.e., the RE should be struct task_struct {. Is that correct? Let's see.

$ findc | xargs grep -EnH "struct task_struct {"
./include/linux/sched.h:947:struct task_struct {

And you got it. Exactly where it is defined.

The RE I used is not exactly correct. There could be any number of whitespaces between keywords. Even though Linux kernel adheres to its coding standards, a generic RE would look like,

$ findc | xargs grep -EnH "\W*struct\W+task_struct\W*{"
./include/linux/sched.h:947:struct task_struct {

This RE means, "0 or more non-word characters followed by struct, followed by 1 or more non-word characters followed by task_struct followed by 0 or more non-word characters followed by {"

Finding functions

Finding functions is a little more difficult, but it is great to write REs to find them. Let's try finding the function find_pid

[om@testserv ~/src]
$ findc | xargs grep -EHn "find_pid" | wc -l
24

Assuming that I saw this function while browsing the code, I would know it takes an integer/long argument and returns a struct pid *. Let's formulate an RE to find this.

$ findc | xargs grep -EnH "find_pid\W*\(((int)|(long))\W+"
./include/linux/pid.h:90:extern struct pid *FASTCALL(find_pid(int nr));
./kernel/pid.c:238:struct pid * fastcall find_pid(int nr)

The RE means "find_pid followed by 0 or more non-word characters followed by ( followed by int or long followed by 1 or more non-word characters". This is not a complete expression for a function, but it does find you the function definition.

gtags / global

Another tool that's quite useful when searching the code is the cli tool global. It requires gtags to be generated with:

[agatha@guidai linux]$ make gtags

Then you can use global to search for code, functions, symbols, and even grep-like regex on an indexed database. i.e.

Find a function declaration

[agatha@guidai linux]$ global do_mount
fs/namespace.c

To see file contents as well you can use the -x flag:

[agatha@guidai linux]$ global -x do_mount
do_mount         3838 fs/namespace.c   long do_mount(const char *dev_name, const char __user *dir_name,

Macros and grep-like behavior

Beware that your function might be declared within a macro context, so you might need to account for that. This is a case where global grep-like mode (-g and possibly -E) might be useful. For instance:

[agatha@guidai linux]$ global -x bpf_tcp_raw_check_syncookie_ipv4
[agatha@guidai linux]$

returns nothing, while:

[agatha@guidai linux]$ global -xg bpf_tcp_raw_check_syncookie_ipv4
bpf_tcp_raw_check_syncookie_ipv4 5678 include/uapi/linux/bpf.h  * long bpf_tcp_raw_check_syncookie_ipv4(struct iphdr *iph, struct tcphdr *th)
bpf_tcp_raw_check_syncookie_ipv4 7861 net/core/filter.c BPF_CALL_2(bpf_tcp_raw_check_syncookie_ipv4, struct iphdr *, iph,
bpf_tcp_raw_check_syncookie_ipv4 7870 net/core/filter.c static const struct bpf_func_proto bpf_tcp_raw_check_syncookie_ipv4_proto = {
bpf_tcp_raw_check_syncookie_ipv4 7871 net/core/filter.c         .func           = bpf_tcp_raw_check_syncookie_ipv4,
bpf_tcp_raw_check_syncookie_ipv4 8267 net/core/filter.c                 return &bpf_tcp_raw_check_syncookie_ipv4_proto;
bpf_tcp_raw_check_syncookie_ipv4 8326 net/core/filter.c                 return &bpf_tcp_raw_check_syncookie_ipv4_proto;
bpf_tcp_raw_check_syncookie_ipv4 5677 tools/include/uapi/linux/bpf.h  * long bpf_tcp_raw_check_syncookie_ipv4(struct iphdr *iph, struct tcphdr *th)
bpf_tcp_raw_check_syncookie_ipv4  740 tools/testing/selftests/bpf/progs/xdp_synproxy_kern.c             err = bpf_tcp_raw_check_syncookie_ipv4(hdr->ipv4, hdr->tcp);

Returns possibly too much, but:

[agatha@guidai linux]$ global -xgE "BPF_CALL_[0-5]\(bpf_tcp_raw_check_syncookie_ipv4"
BPF_CALL_[0-5]\(bpf_tcp_raw_check_syncookie_ipv4 7861 net/core/filter.c BPF_CALL_2(bpf_tcp_raw_check_syncookie_ipv4, struct iphdr *, iph,

Returns the exact function declaration of bpf_tcp_raw_check_syncookie_ipv4()

Find a Function Reference

You can find a reference to a function (i.e. a function call) by using the -r flag. i.e.

$ global -xr do_mount
do_mount         4055 fs/namespace.c    ret = do_mount(kernel_dev, dir_name, kernel_type, flags, options);
do_mount          117 include/linux/mount.h extern long do_mount(const char *, const char __user *,

Find a Symbol

You can also find symbols with -s, i.e.

[agatha@guidai linux]$ global -xs acl_skb
acl_skb           819 drivers/bluetooth/btusb.c         struct sk_buff *acl_skb;
acl_skb          1052 drivers/bluetooth/btusb.c         dev_kfree_skb_irq(data->acl_skb);
acl_skb          1053 drivers/bluetooth/btusb.c         data->acl_skb = NULL;
acl_skb          1148 drivers/bluetooth/btusb.c         skb = data->acl_skb;
acl_skb          1193 drivers/bluetooth/btusb.c         data->acl_skb = skb;