From 130eebe0e0c58b4479678f3575a25e565eadc0a3 Mon Sep 17 00:00:00 2001 From: William Cohen Date: Wed, 17 Aug 2011 17:40:57 -0400 Subject: [PATCH] Add the structure comments for tapset reference manual to nfs.stp --- tapset/nfs.stp | 489 ++++++++++++++++++++++--------------------------- 1 file changed, 219 insertions(+), 270 deletions(-) diff --git a/tapset/nfs.stp b/tapset/nfs.stp index bce1460a7..1ea30cd0f 100644 --- a/tapset/nfs.stp +++ b/tapset/nfs.stp @@ -2,7 +2,7 @@ // Copyright (C) 2006-2007 IBM Corp. // Copyright (C) 2007 Intel Corporation. // Copyright (C) 2007 Bull S.A.S -// Copyright (c) 2009-2010 Red Hat Inc. +// Copyright (c) 2009,2010,2011 Red Hat Inc. // // This file is part of systemtap, and is free software. You can // redistribute it and/or modify it under the terms of the GNU General @@ -247,23 +247,16 @@ probe nfs.fop.return = nfs.fop.llseek.return, { } -/* probe nfs.fop.llseek - * - * Fires when do a llseek operation on nfs, it probes - * llseek file operation of nfs - * - * Arguments: - * dev : device identifier - * ino : inode number - * offset : the offset of the file will be repositioned - * origin : the original position. The possible value could be: - * SEEK_SET - * The offset is set to offset bytes. - * SEEK_CUR - * The offset is set to its current location plus offset bytes. - * SEEK_END - * The offset is set to the size of the file plus offset bytes. +/** + * probe nfs.fop.llseek - NFS client llseek operation * + * @dev: device identifier + * @ino: inode number + * @offset: the offset of the file will be repositioned + * @origin: the original position. The possible value could be: + * SEEK_SET (offset set to offset bytes), + * SEEK_CUR (offset set to its current location plus offset bytes), + * or SEEK_END (offset set to the size of the file plus offset bytes). */ probe nfs.fop.llseek = kernel.function ("nfs_file_llseek") !, module("nfs").function("nfs_file_llseek") @@ -288,14 +281,14 @@ probe nfs.fop.llseek.return = kernel.function ("nfs_file_llseek").return !, retstr = sprintf("%d", $return) } -/* probe nfs.fop.read +/** + * probe nfs.fop.read - NFS client read operation * - * Fires when do a read operation on nfs, it probes - * read file operation of nfs + * @devname: block device name * - * Arguments: - * - * + * SystemTap uses the vfs.do_sync_read probe to implement this probe + * and as a result will get operations other than the NFS client read + * operations. */ probe nfs.fop.read = vfs.do_sync_read { @@ -309,14 +302,14 @@ probe nfs.fop.read.return = vfs.do_sync_read.return name = "nfs.fop.read.return" } -/* probe nfs.fop.write +/** + * probe nfs.fop.write - NFS client write operation * - * Fires when do a write operation on nfs, it probes - * write file operation of nfs - * - * Arguments: - * + * @devname: block device name * + * SystemTap uses the vfs.do_sync_write probe to implement this probe + * and as a result will get operations other than the NFS client write + * operations. */ probe nfs.fop.write = vfs.do_sync_write { @@ -330,25 +323,21 @@ probe nfs.fop.write.return = vfs.do_sync_write.return name = "nfs.fop.write.return" } -/* probe nfs.fop.aio_read +/** + * probe nfs.fop.aio_read - NFS client aio_read file operation * - * It probes aio_read file operation of nfs - * - * Arguments: - * dev : device identifier - * ino : inode number - * count : read bytes - * pos : current position of file - * buf : the address of buf in user space - * parent_name : parent dir name - * file_name : file name - * cache_valid : cache related bit mask flag - * cache_time : when we started read-caching this inode - * attrtimeo : how long the cached information is assumed - * to be valid. - * We need to revalidate the cached attrs for this inode if - * - * jiffies - read_cache_jiffies > attrtimeo + * @dev: device identifier + * @ino: inode number + * @count: read bytes + * @pos: current position of file + * @buf: the address of buf in user space + * @parent_name: parent dir name + * @file_name: file name + * @cache_valid: cache related bit mask flag + * @cache_time: when we started read-caching this inode + * @attrtimeo: how long the cached information is assumed to be valid. + * We need to revalidate the cached attrs for this inode + * if jiffies - read_cache_jiffies > attrtimeo. */ probe nfs.fop.aio_read = kernel.function ("nfs_file_read") !, module("nfs").function("nfs_file_read") @@ -396,19 +385,16 @@ probe nfs.fop.aio_read.return = kernel.function ("nfs_file_read").return !, units = "bytes" } -/* probe nfs.fop.aio_write - * - * It probes aio_write file operation of nfs - * - * Arguments: - * dev : device identifier - * ino : inode number - * count : read bytes - * pos : offset of the file - * buf : the address of buf in user space - * parent_name : parent dir name - * file_name : file name +/** + * probe nfs.fop.aio_write - NFS client aio_write file operation * + * @dev: device identifier + * @ino: inode number + * @count: read bytes + * @pos: offset of the file + * @buf: the address of buf in user space + * @parent_name: parent dir name + * @file_name: file name */ probe nfs.fop.aio_write = kernel.function("nfs_file_write") !, module("nfs").function("nfs_file_write") @@ -450,27 +436,22 @@ probe nfs.fop.aio_write.return = kernel.function("nfs_file_write").return !, units = "bytes" } -/* probe nfs.fop.mmap - * - * Fires when do an mmap operation on nfs, - * it probes mmap operation of nfs +/** + * probe nfs.fop.mmap - NFS client mmap operation * - * Arguments: - * dev : device identifier - * ino : inode number - * vm_start : start address within vm_mm - * vm_end : the first byte after end address within vm_mm - * vm_flag : vm flags - * buf : the address of buf in user space - * parent_name : parent dir name - * file_name : file name - * cache_valid : cache related bit mask flag - * cache_time : when we started read-caching this inode - * attrtimeo : how long the cached information is assumed - * to be valid. - * We need to revalidate the cached attrs for this inode if - * - * jiffies - read_cache_jiffies > attrtimeo + * @dev: device identifier + * @ino: inode number + * @vm_start: start address within vm_mm + * @vm_end: the first byte after end address within vm_mm + * @vm_flag: vm flags + * @buf: the address of buf in user space + * @parent_name: parent dir name + * @file_name: file name + * @cache_valid: cache related bit mask flag + * @cache_time: when we started read-caching this inode + * @attrtimeo: how long the cached information is assumed to be valid. + * We need to revalidate the cached attrs for this inode + * if jiffies - read_cache_jiffies > attrtimeo. */ probe nfs.fop.mmap = kernel.function("nfs_file_mmap") !, module("nfs").function("nfs_file_mmap") @@ -502,17 +483,14 @@ probe nfs.fop.mmap.return = kernel.function("nfs_file_mmap").return !, retstr = sprintf("%d", $return) } -/* probe nfs.fop.open +/** + * probe nfs.fop.open - NFS client file open operation * - * Fires when do an open operation on nfs, - * it probes open file operation of nfs - * - * Arguments: - * dev : device identifier - * ino : inode number - * file_name : file name - * flag : file flag - * i_size : file length in bytes + * @dev: device identifier + * @ino: inode number + * @file_name: file name + * @flag: file flag + * @i_size: file length in bytes */ probe nfs.fop.open = kernel.function("nfs_file_open") !, module("nfs").function("nfs_file_open") @@ -538,16 +516,13 @@ probe nfs.fop.open.return = kernel.function("nfs_file_open").return !, retstr = sprintf("%d", $return) } -/* probe nfs.fop.flush - * - * Fires when do a flush file operation on nfs, - * it probes flush file operation of nfs +/** + * probe nfs.fop.flush - NFS client flush file operation * - * Arguments: - * dev : device identifier - * ino : inode number - * mode : file mode - * ndirty : number of dirty page + * @dev: device identifier + * @ino: inode number + * @mode: file mode + * @ndirty: number of dirty page */ probe nfs.fop.flush = kernel.function("nfs_file_flush") !, module("nfs").function("nfs_file_flush") @@ -571,15 +546,12 @@ probe nfs.fop.flush.return = kernel.function("nfs_file_flush").return !, retstr = sprintf("%d", $return) } -/* probe nfs.fop.release - * - * Fires when do a release page operation on nfs, - * it probes release file operation of nfs +/** + * probe nfs.fop.release - NFS client release page operation * - * Arguments: - * dev : device identifier - * ino : inode number - * mode : file mode + * @dev: device identifier + * @ino: inode number + * @mode: file mode */ probe nfs.fop.release = kernel.function("nfs_file_release") !, module("nfs").function("nfs_file_release") @@ -602,15 +574,12 @@ probe nfs.fop.release.return = kernel.function("nfs_file_release").return !, retstr = sprintf("%d", $return) } -/* probe nfs.fop.fsync - * - * Fires when do a fsync operation on nfs, - * it probes fsync file operation of nfs +/** + * probe nfs.fop.fsync - NFS client fsync operation * - * Arguments: - * dev : device identifier - * ino : inode number - * ndirty : number of dirty pages + * @dev: device identifier + * @ino: inode number + * @ndirty: number of dirty pages */ probe nfs.fop.fsync = kernel.function("nfs_file_fsync") !, module("nfs").function("nfs_file_fsync") !, @@ -637,20 +606,17 @@ probe nfs.fop.fsync.return = kernel.function("nfs_file_fsync").return !, retstr = sprintf("%d", $return) } -/* probe nfs.fop.lock - * - * Fires when do a file lock operation on nfs, - * it probes lock file operation of nfs +/** + * probe nfs.fop.lock - NFS client file lock operation * - * Arguments: - * dev : device identifier - * ino : inode number - * i_mode : file type and access rights - * cmd : cmd arguments - * fl_type :lock type - * fl_flag : lock flags - * fl_start : starting offset of locked region - * fl_end : ending offset of locked region + * @dev: device identifier + * @ino: inode number + * @i_mode: file type and access rights + * @cmd: cmd arguments + * @fl_type:lock type + * @fl_flag: lock flags + * @fl_start: starting offset of locked region + * @fl_end: ending offset of locked region */ probe nfs.fop.lock = kernel.function("nfs_lock") !, module("nfs").function("nfs_lock") @@ -679,23 +645,18 @@ probe nfs.fop.lock.return = kernel.function("nfs_lock").return !, retstr = sprintf("%d", $return) } -/* probe nfs.fop.sendfile - * - * Fires when do a send file operation on nfs, - * it probes sendfile file operation of nfs +/** + * probe nfs.fop.sendfile - NFS client send file operation * - * Arguments: - * dev : device identifier - * ino : inode number - * count : read bytes - * ppos : current position of file - * cache_valid : cache related bit mask flag - * cache_time : when we started read-caching this inode - * attrtimeo : how long the cached information is assumed - * to be valid. - * We need to revalidate the cached attrs for this inode if - * - * jiffies - read_cache_jiffies > attrtimeo + * @dev: device identifier + * @ino: inode number + * @count: read bytes + * @ppos: current position of file + * @cache_valid: cache related bit mask flag + * @cache_time: when we started read-caching this inode + * @attrtimeo: how long the cached information is assumed to be valid. + * We need to revalidate the cached attrs for this inode + * if jiffies - read_cache_jiffies > attrtimeo. */ probe nfs.fop.sendfile = kernel.function("nfs_file_sendfile") !, module("nfs").function("nfs_file_sendfile") ? @@ -732,13 +693,10 @@ probe nfs.fop.sendfile.return = units = "bytes" } -/* probe nfs.fop.check_flags +/** + * probe nfs.fop.check_flags - NFS client checking flag operation * - * Fires when do a checking flag operation on nfs, - * it probes check_flag file operation of nfs - * - * Arguments: - * flag : file flag + * @flag: file flag */ probe nfs.fop.check_flags = kernel.function("nfs_check_flags") !, module("nfs").function("nfs_check_flags") @@ -777,24 +735,22 @@ probe nfs.aop.return = nfs.aop.readpage.return, { } -/* probe nfs.aop.readpage - * - * Read the page, only fies when a previous async - * read operation failed +/** + * probe nfs.aop.readpage - NFS client synchronously reading a page + * @__page: the address of page + * @dev: device identifier + * @ino: inode number + * @i_flag: file flags + * @i_size: file length in bytes + * @sb_flag: super block flags + * @file: file argument + * @page_index : offset within mapping, can used a page identifier + * and position identifier in the page frame + * @rsize: read size (in bytes) + * @size: number of pages to be read in this execution * - * Arguments: - * __page : the address of page - * dev : device identifier - * ino : inode number - * i_flag : file flags - * i_size : file length in bytes - * sb_flag : super block flags - * file : file argument - * page_index : offset within mapping, can used a - * page identifier and position identifier - * in the page frame - * rsize : read size (in bytes) - * size : number of pages to be read in this execution + * Read the page over, only fires when a previous async + * read operation failed */ probe nfs.aop.readpage = kernel.function ("nfs_readpage") !, module("nfs").function ("nfs_readpage") @@ -831,17 +787,17 @@ probe nfs.aop.readpage.return = kernel.function ("nfs_readpage").return !, units = "pages" } -/* probe nfs.aop.readpages +/** + * probe nfs.aop.readpages - NFS client reading multiple pages + * @dev: device identifier + * @ino: inode number + * @nr_pages: number of pages attempted to read in this execution + * @file: filp argument + * @rpages: read size (in pages) + * @rsize: read size (in bytes) + * @size: number of pages attempted to read in this execution * - * Fies when in readahead way, read several pages once - * Arguments: - * dev : device identifier - * ino : inode number - * nr_pages : number of pages attempted to read in this execution - * file : filp argument - * rpages : read size (in pages) - * rsize : read size (in bytes) - * size : number of pages attempted to read in this execution + * Fires when in readahead way, read several pages once */ probe nfs.aop.readpages = kernel.function ("nfs_readpages") !, module("nfs").function ("nfs_readpages") @@ -874,14 +830,14 @@ probe nfs.aop.readpages.return = kernel.function ("nfs_readpages").return !, units = "pages" } -/* probe nfs.aop.set_page_dirty - * - * __set_page_dirty_nobuffers is used to set a page dirty, but - * not all the buffers. +/** + * probe nfs.aop.set_page_dirty - NFS client marking page as dirty + * @__page: the address of page + * @page_flag: page flags * - * Arguments: - * __page : the address of page - * page_flag : page flags + * This probe attaches to the generic __set_page_dirty_nobuffers function. + * Thus, this probe is going to fire on many other file systems in + * addition to the NFS client. */ probe nfs.aop.set_page_dirty = kernel.function ("__set_page_dirty_nobuffers") !, @@ -902,28 +858,26 @@ probe nfs.aop.set_page_dirty.return = retstr = sprintf("%d", $return) } -/* probe nfs.aop.writepage +/** + * probe nfs.aop.writepage - NFS client writing a mapped page to the NFS server + * @__page: the address of page + * @dev: device identifier + * @ino: inode number + * @for_reclaim: a flag of writeback_control, + * indicates if it's invoked from the page allocator + * @for_kupdate: a flag of writeback_control, + * indicates if it's a kupdate writeback + * @i_flag: file flags + * @i_size: file length in bytes + * @i_state: inode state flags + * @sb_flag: super block flags + * @page_index: offset within mapping, + * can used a page identifier and position identifier in the page frame + * @wsize: write size + * @size: number of pages to be written in this execution * - * Write an mapped page to the server - * - * Arguments: - * __page : the address of page - * dev : device identifier - * ino : inode number - * for_reclaim : a flag of writeback_control, indicates if it's - * invoked from the page allocator - * for_kupdate : a flag of writeback_control, indicates if it's a - * kupdate writeback - * The priority of wb is decided by above two flags - * i_flag : file flags - * i_size : file length in bytes - * i_state : inode state flags - * sb_flag : super block flags - * page_index : offset within mapping, can used a - * page identifier and position identifier - * in the page frame - * wsize : write size - * size : number of pages to be written in this execution + * The priority of wb is decided by the flags + * @for_reclaim and @for_kupdate. */ probe nfs.aop.writepage = kernel.function ("nfs_writepage") !, module("nfs").function ("nfs_writepage") @@ -960,21 +914,21 @@ probe nfs.aop.writepage.return = kernel.function ("nfs_writepage").return !, retstr = sprintf("%d", $return) } -/* probe nfs.aop.writepages - * Write several dirty pages to the serve - *Arguments: - * dev : device identifier - * ino : inode number - * for_reclaim : a flag of writeback_control, indicates if it's - * invoked from the page allocator - * for_kupdate : a flag of writeback_control, indicates if it's a - * kupdate writeback - * The priority of wb is decided by above two flags - * wsize : write size - * wpages : write size (in pages) - * nr_to_write : number of pages attempted to be written in this - * execution - * size : number of pages attempted to be written in this execution +/** + * probe nfs.aop.writepages - NFS client writing several dirty pages to the NFS server + * @dev: device identifier + * @ino: inode number + * @for_reclaim: a flag of writeback_control, + * indicates if it's invoked from the page allocator + * @for_kupdate: a flag of writeback_control, + * indicates if it's a kupdate writeback + * @wsize: write size + * @wpages: write size (in pages) + * @nr_to_write: number of pages attempted to be written in this execution + * @size: number of pages attempted to be written in this execution + * + * The priority of wb is decided by the flags + * @for_reclaim and @for_kupdate. */ probe nfs.aop.writepages = kernel.function ("nfs_writepages") !, module("nfs").function ("nfs_writepages") @@ -1009,6 +963,25 @@ probe nfs.aop.writepages.return = # nfs_write_begin()/nfs_write_end(). So, we try to find whatever the # current kernel has. +/** + * probe nfs.aop.write_begin - NFS client begin to write data + * @__page: the address of page + * @dev: device identifier + * @ino: inode number + * @offset: start address of this write operation + * @to: end address of this write operation + * @page_index: offset within mapping, can used a page identifier + * and position identifier in the page frame + * @size: write bytes + * + * Occurs when write operation occurs on nfs. It prepare a page for writing, + * look for a request corresponding to the page. If there + * is one, and it belongs to another file, it flush it out + * before it tries to copy anything into the page. + * Also do the same if it finds a request from an existing + * dropped page + * + */ probe nfs.aop.write_begin = __nfs.aop.write_begin !, __nfs.aop.prepare_write { @@ -1019,6 +992,24 @@ probe nfs.aop.write_begin.return { } +/** + * probe nfs.aop.write_end - NFS client complete writing data + * @__page: the address of page + * @dev: device identifier + * @ino: inode number + * @offset: start address of this write operation + * @to: end address of this write operation + * @i_flag: file flags + * @i_size: file length in bytes + * @sb_flag: super block flags + * @page_index: offset within mapping, can used a page identifier and position identifier in the page frame + * @size: write bytes + * + * Fires when do a write operation on nfs, + * often after prepare_write + * + * Update and possibly write a cached page of an NFS file. + */ probe nfs.aop.write_end = __nfs.aop.write_end !, __nfs.aop.commit_write { @@ -1102,26 +1093,6 @@ probe __nfs.aop.write_end.return retstr = sprintf("%d", $return) } -/* probe nfs.aop.prepare_write - * Fires when do write operation on nfs. - * Prepare a page for writing - * Look for a request corresponding to the page. If there - * is one, and it belongs to another file, we flush it out - * before we try to copy anything into the page. - * Also do the same if we find a request from an existing - * dropped page - * - * Arguments: - * __page : the address of page - * dev : device identifier - * ino : inode number - * offset : start address of this write operation - * to : end address of this write operation - * page_index : offset within mapping, can used a - * page identifier and position identifier - * in the page frame - * size : write bytes - */ probe __nfs.aop.prepare_write = kernel.function ("nfs_prepare_write") !, module("nfs").function ("nfs_prepare_write") { @@ -1159,26 +1130,6 @@ probe __nfs.aop.prepare_write.return = retstr = sprintf("%d", $return) } -/* probe nfs.aop.commit_write - * Fires when do a write operation on nfs, - * often after prepare_write - * - * Update and possibly write a cached page of an NFS file - * - * Arguments: - * __page : the address of page - * dev : device identifier - * ino : inode number - * offset : start address of this write operation - * to : end address of this write operation - * i_flag : file flags - * i_size : file length in bytes - * sb_flag : super block flags - * page_index : offset within mapping, can used a - * page identifier and position identifier - * in the page frame - * size : write bytes - */ probe __nfs.aop.commit_write = kernel.function ("nfs_commit_write") !, module("nfs").function ("nfs_commit_write") { @@ -1221,18 +1172,16 @@ probe __nfs.aop.commit_write.return = retstr = sprintf("%d", $return) } -/* probe nfs.aop.release_page - * Fires when do a release operation on nfs, +/** + * probe nfs.aop.release_page - NFS client releasing page + * @__page: the address of page + * @dev: device identifier + * @ino: inode number + * @page_index: offset within mapping, can used a page identifier + * and position identifier in the page frame + * @size: release pages * - * - * Arguments: - * __page : the address of page - * dev : device identifier - * ino : inode number - * page_index : offset within mapping, can used a - * page identifier and position identifier - * in the page frame - * size : release pages + * Fires when do a release operation on NFS. */ probe nfs.aop.release_page = kernel.function ("nfs_release_page") !, module("nfs").function ("nfs_release_page") ? -- 2.43.5