dbx プラグイン・フレームワーク用の開発

^libdbx_.+¥.so$

$ export dbx_PLUGIN_PATH=$HOME/dbx_plugins:/mnt/share/dbx_plugins

• プラグインは、dbx が検索するディレクトリー内に置くことで、自動的にロードされ、初期化されるようにすることができます。 それが行われるのは、dbx の初期化のときです。
• pluginload dbx サブコマンドに対してプラグインのロケーションを指定すると、そのプラグインを手動でロードして初期化することができます。 これは dbx セッション中はいつでも行うことができます。

(dbx) pluginload /home/user/dbx_plugins/libdbx_sample.so
 plug-in "/home/user/dbx_plugins/libdbx_sample.so"  loaded

(dbx) pluginload /mnt/share/dbx_plugins/libdbx_sample.so

could not load plug-in 
"/mnt/share/dbx_plugins/libdbx_sample.so":
plug-in "/home/user/dbx_plugins/libdbx_sample.so" already loaded.

(dbx) pluginunload sample 
plug-in "/home/user/dbx_plugins/libdbx_sample.so" unloaded.

/usr/include/sys/dbx_plugin.h

• int dbx_plugin_version(void)
• int dbx_plugin_session_init(dbx_plugin_session_t session, constdbx_plugin_service_t *servicep)
• void dbx_plugin_session_command(dbx_plugin_session_t session, int argc, char *const argv[])
• void dbx_plugin_session_event(dbx_plugin_session_t session, int event, dbx_plugin_event_info_t *event_infop)

plugin Name [arg0 arg1 arg2 ... argn]

void dbx_plugin_session_destroy(dbx_plugin_session_t session)

typedef int (*dbx_plugin_session_service_t)(dbx_plugin_session_t session,
                                            dbx_plugin_session_flags_t *flagsp).

• DBX_PLUGIN_SUCCESS
• DBX_PLUGIN_BAD_SESSION - セッションは有効ではありません。
• DBX_PLUGIN_BAD_POINTER - flagsp は NULL です。

typedef int (*dbx_plugin_process_service_t)(dbx_plugin_session_t session,
                                            dbx _plugin_procinfo_t *infop,
                                            size_t procinfo_size) 

• DBX_PLUGIN_SUCCESS
• DBX_PLUGIN_BAD_SESSION - session は有効ではありません。
• DBX_PLUGIN_BAD_POINTER - infop は NULL です。
• DBX_PLUGIN_BAD_ARG - procinfo_size は有効ではありません。
• DBX_PLUGIN_UNAVAILABLE - プロセスはアクティブではないか、またはメモリー内に情報がありません。

• 各ファイル・ディスクリプターに関する情報を別々に入手するために対話式で呼び出す。 または
• ファイル・ディスクリプターの合計数を得るために 1 回呼び出し、 すべてのファイル・ディスクリプターに関する情報を同時に得るためにもう 1 回呼び出す。

typedef int (*dbx_plugin_fds_service_t)(dbx_plugin_session_t session,
                                        dbx_plugin_fdinfo_t *infop,
                                        size_t fdinfo_size,
                                        unsigned int *indexp,
                                        unsigned int *countp)

• DBX_PLUGIN_SUCCESS
• DBX_PLUGIN_BAD_SESSION - session は有効ではありません。
• DBX_PLUGIN_BAD_POINTER - indexp は NULL であるか、または countp が NULL です。
• DBX_PLUGIN_BAD_ARG - fdinfo_size が有効でないか、または * countp == 0。
• DBX_PLUGIN_UNAVAILABLE - プロセスはアクティブではないか、またはメモリー内に情報がありません。

• 各モジュールに関する情報を別々に入手するために対話式で呼び出す。 または
• モジュールの合計数を得るために 1 回呼び出し、 すべてのモジュールに関する情報を同時に得るためにもう 1 回呼び出す。

typedef int (*dbx_plugin_modules_service_t)(dbx_plugin_session_t session,
                                            dbx_plugin_modinfo_t *infop,
                                            size_t modinfo_size,
                                            unsigned int *indexp,
                                            unsigned int *countp)

