xcrash README Last modified: October 20, 1993 xcrash DESCRIPTION: ====== ============ This program was developed in an attempt to increase reliability in the area of X servers. I have used a number different X servers and have found a few problems with memory leaks and crashes. This is especially true when using many different line types, styles, etc. If a dashed line does not draw dashed correctly, it is a problem which needs to be fixed. If drawing a dashed line crashes the server, it is a critical problem which can stop development. If it crashes for a customer... well, there goes the drawing of the nuclear reactor. This program draws randomized primitives in an X window looking for these problems. It can be used in development of X servers to find bugs which were introduced by fixes or features. It can also be used by the purchaser of an X server to see how robust it is or is going to be in the area of drawing primitives (one of the main functions of an X server). There are a number of test suites for the X server. Unisoft's is one which can be used for a "full" evaluation. The T7 test suite (which in an earlier version of this README I mistakenly attributed to Unisoft), could also be used for this purpose. This program does not attempt to replace those suites. xcrash does not check the primitives to see if they are being drawn correctly. It only looks for critical server failures. Therefore, for full server validation, this program is only a small (but important) part. There is a shell script "xcrashmon" included with this package which can be used in development of an X server. It will bring up an X server and runs tests waiting for a server crash. If the server crashes, the script causing the crash is saved off so it can be replayed later to see what the problem is. After the script is saved off, xcrashmon will do a dbx/where if there is a core file and then start the process over. The xcrashmon script will probably need be modified to suit your system since currently, it is only modified to support the Sun and RS/6000. xcrash has a -nasty mode. This mode has shows problems in a large number of servers. Primitives will be drawn "way off" screen. Because of the way most servers clip primitives, your machine may swap itself to death when this is run. There is a man page included in this package. To read it, you can use (on many systems): % nroff -man xcrash.man | more MAKING AND RUNNING xcrash: ====== === ======= ======= To make xcrash on a system which has X setup nicely use: % xmkmf -a % make For those awful systems which dont have xmkmf (and sometimes not even imake!) you can try the following: % cc xcrash.c -L/usr/lib/X11 -lX11 -o xcrash If that doesn't work, try finding a UNIX guru (possibly yourself) to track down the problem. When that completes, try the command: % xcrash -help If you get no error messages, things have probably built correctly. Now you will probably want to run it. First, make sure you have nothing important currently running under X. If you do, it will be lost if the server crashes. To see if your server has basic functionality try: % xcrash -tests 10000 This will generate 10000-20000 random X primitive draw calls to your server. Half of the screen (on the left hand size) should fill with garbage. If your server stays up through this test, it probably has basic functionality in the area of primitive drawing. Check to see how much memory the server process is using. This may hint to memory leaks or other problems (although on most machines the server process will have increased in size since it was started). If it stayed up for that run, see if your server is 'golden' with: % xcrash -nasty -tests 10000 If it makes it through this without crashing and things looks like they are drawing correctly, you are probably in very good shape in the basic primitve area (better than I've seen). If your server crashes, you can record and playback a session like this: % xcrash -v -tests 10 > out1 % xcrash -in out1 This will record and play back 10 tests. If your server crashes during that time, you have a script (out1) which you can send to someone to show them the problem. PROBLEMS WITH xcrash: ======== ==== ======= Problems with compilation of xcrash: 1] The srandom() and random() functions are used to get random values. I know that these are different on some systems, but I can't remember which and I don't have them around. If you have problems in this area, replace the calls to srand and rand with anything on your system that will seed the random number generator and generate a random number. 2] The time() function is used by the program and may be different on some systems. It is used to seed the random number generator. If you have a problem with this function, just pull it out and use the -seed parameter on the program line. 3] The code is not ANSI because I needed to support non-ansi compilers. BUGS in xcrash: ==== == ======= To compare a single test against another server, that server should match some of the basic properties of the one which created the test (same number of bitplanes, etc). The program should handle this in some way. If you have and suggestions, problems, fixes, or additions to xcrash you are welcome to mail me at ess@netcom.com. I will attempt to respond. For bugs, fixes, etc. please include the version number (you can find this by running verbose mode), machine you are running on, operating system, X11 release and patch numbers in your message. Bugs found in your server (crashes, dumps, hangs, etc), should be directed to whoever you got the X server from. CREDITS: ======== Eric Swildens, while contracting at HaL Computer Systems, is the author of xcrash. Thanks go to Barrett Blake, Steve Goldsmith, Mike Lindzey, Greg Moore, and Bob Pendelton of Hal Computer Systems, Inc. who have provided input in development of the program. A big thanks also goes to the people who created and continue to support X. Another quality product from: ess@netcom.com Eric Swildens