在正式地介紹 ply 的語法之前，先看看一個例子來展示一下如何使用他來追蹤程式碼。以下要追蹤的是關於 Raspberry Pi 3 Model B 板子上的那個綠色 LED，看看背後是核心中的哪些功能在控制他的明滅。

Step 1：猜測可能有關的子系統

講既然是個 LED，可能會想猜背後是某種 GPIO。接下來的目標就是是試試看追蹤核心中跟 GPIO 有關的函式，然後看看 LED 在開啟跟關閉時，追縱到的東西有沒有不同？就可以推測是否追蹤到正確的東西。

Step 2：找到有關那個子系統的函數

目前我們知道準備要追蹤的是跟 GPIO 有關的函式，不過這樣還是有點模糊，因為現在根本不知道這些函數長什麼樣子？或是整個子系統的大致架構如何？這時就可以去核心的文件找一些提示。比如說 General Purpose Input/Output (GPIO) 這個章節中，就介紹了 GPIO 子系統。不過，這時可以注意到 Introduction 下有一段這樣的話：

...The remainder of this document applies to the new descriptor-based interface. gpio-legacy.txt contains the same information applied to the legacy integer-based interface.

也就是說，核心中有另外一套遺留的 GPIO 架構。再閱讀一下文件，可以在 GPIO Descriptor Consumer Interface 一章節中，可以知道新的 GPIO 的架構中，是以 gpio_desc 作為描述 GPIO 的資料結構，並且相關的函式的命名，都是 gpiod_* 的形式。

有了這個之後，就知道要去找哪些可能跟 GPIO 有關的函式了。而這剛好可以用 /proc 中提供資訊去看看。

Step 2-1：/proc

/proc 是一個虛擬的檔案系統，他會把 Linux 的一些核心資料結構揭露出來，讓使用者可以用讀寫檔案的方式讀取這些核心的資料結構的內容。比如說 ls 一下看看裡面有什麼檔案：

$ ls /proc

可以發現類似以下的輸出：

1     183  366  60   8            fb             partitions
10    184  373  600  80           filesystems    sched_debug
100   19   374  605  81           fs             schedstat
1010  2    378  606  82           interrupts     self
1035  20   380  61   83           iomem          slabinfo
1049  23   395  62   883          ioports        softirqs
1050  230  4    63   9            irq            stat
1052  239  409  64   942          kallsyms       swaps
1053  24   444  65   945          keys           sys
108   240  457  66   asound       key-users      sysrq-trigger
11    25   466  661  buddyinfo    kmsg           sysvipc
116   28   477  664  bus          kpagecgroup    thread-self
12    29   483  67   cgroups      kpagecount     timer_list
13    3    484  68   cmdline      kpageflags     tty
133   30   485  69   consoles     latency_stats  uptime
14    306  52   70   cpu          loadavg        version
145   32   53   71   cpuinfo      locks          vmallocinfo
147   33   54   73   crypto       meminfo        vmstat
15    34   55   75   devices      misc           zoneinfo
165   346  57   76   device-tree  modules
178   348  58   77   diskstats    mounts
18    35   59   78   driver       net
181   363  6    79   execdomains  pagetypeinfo

可以發現裡面有很的關於作業系統本身的資訊。像 device-tree(一種描述周邊硬體的語言)、cpuinfo (cpu 供應商提供的資訊)，還有不同 pid 的行程對應的相關資訊等等。而這邊有興趣的是 kallsyms，裡面有核心的符號表，以及核心模組中提供出來的函數。

Step 2-2：/proc/kallsyms

/proc/kallsym 裡面是核心的符號表。可以從這裡面的內容，搭配核心的原始程式碼，藉由名字搭配核心的原始程式碼及文件，去推測哪個子系統可能用到哪些函數。可以先看看裡面有什麼：

$ cat /proc/kallsyms

會出線一大堆函數的名稱。為了方便，可以善用 grep 跟 less (或是把 tmux 設置成滑鼠可以捲動等等)。比如說：把 cat 的「導向」給 less，這樣就可以用上下鍵捲動：

$ cat /proc/kallsyms | less

又比如說如果想要找 GPIO 相關的函式，可以試著把 cat 的輸出塞給 grep 搜尋，接著再塞給less 以方便捲動閱讀：

$ cat /proc/kallsyms | grep gpio | less

預計出現類似以下的輸出：

00000000 T pinctrl_find_gpio_range_from_pin_nolock
00000000 T pinctrl_add_gpio_range
00000000 T pinctrl_add_gpio_ranges
00000000 T pinctrl_find_gpio_range_from_pin
00000000 T pinctrl_remove_gpio_range

[...]

