2.2. タップセットの要素

以降の項では、タップセットの作成で最も重要となる事柄について説明します。内容はほぼ SystempTap のタップセットのアップストリームライブラリーへの貢献を検討している開発者向けになります。

2.2.1. タップセットファイル

タップセットファイルは SystemTap GIT ディレクトリーの src/tapset/ に保存されます。ほとんどのタップセットファイルがこのレベルで保存されます。特定のアーキテクチャーやカーネルバージョンでのみ動作するコードがある場合、タップセットを適切なサブディレクトリーに置くことを選択することもできます。
インストールされたタップセットは /usr/share/systemtap/tapset/ または /usr/local/share/systemtap/tapset にあります。
個人のタップセットはどこにでも保存できますが、SystemTap でこれらを使用できるようにするには、-I tapset_directory を使用して stap を呼び出すときにタップセットの場所を指定します。

2.2.2. 名前空間

プローブエイリアス名は、 tapset_name.probe_name という形式を取る必要があります。たとえば、シグナル送信のプローブには signal.send という名前を付けることができます。
グローバルシンボル名 (プローブ、関数、および変数) はタップセット全体で一意である必要があります。これにより、複数のタップセットを使用するスクリプトで名前空間の競合が発生しないようにします。このために、グローバルシンボルにタップセット固有の接頭辞を使用します。
内部シンボル名にはアンダースコア (_) を接頭辞として使用する必要があります。

2.2.3. コメントおよび記録

すべてのプローブと関数には、目的、提供されるデータ、および実行されるコンテキスト (割り込み、プロセスなど) を記述するコメントブロックが含まれる必要があります。コードを見ても目的が分かりにくい部分にコメントを使用します。
本ガイドには、ほとんどのタップセットから自動的に抽出された特別な形式のコメントが含まれています。これにより、タップセットの提供者が同じ場所でタップセットを作成し、記録することができます。タップセットを記録するための指定の形式は次のとおりです。
/**
 * probe tapset.name - Short summary of what the tapset does.
 * @argument: Explanation of argument.
 * @argument2: Explanation of argument2. Probes can have multiple arguments.
 *
 * Context:
 * A brief explanation of the tapset context. 
 * Note that the context should only be 1 paragraph short.
 *
 * Text that will appear under "Description."
 *
 * A new paragraph that will also appear under the heading "Description".
 *
 * Header:
 * A paragraph that will appear under the heading "Header".
 **/
以下に例を示します。
/**
 * probe vm.write_shared_copy- Page copy for shared page write.
 * @address: The address of the shared write.
 * @zero: Boolean indicating whether it is a zero page
 *         (can do a clear instead of a copy).
 *
 * Context:
 *  The process attempting the write.
 *
 *  Fires when a write to a shared page requires a page copy.  This is
 *  always preceded by a vm.shared_write.
 **/
自動的に生成される Synopsis コンテンツをオーバーライドするには、以下を使用します。
 * Synopsis:
 * New Synopsis string
 *
以下に例を示します。
/**
 * probe signal.handle - Fires when the signal handler is invoked
 * @sig: The signal number that invoked the signal handler
 *
 * Synopsis:
 * <programlisting>static int handle_signal(unsigned long sig, siginfo_t *info, struct k_sigaction *ka,
 * sigset_t *oldset, struct pt_regs * regs)</programlisting>
 */
エントリーの Synopsis コンテンツをオーバーライドすると必要なタグが自動的に作成されないため、この例では <programlisting> タグを使用することが推奨されます。
コメントの DocBook XML 出力を改善するため、コメントに以下の XML タグを使用することもできます。
  • command
  • emphasis
  • programlisting
  • remark (タグ付けされた文字列はドキュメントの Publican ベータ版ビルドに表示されます)