How to debug IIIM related problems

IIIM is a Input Method framework mainly used in Asian locales. This is a memo how to debug iiim related problems.

 Server modules, iiimx, iiimd and iiim-xbe 

When starting up, iiimx is invoked by IM script. Then it invokes three daemons, iiim-xbe, iiimd and iiim-panel.
/usr/bin/iiimx -iiimd iiimd -nodaemon -desktop ... iiim-panel --disable-crash-dialog iiim-xbe
iiim-xbe is mainly used in non UTF-8 locales and responsible to work as XIM and XIMP server. iiim-xbe is also used in UTF-8 locales as a starter of IIIM AUX services. iiimd is used as IIIM server. iiim-panel is used mainly as Input method switcher. So when debungging iiim related problems, you will need to check iiim-xbe and iiimd behavior as a server module.

 Client modules, im-iiim.so, xiiimp.so.2, ximp40.so.2 and ximcp.so.2 

  When GTK application is invoked, im-iiim.so is loaded for connecting IIIM server because GTK_IM_MODULE=iiim is set in start up script.
         o GTK app -> GTK API -> im-iiim.so -> libiiim*.so -> [IIIM protocol] -> iiimd
  When Java/X application is invoked on UTF-8 locales, xiiimp.so.2 is loaded for connecting IIIM server.
         o X app (UTF-8) -> X API -> xiiimp.so.2 -> libiiimc*.so -> [IIIM protocol] -> iiimd
  When Java/X application is invoked on non UTF-8 locales in s10, ximp40.so.2 is loaded for connecting to XIMP server.
         o X app (non UTF-8) -> X API -> ximp40.so.2 -> [XIMP protocol] -> iiim-xbe -> libiiim*.so -> [IIIM protocol] -> iiimd
  When Java/X application is invoked on non UTF-8 locales in s11, ximcp.so.2 is loaded for connecting to XIM server.
         o X app (non UTF-8) -> X API -> ximcp.so.2 -> [XIM protocol] -> iiim-xbe -> libiiim*.so -> [IIIM protocol] -> iiimd

  So when debugging a client application for Input method, you will need to check im-iiim.so, xiiimp.so.2, ximp40.so.2 and ximcp.so.2 behavior based on the application framwork. For example, the following tables shows used modules for Japanese locales.

 Debugging on IIIM server side 

  Some dtrace scripts for debugging iiim modules are available. You can download iiim-dtrace-debug.zip. If you don't have iiimf source files, you can take it's copy from im-sdk-include.zip (This zip file includes only needed header files). Once these are downloaded, unzip these files.
# unzip iiim-dtrace-debug.zip # cd iiim-dtrace-debug # unzip ../im-sdk-include.zip

 iiimd 

  iiimd-debug is a dtrace script and can be used to trace IIIM protocol. If you encounter a problem related IIIM, it may be useful whether iiimd is working fine to look this output with comparing normal behavior.
# ./iiimd-debug -h ./iiimd-debug: getopts: h bad option(s) Usage: iiimd-debug -p <uid> [-t <num>] -u <uid> # User ID for iiimd -t <num> # num bytes used by tracemem output # ./iiimd-debug -u jdstest uid=jdstest iiimd_pid=22280 tracemem=0 S->C:1:1 IM_AUX_GETVALUES_REPLY (opcode=63,size=108) S->C:1:2 IM_AUX_DRAW (opcode=5c,size=108) S->C:1:2 IM_HOTKEY_STATE_NOTIFY (opcode=22,size=8) C->S:1:2 IM_AUX_DRAW_REPLY (opcode=5d,size=76) : If -t option is specified (like -t 128), you can dump first 128bytes of the payload. S->C:1:1 IM_STATUS_DRAW (opcode=34,size=64) 0 1 2 3 4 5 6 7 8 9 a b c d e f 0123456789abcdef 0: 01 00 01 00 01 00 00 00 30 00 00 00 21 ff 08 00 ........0...!... 10: 00 00 00 00 00 00 00 00 34 ff 08 00 00 00 00 00 ........4....... 20: 00 00 00 00 2f ff 08 00 00 00 00 00 00 00 00 00 ..../........... 30: 2b ff 08 00 00 00 00 00 00 00 00 00 00 00 00 00 +............... 40: fc fb 13 08 70 21 00 00 ac b5 c4 fe 00 00 00 00 ....p!.......... 50: 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 60: 05 00 00 00 00 00 00 00 90 99 58 08 00 81 58 08 ..........X...X. 70: 00 00 00 00 00 00 00 00 02 00 00 00 00 00 00 00 ................
You can understand IIIM protocol by iiimp_spec.html.

 iiim-xbe 

  iiim-xbe-debug is a dtrace script and can be used to trace XIMP protocol and XIM protocol (X client message only). If your application is Java/X and it is running under non UTF-8 locales, you should check this output and compare output with normal behavior.