00000000 T pinctrl_find_and_add_gpio_range
00000000 T pinmux_can_be_used_for_gpio
00000000 T pinmux_request_gpio
00000000 T pinmux_free_gpio
00000000 T pinmux_gpio_direction
00000000 t bcm2835_gpio_irq_config
00000000 t bcm2835_pmx_gpio_set_direction

[...]

00000000 t bcm2835_gpio_direction_output
00000000 t bcm2835_gpio_direction_input
00000000 t bcm2835_pmx_gpio_disable_free
00000000 T desc_to_gpio
00000000 T gpiod_to_chip
00000000 T gpiochip_line_is_valid
00000000 T gpiochip_get_data

[...]

00000000 T gpiochip_lock_as_irq
00000000 T gpiochip_irq_domain_activate
00000000 t gpiodevice_release
00000000 T gpiod_set_debounce
00000000 T gpiod_set_transitory
00000000 T gpiod_is_active_low
00000000 T gpiod_cansleep
00000000 T gpiod_set_consumer_name

[...]

就可以過濾出跟 GPIO 有關的可能函數了。

Step 2-3：插入 kprobe

比如說：有一大類函數是 pinctrl_ 開頭的，那就可以在他們上面插上 kprobe，這是一個核心當中的基礎設施，可以在執行到某一道指令前，觸發其他的程式片段，然後再繼續執行該指令。現在插上 kprobe，看看他們在閃燈時做了什麼：

$ sudo ply 'kprobe:pinctrl_* { @[stack] = count(); }'

根據 ply 的文件，可以用萬用字元 * 來一口氣把 kprobe 插在所有名字以 pinctrl_ 為開頭的函數中。而不難猜測上述的程式用意是：從給每一個名字前綴是 pinctrl_ 的函數，都插上 kprobe。而當 kprobe 被觸發時，要做的事情是統計不同的「呼叫堆疊」出現了幾次。

執行上述指令，會得到以下的輸出：

ply: active

在執行一段時間 (大概數秒) 之後，按下 Ctrl + c 終止 ply，會發現以下的輸出：

^Cply: deactivating

@:

這時就發先沒有輸出。接著試試開頭為 bcm2835_gpio_* 的函數，也會發現有類似的結果。再試到 gpiod_* 名字為開頭的相關函數時：

$ sudo ply 'kprobe:gpiod_* { @[stack] = count(); }'

就出現了有趣的東西：

ply: active
^Cply: deactivating

@:
{ 
	gpiod_set_value_nocheck
	gpio_led_set+120
	gpio_led_set_blocking+24
	set_brightness_delayed+140
	process_one_work+592
	worker_thread+96
	kthread+368
	ret_from_fork+20
 }: 10
{ 
	gpiod_set_raw_value_commit
	gpiod_set_value_cansleep+56
	gpio_led_set+120
	gpio_led_set_blocking+24
	set_brightness_delayed+140
	process_one_work+592
	worker_thread+96
	kthread+368
	ret_from_fork+20
 }: 10
{ 
	gpiod_set_value_cansleep
	gpio_led_set_blocking+24
	set_brightness_delayed+140
	process_one_work+592
	worker_thread+96
	kthread+368
	ret_from_fork+20
 }: 10

開始有呼叫堆疊的統計出現了！這其實也不奇怪，因為剛剛從核心 GPIO 子系統的文件可以知道：新的 GPIO 子系統是使用 gpio descriptor 的 gpiod_* 系列函數作為控制，而這大類函數的命名大致上都是以 gpiod_ 為開頭。

這邊補充一個工具：如果是使用 SSH 操縱 Raspberry Pi 的話，可以考慮使用 tmux 這個工具。tmux 是個 terminal multiplexer，可以把同一個 session 的終端機畫面用分割的方式集中在一起，像下面這樣：

這樣就可以一邊查 kallsyms，一邊執行 ply，一邊做其他的事情，不用因為視窗被 ply 阻塞而沒辦法做其他事情。

Step 3：關 LED 並重新追蹤

為了更近一步證實這個呼叫是用來控制上面那顆綠色的 LED 燈的，可以透過讀寫 sysfs 的檔案控制 他。修改 sysfs 中的數值把他的亮度調成 0：

$ sudo su
# echo 0 >/sys/class/leds/led0/brightness
# exit

接著再執行一次 ply：

$ sudo ply 'kprobe:gpiod_* { @[stack] = count(); }'

一段時間之後按下 Ctrl + c 終止 ply，就會發現這次沒有東西了：

ply: active
^Cply: deactivating

@:

然後也可以用肉眼觀察發現綠燈都不會亮了。因此可以更加確認這確實是用來控制綠燈的。順帶一提，如果要把綠燈的亮度設定回原來的樣子，可以用：

$ sudo su
# echo mmc0 >/sys/class/leds/led0/trigger
# exit

肉眼就可以發現綠燈又重新發亮了。