• DBX_PLUGIN_SUCCESS
• DBX_PLUGIN_BAD_SESSION - session は有効ではありません。
• DBX_PLUGIN_BAD_POINTER - indexp は NULL であるか、または countp が NULL です。
• DBX_PLUGIN_BAD_ARG - modinfo_size が有効でないか、または * countp == 0。

• メイン・スレッド・スタック領域 (DBX_PLUGIN_REGION_STACK)
• ユーザー・データ領域 (DBX_PLUGIN_REGION_DATA)
• プロセスのプライベート・データ領域 (DBX_PLUGIN_REGION_SDATA)
• メモリーのマップ先の領域 (DBX_PLUGIN_REGION_MMAP)
• 共用メモリー領域 (DBX_PLUGIN_REGION_SHM)

• 1 つの領域に関する情報を別途入手するために対話式で呼び出す。 または
• 領域の合計数を得るために 1 回呼び出し、 すべての領域に関する情報を同時に得るためにもう 1 回呼び出す。

typedef int (*dbx_plugin_regions_service_t)(dbx_plugin_session_t session,
                                            dbx_plugin_reginfo_t *infop,
                                            size_t reginfo_size,
                                            unsigned int *indexp,
                                            unsigned int *countp)

• DBX_PLUGIN_SUCCESS
• DBX_PLUGIN_BAD_SESSION - session は有効ではありません。
• DBX_PLUGIN_BAD_POINTER - indexp は NULL であるか、または countp が NULL です。
• DBX_PLUGIN_BAD_ARG - reginfo_size が有効でないか、または * countp == 0。
• DBX_PLUGIN_UNAVAILABLE - セッションはライブ・プロセスを表し、領域にはアクセスできません。

• 1 つのスレッドに関する情報を別途入手するために対話式で呼び出す。 または
• スレッドの合計数を得るために 1 回呼び出し、 すべてのスレッドに関する情報を同時に得るためにもう 1 回呼び出す。

typedef int (*dbx_plugin_threads_service_t)(dbx_plugin_session_t session,
                                            dbx _plugin_thrdinfo_t *infop,
                                            size_t thrdinfo_size,
                                            tid64_t *indexp,
                                            unsigned int *countp)

• DBX_PLUGIN_SUCCESS
• DBX_PLUGIN_BAD_SESSION - session は有効ではありません。
• DBX_PLUGIN_BAD_POINTER - indexp は NULL であるか、または countp が NULL です。
• DBX_PLUGIN_BAD_ID - *indexp は有効な ID ではありません。
• DBX_PLUGIN_BAD_ARG - thrdinfo_size は有効ではないか、または *countp ==0。
• DBX_PLUGIN_UNAVAILABLE - プロセスはアクティブではないか、またはメモリー内にエントリーがありません。

• 1 つの pthread に関する情報を別途入手するために対話式で呼び出す。 または
• pthread の合計数を得るために 1 回呼び出し、 すべての pthread に関する情報を同時に得るためにもう 1 回呼び出す。

typedef int (*dbx_plugin_pthreads_service_t)(dbx_plugin_session_t session,
                                             dbx_plugin_pthinfo_t *infop,
                                             size_t pthrdinfo_size,
                                             pthdb_pthread_t *indexp,
                                             unsigned int *countp)

• DBX_PLUGIN_SUCCESS
• DBX_PLUGIN_BAD_SESSION - session は有効ではありません。
• DBX_PLUGIN_BAD_POINTER - indexp は NULL であるか、または countp が NULL です。
• DBX_PLUGIN_BAD_ARG - pthrdinfo_size は有効でないか、または * countp == 0。

typedef int (*dbx_plugin_reg_service_t)(dbx_plugin_session_t session,
                                        uint64_t reg_flags,
                                        uint64_t id,
                                        dbx_plugin_context_t *contextp,
                                        size_t context_size)

• DBX_PLUGIN_SUCCESS。
• DBX_PLUGIN_BAD_SESSION - session は有効ではありません。
• DBX_PLUGIN_BAD_ID - id は有効ではありません。
• DBX_PLUGIN_BAD_ARG - reg_flags は有効ではないか、または context_size は有効ではありません。
• DBX_PLUGIN_BAD_POINTER - contextp は NULL です。
• DBX_PLUGIN_UNAVAILABLE - プロセスはアクティブではないか、 またはスレッドはカーネル・モードであるのにレジスターにアクセスできません。