# ./iiim-xbe-debug -h ./iiim-xbe-debug[14]: getopts: h bad option(s) Usage: iiim-xbe-debug -u <uid> -u <uid> # User ID for iiim-xbe # ./iiim-xbe-debug -u jdstest uid=jdstest iiim_xbe_pid=22285 C->S:* XIMProtocol:XIMP_CREATE Client Window ID=54526053, InputStyle=1026, mask=800001 S->C:5 XIMProtocol::XIMP_CREATE_RETURN ICID=5 C->S:5 XIMProtocol:XIMP_CLIENT_WINDOW ICID=5, Client Window ID=54526053 S->C:5 XIMProtocol::XIMP_CLIENT_WINDOW_RETURN ICID=5 C->S:5 XIMProtocol:XIMP_SETFOCUS ICID=5 7 IIIMCF_EVENT_TYPE_AUX_GETVALUES 8 IIIMCF_EVENT_TYPE_AUX_GETVALUES :

 Debugging on client side 

 GTK+ application 

  gtk-client-trace is dtrace script which traces the function calls in im-iiim.so and gtk_im_* functions in libgtk-x11-2.0.so.0.
# ./gtk-client-trace -h ./gtk-client-trace[14]: getopts: h bad option(s) Usage: gtk-client-trace -c <GTK program> | -p <pid> -c <GTK program> # GTK program path to be invoked. -p <pid> # PID for GTK program running.
If you want trace each functions, it may be useful.
# ./gtk-client-trace -p `pgrep gedit` program= pid=24832 dtrace: script '/dev/fd/11' matched 424 probes CPU FUNCTION 2 -> gtk_im_context_set_cursor_location (840afc8,8046b30,fe56e9bb,2) 2 -> gtk_im_context_get_type (8404728,8046b30,fe4d430f,8046b30) 2 <- gtk_im_context_get_type = 840ab10 2 -> gtk_im_multicontext_set_cursor_location (840afc8,8046b30,fe4d430f,8046b30) 2 -> gtk_im_multicontext_get_slave (840afc8,2f87395d,fe4d6206,8405f08) 2 <- gtk_im_multicontext_get_slave = 840fdf0 2 -> gtk_im_context_set_cursor_location (840fdf0,8046b30,fe4d6206,8405f08)

 Java/X application 

  x-client-trace is dtrace script which traces the function calls in ximp40.so.2, xiiimp.so.2 and ximcp.so.2.
# ./x-client-trace -h ./x-client-trace[16]: getopts: h bad option(s) Usage: ximp-client-trace -c <X program> | -p <pid> -c <X program> # X program path to be invoked. -p <pid> # PID for X program running.
If you want trace each functions, it may be useful.
# ./x-client-trace -c /usr/bin/xterm : CPU FUNCTION 1 -> XOpenIM (80905a8,0,0,0) 2 -> _Ximp_OpenIM (80a3ca0,80905a8,0,0) 2 -> _Ximp_OpenIM_Resource (80c74e8,2,809c74c,fee3c000) 2 -> _Ximp_Environ (0,fef9f560,feff0400,0) 2 <- _Ximp_Environ = 5 2 -> _Ximp_InputServerMode (80c74e8,0,fef9f560,feff0400)

 Tips for collecting needed data 

 To do first 

  If you encounter a problem, you should provide not only your problem description but also the following your environment information.

1. Solaris version, platform, iiimf patch level.
2. Login locale
3. Login session, CDE or JDS 
4. Input method frame work and Language Engine (like iiimf/atok)
5. Application name you encountered the problem.
6. Are you using dictionary setting by default? If you customized, please provide how to customize.

 A GTK/X application hangs after input method turns on 

  This situation is often reported. For many cases, the problem is in iiimd or iiim-xbe that are stopping or waiting something.
So first of all, you should try
% gcore `pgrep iiimd` % gcore `pgrep iiim-xbe` % gcore <application pid>
And check each stack trace whether it is normal or not.

  If iiimd is working fine, the following stack trace will be displayed
