名称

pmc_allocate, pmc_release — 性能のモニタリングカウンタを割り付けて、解放する

ライブラリ

Performance Counters Library (libpmc, -lpmc)

書式

#include < pmc.h>

int
pmc_allocate( const char *eventspecifier, enum pmc_mode mode, uint32_t flags, int cpu, pmc_id_t *pmcid);

int
pmc_release( pmc_id_t pmc);

解説

関数 pmc_allocate() は、引数 eventspecifier によって指定されたイベントを測定する性能モニタリングカウンタを割り付け、引数 pmcid によって指された位置に割り付けられたハンドルを書き込みます。

引数 eventspecifier は、イベント名に続いて、オプションのキーワードと修飾子のコンマで区切られたリストから成ります。引数 eventspecifier のために許可された構文は、プロセッサ特有であり、 pmc(3) マニュアルページのセクション イベント指定子 にリストされています。

望まれる PMC モードは、引数 mode によって指定されます。 mode 引数のための正しい値は、次の通りです:

PMC_MODE_SC

システムスコープカウンティング PMC を割り付けます。

PMC_MODE_SS

システムスコープサンプリング PMC を割り付けます。

PMC_MODE_TC

プロセススコープカウンティング PMC を割り付けます。

PMC_MODE_TS

プロセススコープサンプリング PMC を割り付けます。

モード特有の修飾子は、引数 flags を使用して指定されます。 PMC 割り付け時間でサポートされたフラグは、次の通りです:

PMC_F_DESCENDANTS

プロセススコープ PMC に関して、自動的にアタッチされたプロセスの子孫を追跡します。

PMC_F_LOG_PROCCSW

プロセススコープカウンティング PMC に関して、それが CPU で実行していた時間の間に、プロセスによって見られたハードウェアイベントの増加の数を含んで、あらゆるコンテキストスイッチでログイベントを生成します。

PMC_F_LOG_PROCEXIT

プロセススコープカウンティング PMC に関して、プロセスが CPU で実行されていたときに見られるハードウェアイベントを蓄積して、アタッチされたプロセスが終了するとき、ログイベントを生成します。

フラグ PMC_F_LOG_PROCCSW と PMC_F_LOG_PROCEXIT PMC は、それらが開始される前に、ログファイルが設定される必要があります。

システムスコープ PMC に関して、引数 cpu は、PMC が割り付けられることになっている CPU 番号を指定する負ではない値です。プロセススコープ PMC 割り付けは、この引数のための定数 PMC_CPU_ANY を指定するべきです。

関数 pmc_release() は、引数 pmcid によって示された PMC を解放します。

戻り値

成功するなら、関数 pmc_allocate() は、割り付けられた PMC のハンドルへの引数 pmcid によって指定された位置を設定して、0 を返します。エラーの場合には、関数は、-1 を返して、グローバル変数 errno にエラーを示す値を設定します。

The pmc_release() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

エラー

[ EINVAL]

関数 pmc_allocate() への引数 mode に、無効の値がありました。

[ EINVAL]

関数 pmc_allocate() への引数 cpu に、無効の CPU 番号がありました。

[ EINVAL]

引数 flags が、要求された PMC モードをサポートしていないか、または互換性のないフラグを含んでします。

[ EINVAL]

関数 pmc_allocate() への引数 eventspecifier は、ハードウェアによってサポートされないイベントを指定したか、または構文エラーを含んでいます。

[ ENXIO]

関数 pmc_allocate() が、欠けているか、または管理上無効にされたハードウェアリソースの使用を要求しました。

[ EOPNOTSUPP]

基礎的なハードウェアが、 pmc_allocate() への呼び出しによて割り付けられる PMC に必要であるケーパビリティをサポートしていません。

[ EPERM]

システムスコープ PMC 割り付けが、適切なプロセス特権なしで試みられました。

[ ESRCH]

関数 pmc_release() が、最初に PMC を割り付けていなくて、呼び出されました。

[ EINVAL]

関数 pmc_release() への引数 pmcid が、以前にこのプロセスによって割り付けられた PMC を指定しませんでした。

関連項目

pmc(3), pmc_attach(3), pmc_configure_logfile(3), pmc_start(3), hwpmc(4)