typedef int (*dbx_plugin_reg_service_t) (dbx_plugin_session_t session,
                    uint64_t reg_flags,
                                  uint64_t id,
                                  dbx_plugin_context_t *contextp,
                                  size_t context_size)

• DBX_PLUGIN_SUCCESS
• DBX_PLUGIN_BAD_SESSION - session は有効ではありません。
• DBX_PLUGIN_BAD_ID - id は有効ではありません。
• DBX_PLUGIN_BAD_ARG - reg_flags は有効ではないか、または context_size は有効ではありません。
• DBX_PLUGIN_BAD_POINTER - contextp は NULL です。
• DBX_PLUGIN_UNAVAILABLE - プロセスはアクティブではないか、 またはスレッドはカーネル・モードであるのにレジスターにアクセスできません。

typedef int (*dbx_plugin_reg_service_t)(dbx_plugin_session_t session,
                                        uint64_t reg_flags,
                                        uint64_t id,
                                        dbx_plugin_context_t *contextp,
                                        size_t context_size)

• DBX_PLUGIN_SUCCESS
• DBX_PLUGIN_BAD_SESSION - session は有効ではありません。
• DBX_PLUGIN_BAD_ID - id は有効ではありません。
• DBX_PLUGIN_BAD_ARG - reg_flags は有効ではないか、または context_size は有効ではありません。
• DBX_PLUGIN_BAD_POINTER - contextp は NULL です。
• DBX_PLUGIN_UNAVAILABLE - プロセスはアクティブではないか、 またはスレッドはカーネル・モードであるのにレジスターにアクセスできません。

typedef int (*dbx_plugin_reg_service_t)(dbx_plugin_session_t session,
                                        uint64_t reg_flags,
                                        uint64_t id,
                                        dbx_plugin_context_t *contextp,
                                        size_t context_size)

• DBX_PLUGIN_SUCCESS
• DBX_PLUGIN_BAD_SESSION - session は有効ではありません。
• DBX_PLUGIN_BAD_ID - id は有効ではありません。
• DBX_PLUGIN_BAD_ARG - reg_flags は有効ではないか、または context_size は有効ではありません。
• DBX_PLUGIN_BAD_POINTER - contextp は NULL です。
• DBX_PLUGIN_UNAVAILABLE - プロセスはアクティブではないか、 または pthread に関係付けられたカーネル・スレッドはカーネル・モードであるのでレジスターにアクセスできません。

typedef int (*dbx_plugin_mem_service_t)(dbx_plugin_session_t session,
                                        uint64_t addr,
                                        void *buffer,
                                        size_t len)

• DBX_PLUGIN_SUCCESS
• DBX_PLUGIN_BAD_SESSION - session は有効ではありません。
• DBX_PLUGIN_BAD_POINTER - buffer は NULL です。
• DBX_PLUGIN_UNAVAILABLE - addr から読み取れません。

typedef int (*dbx_plugin_mem_service_t)(dbx_plugin_session_t session,
                                        uint64_t addr,
                                        void *buffer,
                                        size_t len)

• DBX_PLUGIN_SUCCESS
• DBX_PLUGIN_BAD_SESSION - session は有効ではありません。
• DBX_PLUGIN_BAD_POINTER - buffer は NULL です。
• DBX_PLUGIN_UNAVAILABLE - addr に書き込めません。

typedef int (*dbx_plugin_sym_service_t)(dbx_plugin_session_t session,
                                        dbx_plugin_sym_t *symbols,
                                        size_t syminfo_size,
                                        unsigned int count)

• DBX_PLUGIN_SUCCESS
• DBX_PLUGIN_BAD_SESSION - session は有効ではありません。
• DBX_PLUGIN_BAD_ARG - syminfo_size は有効ではありません。
• DBX_PLUGIN_BAD_POINTER - symbols は NULL です。