when waiting a connection.
one IMSocketTrans*IMSocketListen::accept()/poll one void*parent_watchdog/sleep many IMSocketTrans::recv/recv
% pstack core.9470 | c++filt 9470: iiimd -nodaemon -desktop -udsfile /tmp/.iiim-sayama/:11.0 -vardir /exp ----------------- lwp# 1 / thread# 1 -------------------- feef1eb7 pollsys (9118288, 1, 0, 0) fee96df6 poll (9118288, 1, ffffffff, feeeb1f4) + 4c 080af145 IMSocketTrans*IMSocketListen::accept() (80f4f38, 8047828, 8047838, 80a 10eb) + a1 080948c7 IMState*IIIMProtocol::accept(int) (8123480, 0, 4, 8230c28) + 23 080a3cc4 int IMSvr::start() (80478e0, feffb8f4, 8047978, 80bf371) + 40 080bf388 main (9, 80479a4, 80479cc, 807cfb0) + b0 0807d04d _start (9, 8047ad8, 8047ade, 8047ae8, 8047af1, 8047afa) + 7d ----------------- lwp# 2 / thread# 2 -------------------- feef1877 nanosleep (fbb0ef90, fbb0ef98) feedd709 sleep (a, 200, 8, 80bf242) + 31 080bf23a void*parent_watchdog(void*) (0, fef70000, fbb0efe8, feeed60e) + 1a feeed663 _thrp_setup (fba00240) + 9b feeed910 _lwp_start (fba00240, 0, 0, 0, 0, 0) ----------------- lwp# 9 / thread# 9 -------------------- feef1a07 recv (c, fb9fef18, 8, 0) fed9ca72 recv (c, fb9fef18, 8, 0, fef71008, 0) + 2a 080aef71 int IMSocketTrans::recv(void*,unsigned) (80f98e8, fb9fef18, 8, feee5f3 1) + 19 0809322e IIIMPTrans_read (8307d10, fb9fef18, 8, fc2cea66) + 26 fc2cea89 iiimf_stream_receive (8307b90, 8231728, fb9fef5c, fc2c9813) + 31 08093178 IIIMP_message*IIIMPTrans::receive() (8307d10, 8379190, 1, 8379190) + 1 8 08094830 bool IIIMProtocol::receive_and_dispatch(IMState*,int) (8123480, 821ef9 0, 0, feeec906) + 14 080a1090 IMScheduler_MTPC_thread_entry (82d5c08, fef70000, fb9fefe8, feeed60e) + 44 feeed663 _thrp_setup (fba00a40) + 9b feeed910 _lwp_start (fba00a40, 0, 0, 0, 0, 0)
  If iiim-xbe is working fine, the following stack trace will be displayed when waiting a connection.
% pstack core.9475 | c++filt core 'core.9475' of 9475: iiim-xbe ----------------- lwp# 1 / thread# 1 -------------------- feef1877 nanosleep (80479c0, 80479c8) feedd709 sleep (989680, 8047a28, 80479f8, 805e074) + 31 0805e081 main (1, 8047a28, 8047a30, 805d8fd) + 29 0805d93d _start (1, 8047b3c, 0, 80a3254, 8047b78, 8047b8e) + 7d ----------------- lwp# 2 / thread# 2 -------------------- feef1eb7 pollsys (8093128, 1, 0, 0) fee96df6 poll (8093128, 1, ffffffff, fec949ae) + 4c fec94a88 _XWaitForReadable (80961e0, fed9c000, fe40e6d8, fec9484c) + e8 fec9487d _XRead (80961e0, fe40e710, 20, fecc744d) + a9 fecc7682 _XReadEvents (80961e0, fe40ef60, 80dace8, fec9ddf6) + 246 fec9de36 XNextEvent (80961e0, fe40ef60, 4e0006c, 805fd0d) + 4a 0805fd29 void*XIMProtocol::xevent_loop(void*) (808bcc0, fef70000, fe40efe8, feeed60e) + 29 feeed663 _thrp_setup (fe300240) + 9b feeed910 _lwp_start (fe300240, 0, 0, 0, 0, 0) ----------------- lwp# 3 / thread# 3 -------------------- feef1eb7 pollsys (809c210, 1, 0, 0) fee96df6 poll (809c210, 1, ffffffff, fec949ae) + 4c fec94a88 _XWaitForReadable (809b8b8, fed9c000, fe2fe6d8, fec9484c) + e8 fec9487d _XRead (809b8b8, fe2fe710, 20, fecc744d) + a9 fecc7682 _XReadEvents (809b8b8, fef70000, fe2fef68, fec9ddf6) + 246 fec9de36 XNextEvent (809b8b8, fe2fef60) + 4a 08068a38 void*R6IMProtocol::xevent_loop(void*) (808c280, fef70000, fe2fefe8, feeed60e) + 28 feeed663 _thrp_setup (fe300a40) + 9b feeed910 _lwp_start (fe300a40, 0, 0, 0, 0, 0)
You should also try gtk-client-trace, x-client-trace dtrace script to check where application is hanging.
After you understood where application is hanging, you will check source files and would try more specialized dtrace or debug binary as a next step.

 jserver crash problem.

  jserver crash is often reported. If crash occured, core file is very useful. So please investigate this first. Also it is nice to provide the following information if crash problem can be reproducible.

1. Please provide the output of wnnstat、wnnstat -D、wnnstat -F for both before crash and after crash.
2. -s option of jserver can save the log file. So please modify
   /lib/svc/method/wnn8-server ${JSERVER} ${JSERVER_OPT} & to ${JSERVER} -s /var/tmp/log ${JSERVER_OPT} &
   and save /var/tmp/log when crash occured.