relay.rst 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501
  1. .. SPDX-License-Identifier: GPL-2.0
  2. ==================================
  3. relay interface (formerly relayfs)
  4. ==================================
  5. The relay interface provides a means for kernel applications to
  6. efficiently log and transfer large quantities of data from the kernel
  7. to userspace via user-defined 'relay channels'.
  8. A 'relay channel' is a kernel->user data relay mechanism implemented
  9. as a set of per-cpu kernel buffers ('channel buffers'), each
  10. represented as a regular file ('relay file') in user space. Kernel
  11. clients write into the channel buffers using efficient write
  12. functions; these automatically log into the current cpu's channel
  13. buffer. User space applications mmap() or read() from the relay files
  14. and retrieve the data as it becomes available. The relay files
  15. themselves are files created in a host filesystem, e.g. debugfs, and
  16. are associated with the channel buffers using the API described below.
  17. The format of the data logged into the channel buffers is completely
  18. up to the kernel client; the relay interface does however provide
  19. hooks which allow kernel clients to impose some structure on the
  20. buffer data. The relay interface doesn't implement any form of data
  21. filtering - this also is left to the kernel client. The purpose is to
  22. keep things as simple as possible.
  23. This document provides an overview of the relay interface API. The
  24. details of the function parameters are documented along with the
  25. functions in the relay interface code - please see that for details.
  26. Semantics
  27. =========
  28. Each relay channel has one buffer per CPU, each buffer has one or more
  29. sub-buffers. Messages are written to the first sub-buffer until it is
  30. too full to contain a new message, in which case it is written to
  31. the next (if available). Messages are never split across sub-buffers.
  32. At this point, userspace can be notified so it empties the first
  33. sub-buffer, while the kernel continues writing to the next.
  34. When notified that a sub-buffer is full, the kernel knows how many
  35. bytes of it are padding i.e. unused space occurring because a complete
  36. message couldn't fit into a sub-buffer. Userspace can use this
  37. knowledge to copy only valid data.
  38. After copying it, userspace can notify the kernel that a sub-buffer
  39. has been consumed.
  40. A relay channel can operate in a mode where it will overwrite data not
  41. yet collected by userspace, and not wait for it to be consumed.
  42. The relay channel itself does not provide for communication of such
  43. data between userspace and kernel, allowing the kernel side to remain
  44. simple and not impose a single interface on userspace. It does
  45. provide a set of examples and a separate helper though, described
  46. below.
  47. The read() interface both removes padding and internally consumes the
  48. read sub-buffers; thus in cases where read(2) is being used to drain
  49. the channel buffers, special-purpose communication between kernel and
  50. user isn't necessary for basic operation.
  51. One of the major goals of the relay interface is to provide a low
  52. overhead mechanism for conveying kernel data to userspace. While the
  53. read() interface is easy to use, it's not as efficient as the mmap()
  54. approach; the example code attempts to make the tradeoff between the
  55. two approaches as small as possible.
  56. klog and relay-apps example code
  57. ================================
  58. The relay interface itself is ready to use, but to make things easier,
  59. a couple simple utility functions and a set of examples are provided.
  60. The relay-apps example tarball, available on the relay sourceforge
  61. site, contains a set of self-contained examples, each consisting of a
  62. pair of .c files containing boilerplate code for each of the user and
  63. kernel sides of a relay application. When combined these two sets of
  64. boilerplate code provide glue to easily stream data to disk, without
  65. having to bother with mundane housekeeping chores.
  66. The 'klog debugging functions' patch (klog.patch in the relay-apps
  67. tarball) provides a couple of high-level logging functions to the
  68. kernel which allow writing formatted text or raw data to a channel,
  69. regardless of whether a channel to write into exists or not, or even
  70. whether the relay interface is compiled into the kernel or not. These
  71. functions allow you to put unconditional 'trace' statements anywhere
  72. in the kernel or kernel modules; only when there is a 'klog handler'
  73. registered will data actually be logged (see the klog and kleak
  74. examples for details).
  75. It is of course possible to use the relay interface from scratch,
  76. i.e. without using any of the relay-apps example code or klog, but
  77. you'll have to implement communication between userspace and kernel,
  78. allowing both to convey the state of buffers (full, empty, amount of
  79. padding). The read() interface both removes padding and internally
  80. consumes the read sub-buffers; thus in cases where read(2) is being
  81. used to drain the channel buffers, special-purpose communication
  82. between kernel and user isn't necessary for basic operation. Things
  83. such as buffer-full conditions would still need to be communicated via
  84. some channel though.
  85. klog and the relay-apps examples can be found in the relay-apps
  86. tarball on http://relayfs.sourceforge.net
  87. The relay interface user space API
  88. ==================================
  89. The relay interface implements basic file operations for user space
  90. access to relay channel buffer data. Here are the file operations
  91. that are available and some comments regarding their behavior:
  92. =========== ============================================================
  93. open() enables user to open an _existing_ channel buffer.
  94. mmap() results in channel buffer being mapped into the caller's
  95. memory space. Note that you can't do a partial mmap - you
  96. must map the entire file, which is NRBUF * SUBBUFSIZE.
  97. read() read the contents of a channel buffer. The bytes read are
  98. 'consumed' by the reader, i.e. they won't be available
  99. again to subsequent reads. If the channel is being used
  100. in no-overwrite mode (the default), it can be read at any
  101. time even if there's an active kernel writer. If the
  102. channel is being used in overwrite mode and there are
  103. active channel writers, results may be unpredictable -
  104. users should make sure that all logging to the channel has
  105. ended before using read() with overwrite mode. Sub-buffer
  106. padding is automatically removed and will not be seen by
  107. the reader.
  108. sendfile() transfer data from a channel buffer to an output file
  109. descriptor. Sub-buffer padding is automatically removed
  110. and will not be seen by the reader.
  111. poll() POLLIN/POLLRDNORM/POLLERR supported. User applications are
  112. notified when sub-buffer boundaries are crossed.
  113. close() decrements the channel buffer's refcount. When the refcount
  114. reaches 0, i.e. when no process or kernel client has the
  115. buffer open, the channel buffer is freed.
  116. =========== ============================================================
  117. In order for a user application to make use of relay files, the
  118. host filesystem must be mounted. For example::
  119. mount -t debugfs debugfs /sys/kernel/debug
  120. .. Note::
  121. the host filesystem doesn't need to be mounted for kernel
  122. clients to create or use channels - it only needs to be
  123. mounted when user space applications need access to the buffer
  124. data.
  125. The relay interface kernel API
  126. ==============================
  127. Here's a summary of the API the relay interface provides to in-kernel clients:
  128. TBD(curr. line MT:/API/)
  129. channel management functions::
  130. relay_open(base_filename, parent, subbuf_size, n_subbufs,
  131. callbacks, private_data)
  132. relay_close(chan)
  133. relay_flush(chan)
  134. relay_reset(chan)
  135. channel management typically called on instigation of userspace::
  136. relay_subbufs_consumed(chan, cpu, subbufs_consumed)
  137. write functions::
  138. relay_write(chan, data, length)
  139. __relay_write(chan, data, length)
  140. relay_reserve(chan, length)
  141. callbacks::
  142. subbuf_start(buf, subbuf, prev_subbuf, prev_padding)
  143. buf_mapped(buf, filp)
  144. buf_unmapped(buf, filp)
  145. create_buf_file(filename, parent, mode, buf, is_global)
  146. remove_buf_file(dentry)
  147. helper functions::
  148. relay_buf_full(buf)
  149. subbuf_start_reserve(buf, length)
  150. Creating a channel
  151. ------------------
  152. relay_open() is used to create a channel, along with its per-cpu
  153. channel buffers. Each channel buffer will have an associated file
  154. created for it in the host filesystem, which can be and mmapped or
  155. read from in user space. The files are named basename0...basenameN-1
  156. where N is the number of online cpus, and by default will be created
  157. in the root of the filesystem (if the parent param is NULL). If you
  158. want a directory structure to contain your relay files, you should
  159. create it using the host filesystem's directory creation function,
  160. e.g. debugfs_create_dir(), and pass the parent directory to
  161. relay_open(). Users are responsible for cleaning up any directory
  162. structure they create, when the channel is closed - again the host
  163. filesystem's directory removal functions should be used for that,
  164. e.g. debugfs_remove().
  165. In order for a channel to be created and the host filesystem's files
  166. associated with its channel buffers, the user must provide definitions
  167. for two callback functions, create_buf_file() and remove_buf_file().
  168. create_buf_file() is called once for each per-cpu buffer from
  169. relay_open() and allows the user to create the file which will be used
  170. to represent the corresponding channel buffer. The callback should
  171. return the dentry of the file created to represent the channel buffer.
  172. remove_buf_file() must also be defined; it's responsible for deleting
  173. the file(s) created in create_buf_file() and is called during
  174. relay_close().
  175. Here are some typical definitions for these callbacks, in this case
  176. using debugfs::
  177. /*
  178. * create_buf_file() callback. Creates relay file in debugfs.
  179. */
  180. static struct dentry *create_buf_file_handler(const char *filename,
  181. struct dentry *parent,
  182. umode_t mode,
  183. struct rchan_buf *buf,
  184. int *is_global)
  185. {
  186. return debugfs_create_file(filename, mode, parent, buf,
  187. &relay_file_operations);
  188. }
  189. /*
  190. * remove_buf_file() callback. Removes relay file from debugfs.
  191. */
  192. static int remove_buf_file_handler(struct dentry *dentry)
  193. {
  194. debugfs_remove(dentry);
  195. return 0;
  196. }
  197. /*
  198. * relay interface callbacks
  199. */
  200. static struct rchan_callbacks relay_callbacks =
  201. {
  202. .create_buf_file = create_buf_file_handler,
  203. .remove_buf_file = remove_buf_file_handler,
  204. };
  205. And an example relay_open() invocation using them::
  206. chan = relay_open("cpu", NULL, SUBBUF_SIZE, N_SUBBUFS, &relay_callbacks, NULL);
  207. If the create_buf_file() callback fails, or isn't defined, channel
  208. creation and thus relay_open() will fail.
  209. The total size of each per-cpu buffer is calculated by multiplying the
  210. number of sub-buffers by the sub-buffer size passed into relay_open().
  211. The idea behind sub-buffers is that they're basically an extension of
  212. double-buffering to N buffers, and they also allow applications to
  213. easily implement random-access-on-buffer-boundary schemes, which can
  214. be important for some high-volume applications. The number and size
  215. of sub-buffers is completely dependent on the application and even for
  216. the same application, different conditions will warrant different
  217. values for these parameters at different times. Typically, the right
  218. values to use are best decided after some experimentation; in general,
  219. though, it's safe to assume that having only 1 sub-buffer is a bad
  220. idea - you're guaranteed to either overwrite data or lose events
  221. depending on the channel mode being used.
  222. The create_buf_file() implementation can also be defined in such a way
  223. as to allow the creation of a single 'global' buffer instead of the
  224. default per-cpu set. This can be useful for applications interested
  225. mainly in seeing the relative ordering of system-wide events without
  226. the need to bother with saving explicit timestamps for the purpose of
  227. merging/sorting per-cpu files in a postprocessing step.
  228. To have relay_open() create a global buffer, the create_buf_file()
  229. implementation should set the value of the is_global outparam to a
  230. non-zero value in addition to creating the file that will be used to
  231. represent the single buffer. In the case of a global buffer,
  232. create_buf_file() and remove_buf_file() will be called only once. The
  233. normal channel-writing functions, e.g. relay_write(), can still be
  234. used - writes from any cpu will transparently end up in the global
  235. buffer - but since it is a global buffer, callers should make sure
  236. they use the proper locking for such a buffer, either by wrapping
  237. writes in a spinlock, or by copying a write function from relay.h and
  238. creating a local version that internally does the proper locking.
  239. The private_data passed into relay_open() allows clients to associate
  240. user-defined data with a channel, and is immediately available
  241. (including in create_buf_file()) via chan->private_data or
  242. buf->chan->private_data.
  243. Buffer-only channels
  244. --------------------
  245. These channels have no files associated and can be created with
  246. relay_open(NULL, NULL, ...). Such channels are useful in scenarios such
  247. as when doing early tracing in the kernel, before the VFS is up. In these
  248. cases, one may open a buffer-only channel and then call
  249. relay_late_setup_files() when the kernel is ready to handle files,
  250. to expose the buffered data to the userspace.
  251. Channel 'modes'
  252. ---------------
  253. relay channels can be used in either of two modes - 'overwrite' or
  254. 'no-overwrite'. The mode is entirely determined by the implementation
  255. of the subbuf_start() callback, as described below. The default if no
  256. subbuf_start() callback is defined is 'no-overwrite' mode. If the
  257. default mode suits your needs, and you plan to use the read()
  258. interface to retrieve channel data, you can ignore the details of this
  259. section, as it pertains mainly to mmap() implementations.
  260. In 'overwrite' mode, also known as 'flight recorder' mode, writes
  261. continuously cycle around the buffer and will never fail, but will
  262. unconditionally overwrite old data regardless of whether it's actually
  263. been consumed. In no-overwrite mode, writes will fail, i.e. data will
  264. be lost, if the number of unconsumed sub-buffers equals the total
  265. number of sub-buffers in the channel. It should be clear that if
  266. there is no consumer or if the consumer can't consume sub-buffers fast
  267. enough, data will be lost in either case; the only difference is
  268. whether data is lost from the beginning or the end of a buffer.
  269. As explained above, a relay channel is made of up one or more
  270. per-cpu channel buffers, each implemented as a circular buffer
  271. subdivided into one or more sub-buffers. Messages are written into
  272. the current sub-buffer of the channel's current per-cpu buffer via the
  273. write functions described below. Whenever a message can't fit into
  274. the current sub-buffer, because there's no room left for it, the
  275. client is notified via the subbuf_start() callback that a switch to a
  276. new sub-buffer is about to occur. The client uses this callback to 1)
  277. initialize the next sub-buffer if appropriate 2) finalize the previous
  278. sub-buffer if appropriate and 3) return a boolean value indicating
  279. whether or not to actually move on to the next sub-buffer.
  280. To implement 'no-overwrite' mode, the userspace client would provide
  281. an implementation of the subbuf_start() callback something like the
  282. following::
  283. static int subbuf_start(struct rchan_buf *buf,
  284. void *subbuf,
  285. void *prev_subbuf,
  286. unsigned int prev_padding)
  287. {
  288. if (prev_subbuf)
  289. *((unsigned *)prev_subbuf) = prev_padding;
  290. if (relay_buf_full(buf))
  291. return 0;
  292. subbuf_start_reserve(buf, sizeof(unsigned int));
  293. return 1;
  294. }
  295. If the current buffer is full, i.e. all sub-buffers remain unconsumed,
  296. the callback returns 0 to indicate that the buffer switch should not
  297. occur yet, i.e. until the consumer has had a chance to read the
  298. current set of ready sub-buffers. For the relay_buf_full() function
  299. to make sense, the consumer is responsible for notifying the relay
  300. interface when sub-buffers have been consumed via
  301. relay_subbufs_consumed(). Any subsequent attempts to write into the
  302. buffer will again invoke the subbuf_start() callback with the same
  303. parameters; only when the consumer has consumed one or more of the
  304. ready sub-buffers will relay_buf_full() return 0, in which case the
  305. buffer switch can continue.
  306. The implementation of the subbuf_start() callback for 'overwrite' mode
  307. would be very similar::
  308. static int subbuf_start(struct rchan_buf *buf,
  309. void *subbuf,
  310. void *prev_subbuf,
  311. size_t prev_padding)
  312. {
  313. if (prev_subbuf)
  314. *((unsigned *)prev_subbuf) = prev_padding;
  315. subbuf_start_reserve(buf, sizeof(unsigned int));
  316. return 1;
  317. }
  318. In this case, the relay_buf_full() check is meaningless and the
  319. callback always returns 1, causing the buffer switch to occur
  320. unconditionally. It's also meaningless for the client to use the
  321. relay_subbufs_consumed() function in this mode, as it's never
  322. consulted.
  323. The default subbuf_start() implementation, used if the client doesn't
  324. define any callbacks, or doesn't define the subbuf_start() callback,
  325. implements the simplest possible 'no-overwrite' mode, i.e. it does
  326. nothing but return 0.
  327. Header information can be reserved at the beginning of each sub-buffer
  328. by calling the subbuf_start_reserve() helper function from within the
  329. subbuf_start() callback. This reserved area can be used to store
  330. whatever information the client wants. In the example above, room is
  331. reserved in each sub-buffer to store the padding count for that
  332. sub-buffer. This is filled in for the previous sub-buffer in the
  333. subbuf_start() implementation; the padding value for the previous
  334. sub-buffer is passed into the subbuf_start() callback along with a
  335. pointer to the previous sub-buffer, since the padding value isn't
  336. known until a sub-buffer is filled. The subbuf_start() callback is
  337. also called for the first sub-buffer when the channel is opened, to
  338. give the client a chance to reserve space in it. In this case the
  339. previous sub-buffer pointer passed into the callback will be NULL, so
  340. the client should check the value of the prev_subbuf pointer before
  341. writing into the previous sub-buffer.
  342. Writing to a channel
  343. --------------------
  344. Kernel clients write data into the current cpu's channel buffer using
  345. relay_write() or __relay_write(). relay_write() is the main logging
  346. function - it uses local_irqsave() to protect the buffer and should be
  347. used if you might be logging from interrupt context. If you know
  348. you'll never be logging from interrupt context, you can use
  349. __relay_write(), which only disables preemption. These functions
  350. don't return a value, so you can't determine whether or not they
  351. failed - the assumption is that you wouldn't want to check a return
  352. value in the fast logging path anyway, and that they'll always succeed
  353. unless the buffer is full and no-overwrite mode is being used, in
  354. which case you can detect a failed write in the subbuf_start()
  355. callback by calling the relay_buf_full() helper function.
  356. relay_reserve() is used to reserve a slot in a channel buffer which
  357. can be written to later. This would typically be used in applications
  358. that need to write directly into a channel buffer without having to
  359. stage data in a temporary buffer beforehand. Because the actual write
  360. may not happen immediately after the slot is reserved, applications
  361. using relay_reserve() can keep a count of the number of bytes actually
  362. written, either in space reserved in the sub-buffers themselves or as
  363. a separate array. See the 'reserve' example in the relay-apps tarball
  364. at http://relayfs.sourceforge.net for an example of how this can be
  365. done. Because the write is under control of the client and is
  366. separated from the reserve, relay_reserve() doesn't protect the buffer
  367. at all - it's up to the client to provide the appropriate
  368. synchronization when using relay_reserve().
  369. Closing a channel
  370. -----------------
  371. The client calls relay_close() when it's finished using the channel.
  372. The channel and its associated buffers are destroyed when there are no
  373. longer any references to any of the channel buffers. relay_flush()
  374. forces a sub-buffer switch on all the channel buffers, and can be used
  375. to finalize and process the last sub-buffers before the channel is
  376. closed.
  377. Misc
  378. ----
  379. Some applications may want to keep a channel around and re-use it
  380. rather than open and close a new channel for each use. relay_reset()
  381. can be used for this purpose - it resets a channel to its initial
  382. state without reallocating channel buffer memory or destroying
  383. existing mappings. It should however only be called when it's safe to
  384. do so, i.e. when the channel isn't currently being written to.
  385. Finally, there are a couple of utility callbacks that can be used for
  386. different purposes. buf_mapped() is called whenever a channel buffer
  387. is mmapped from user space and buf_unmapped() is called when it's
  388. unmapped. The client can use this notification to trigger actions
  389. within the kernel application, such as enabling/disabling logging to
  390. the channel.
  391. Resources
  392. =========
  393. For news, example code, mailing list, etc. see the relay interface homepage:
  394. http://relayfs.sourceforge.net
  395. Credits
  396. =======
  397. The ideas and specs for the relay interface came about as a result of
  398. discussions on tracing involving the following:
  399. Michel Dagenais <michel.dagenais@polymtl.ca>
  400. Richard Moore <richardj_moore@uk.ibm.com>
  401. Bob Wisniewski <bob@watson.ibm.com>
  402. Karim Yaghmour <karim@opersys.com>
  403. Tom Zanussi <zanussi@us.ibm.com>
  404. Also thanks to Hubertus Franke for a lot of useful suggestions and bug
  405. reports.