Home | History | Annotate | Download | only in docs 
      1 # Perfetto <-> Ftrace interoperability
      2 
      3 *** note
      4 **This doc is WIP**, stay tuned.
      5 <!-- TODO(primiano): write ftrace doc. -->
      6 ***
      7 
      8 This doc should:
      9 - Describe the ftrace trace_pipe_raw -> protobuf translation.
     10 - Describe how we deal with kernel ABI (in)stability and ftrace fields changing
     11   over kernel versions (we process `event/**/format files on-device`).
     12 - Describe how to generate ftrace protos (`tools/pull_ftrace_format_files.py`,
     13   `tools/udate_protos.py`)
     14 - Describe how session multiplexing works.
     15 - Describe the page-by-page scheduling algorithm that uses vmsplice()
     16 
     17 Code lives in [/src/ftrace_reader](/src/ftrace_reader/).
     18 
     19 From https://android-review.googlesource.com/c/platform/external/perfetto/+/603793/
     20 ```
     21 
     22   main thread                           [drain] [unblock]
     23                                         /:              |
     24                             post .-----' :              |
     25                                 /        :              v
     26   worker #0  [splice ...] [wakeup] [block ............] [splice]
     27                                          :
     28   worker #1  [splice ...]     [wakeup] [block ........] [splice]
     29                                          :
     30   worker #2  [splice ..........................................]
     31                                          :
     32                                          :
     33                                     drain period (100ms)
     34 
     35 In other words, the splice(2) system call is used to move data from
     36 the raw kernel ftrace pipe into an intermediate pipe at a page
     37 granularity. This call allows every per-cpu worker to sleep until there
     38 is at least one page of data available.
     39 
     40 When a worker wakes up, it will attempt to move as many pages as
     41 possible to its staging pipe (up to 64K, depending on the
     42 system's pipe buffer size) in a non-blocking way. After this, it
     43 will notify the main thread that data is available. This notification
     44 will block the calling worker until the main thread has drained the
     45 data.
     46 
     47 When at least one worker has woken up, we schedule a drain operation
     48 on the main thread for the next drain period (every 100ms by default).
     49 The drain operation parses ftrace data from the staging pipes of
     50 every worker having pending data. After this, each waiting worker is
     51 allowed to issue another call to splice(), restarting the cycle.
     52 ```
     53