typedef int (*dbx_plugin_sym_service_t)(dbx_plugin_session_t session,
                                        dbx_plugin_sym_t *symbols,
                                        size_t syminfo_size,
                                        unsigned int count)

• DBX_PLUGIN_SUCCESS
• DBX_PLUGIN_BAD_SESSION - session は有効ではありません。
• DBX_PLUGIN_BAD_ARG - syminfo_size は有効ではありません。
• DBX_PLUGIN_BAD_POINTER - symbols は NULL です。

typedef int (*dbx_plugin_print_service_t)(dbx_plugin_session_t session,
                                          int print_mode,
                                          char *message)

• DBX_PLUGIN_SUCCESS
• DBX_PLUGIN_BAD_SESSION - session は有効ではありません。
• DBX_PLUGIN_BAD_ARG - print_mode は有効ではありません。
• DBX_PLUGIN_BAD_POINTER - message は NULL です。

alias("intprt", "plugin xyz interpret");

alias("intprt2(addr, count, format)", "addr / count format; plugin xyz interpret addr");

typedef int (*dbx_plugin_alias_service_t)(dbx_plugin_session_t session,
                                          const char *alias,
                                          const char *expansion)

• DBX_PLUGIN_SUCCESS
• DBX_PLUGIN_BAD_SESSION - session は有効ではありません。
• DBX_PLUGIN_BAD_ARG - alias は有効ではありません。
• DBX_PLUGIN_BAD_POINTER - alias は NULL であるか、または expansion が NULL です。
• DBX_PLUGIN_UNAVAILABLE - 同じ名前の付いた別名が既に存在しています。

1. 以下の例は、help サブコマンドと hello サブコマンドを定義します。

   example.c: 
   
   #include <sys/dbx_plugin.h>
   
   dbx_plugin_session_t sid;
   dbx_plugin_services_t dbx;
   
   static void usage(void);
   static void hello_cmd(void);
   
   int
   dbx_plugin_version(void) {
       return DBX_PLUGIN_VERSION_1;
   }
   
   int dbx_plugin_session_init(dbx_plugin_session_t session,
                               const dbx_plugin_services_t *servicep) {
       /* record session identifier */
       sid= session;
   
       /* record dbx service */
       memcpy(&dbx, servicep, sizeof(dbx_plugin_services_t));
   
       (*(dbx.alias))(sid, "hello", "plugin example hello");
       (*(dbx.alias))(sid, "help", "plugin example help");
   
       return 0;
   
   }
   
   void
   dbx_plugin_session_command(dbx_plugin_session_t session,
                              int argc,
                              char *const argv[]) {
       if (argc == 0 || (argc == 1 && strcmp(argv[0], "help") == 0)) {
   
   	usage();
   	return;
       }
       if (argc == 1 && strcmp(argv[0], "hello") == 0) {
   	hello_cmd();
   	return;
       }
       (*(dbx.print))(sid,DBX_PLUGIN_PRINT_MODE_ERR,
   		   "unrecognized command¥n");
   
   }
   
   void
   dbx_plugin_session_event(dbx_plugin_session_t session,
                            int event,
                            dbx_plugin_event_info_t *event_infop) {
       /* ignore event notifications */
   }
   
   void
   dbx_plugin_session_destroy(dbx_plugin_session_t session){
       /* no clean up to perform */
   }
   
   static
   void
   usage(void) {
       (*(dbx.print))(sid,DBX_PLUGIN_PRINT_MODE_OUT,
                          "Subcommands for Plug-in ¥"example¥":¥n¥n" ¥
                          "   help  - displays this output¥n" ¥
                          "   hello - displays a greeting¥n" ¥
   		   "¥n");
   }
   
   static
   void
   hello_cmd(void) {
       (*(dbx.print))(sid,DBX_PLUGIN_PRINT_MODE_OUT,
   		   "Hello dbx World!¥n");
   
   }

   example.exp:
   
   dbx_plugin_version
   dbx_plugin_session_init
   dbx_plugin_session_command
   dbx_plugin_session_event
   dbx_plugin_session_destroy

2. このサンプル・プラグインをコンパイルするには、次のように入力します。

   cc -q64 -o libdbx_example.so example.c -bM:Sre -bE:example.exp -bnoentry