Documentation updates for 3.73 - Alex
authorterminatorX <>
Wed, 14 Aug 2002 17:44:44 +0000 (17:44 +0000)
committerterminatorX <>
Wed, 14 Aug 2002 17:44:44 +0000 (17:44 +0000)
INSTALL
README
README.PERFORMANCE
TODO

diff --git a/INSTALL b/INSTALL
index 04edf5f5a69a48294f47d18c9a9041ac934f6496..02626ae42462b86c1f026dcad044215d04a943b0 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -1,8 +1,9 @@
 terminatorX INSTALL:
 Copyright (C) 1999, 2000, 2001 by Alexander König <alex@lisas.de>
+http://terminatorX.cx
 
 Note: As of Version 3.70 you need to have LADSPA installed to compile
-terminatorX.
+terminatorX. To get LADSPA visit http: http://www.ladspa.org
 
 Quickstart:
 -----------
@@ -37,24 +38,37 @@ Step 1: Configure terminatorX.
                
                --enable-scheduler
                
-               NEW: since 3.5 this option is enabled by default, as you can
-               now operate the GUI while sound is playing, which can cause 
-               audio dropouts when the GUI and the sound thread run at the
-               same priority. You still need root privileges though.
-               
-               If you run terminatorX compiled with this option as root, the
-               engine thread will be run with FIFO-scheduling policy at the 
-               highest priority. This is somewhat dangerous I guess, as is
-               running programs as root anyway ;) If you want everybody to
-               run terminatorX as root (THIS IS DANGEROUS AND YOU SHOULD NOT
-               DO IT) cd (as root) into the directory where you installed
-               terminatorX (usually /usr/local/bin) and execute:
+               This option is now enabled by default. When run with root 
+               privileges terminatorX creates the engine thread with realtime
+               scheduling priorities which should result in much better
+               playback performance. Since Version 3.73 terminatorX supports
+               running suid root. If you install the terminatorX binary suid
+               root with the following commands: (with the default install
+               you should find the terminatorX binary in /usr/local/bin)
                
                > chown root terminatorX
                > chmod u+s terminatorX
                
-               I WARNED YOU! Anybody who can run this binary can completely
-               erase your hardisk. BE CAREFUL.
+               terminatorX will be started with root privileges even when an
+               "unprivileged" user runs the binary. terminatorX will then 
+               create the engine thread with realtime priority before any files
+               are written, any parameters are evaluated or connections to the 
+               X11 display are established. Right after that terminatorX will
+               drop root privileges, so the actual terminatorX code runs 
+               unprivileged.
+               
+               The problem is, with Linux' pthreads implementation the pthread
+               manager thread (that can not be influenced by terminatorX) will 
+               still run with root privileges.
+               
+               So there is a small chance that a malicious attacker could 
+               utilize terminatorX to acquire root privileges if installed suid
+               root, although it should require quite some effort to create an
+               exploit for that. On the other hand realtime scheduling 
+               massively improves the playback performance. So depending on who
+               can access your computer you will have to decide for yourself on
+               performance vs security. Alternatively you can of course run
+               terminatorX as root to achieve realtime scheduling.
                                                
                File support options:
                ---------------------
@@ -93,18 +107,20 @@ Step 1: Configure terminatorX.
                soundfiles. This requires ogg123 (Version >= 1.0RC2) and
                sox to be installed. 
                
-               Misc options:
+               Other options:
                -------------
-
-               --enable-3dnow
                
-               This will cause the binary to include 3DNow! accelerated 
-               mixing routines. The rule's simple: if your CPU does support
-               3DNow! then turn it on (it enhances performance quite a bit)
-               - if your machine doesn't, well then keep it disabled. A binary
-               created with 3DNow! acceleration will *not* run on machines
-               without 3DNow!.
+               --disable-gtk2
+               
+               If you've got gtk+ V2 installed but you want terminatorX to use
+               the old gtk+ V1.2 for some reason, use this switch to disable
+               gtk+ V2 code.
                
+               --disable-libxml2
+               
+               If you've got libxml V2 installed but you want terminatorX to 
+               use V1 instead, use this to disable libxml V1.
+
                --enable-debug
                
                This will cause terminatorX to display some debug messages on
diff --git a/README b/README
index f9d03c0413131ff359c6a8b685c43e6c4929a91d..397279b2b1ed54061c6f969b9e2c2229bc1b8ff4 100644 (file)
--- a/README
+++ b/README
@@ -1,7 +1,7 @@
-terminatorX V3.71 README
+terminatorX V3.73 README
 ------------------------
 
-Copyright (C) 1999, 2000 Alexander König
+Copyright (C) 1999 - 2002 Alexander König
 eMail: alex@lisas.de
 Homepage: http://www.terminatorX.cx
 
@@ -12,13 +12,8 @@ WARNING: TerminatorX comes with ABSOLUTELY NO WARRANTY. This software is known
 to lockup X11 or cause other problems under rare conditions. Don't use
 it on production servers. You have been warned!
 
-NEW: As the previous README was a pain to read I decided to move the
-documentation to an SGML "manual". This distribution contains that manual (in
-the doc-directory) as a set of HTML files for easy browsing and a postscript
-version for printing.
-
-Documentation on terminatorX included:
---------------------------------------
+Read that fine Manual:
+----------------------
 
     o ./INSTALL             - Information on installing terminatorX
     o ./README.GNOME        - Some hints on GNOME-integration
index a49daa21e4e5c5d7d53a9c418bf29e81362c2dd0..4145a2bed74ba7469c87c491e99ee0ff8f2a7faa 100644 (file)
@@ -1,9 +1,10 @@
 There are several things you can do to improve terminatorX performance:
 
 1. Don't use fancy gtk+ themes
-2. Compile an optimized binary
-3. Optimize your terminatorX setup
-4. Optimize your kernel
+2. Install suid root
+3. Compile an optimized binary
+4. Optimize your terminatorX setup
+5. Optimize your kernel
 
 In Detail:
 
@@ -23,13 +24,46 @@ like mad, too. This even hurts the performance of tX' very own widgets and
 therefore hurts playback performance quite a lot. So you shouldn't use these 
 kind of themes, neither.
 
-2. Compile an optimized binary
+2. Install suid root
+--------------------
+
+When run with root privileges terminatorX creates the engine thread
+with realtime scheduling priorities which should result in much better
+playback performance. Since Version 3.73 terminatorX supports running
+suid root. If you install the terminatorX binary suid root with the
+following commands: (with the default install you should find the
+terminatorX binary in /usr/local/bin)
+                
+ > chown root terminatorX
+ > chmod u+s terminatorX
+                
+terminatorX will be started with root privileges even when an
+"unprivileged" user runs the binary. terminatorX will then create the
+engine thread with realtime priority before any files are written, any
+parameters are evaluated or connections to the X11 display are
+established. Right after that terminatorX will drop root privileges,
+so the actual terminatorX code runs unprivileged.
+                
+The problem is, with Linux' pthreads implementation the pthread
+manager thread (that can not be influenced by terminatorX) will still
+run with root privileges.
+               
+So there is a small chance that a malicious attacker could utilize
+terminatorX to acquire root privileges if installed suid root,
+although it should require quite some effort to create an exploit for
+that. On the other hand realtime scheduling massively improves the
+playback performance. So depending on who can access your computer you
+will have to decide for yourself on performance vs security.
+Alternatively you can of course run terminatorX as root to achieve
+realtime scheduling.
+
+3. Compile an optimized binary
 ------------------------------
 
 This issue is covered in the INSTALL file mostly. Setting good optimization
 flags is a good idea although this step will proabably have the least effect.
 
-3. Optimize your terminatorX setup
+4. Optimize your terminatorX setup
 ----------------------------------
 
 The default settings for the GUI updates provide good realtime feedback. This
@@ -37,7 +71,7 @@ may cause problems on slower machines or evil gtk+-themes. If the GUI-thread
 causes dropouts in the audio-engine you should increase the Update-Delay value 
 in the options dialog.
 
-4. Optimize your kernel
+5. Optimize your kernel
 -----------------------
 
 The current 2.2.X-kernels show a pretty high latency. This is problematic for
diff --git a/TODO b/TODO
index 716f7705b3fc655d670218282193833e0fc75cec..dbfebcd40bb2631bfe9c0b511004bdddecd804ab 100644 (file)
--- a/TODO
+++ b/TODO
@@ -1,55 +1,41 @@
 terminatorX TODO:
 
-These are the things I´d like to implement IF I have the time.
+DISCLAIMER: I might implement some of these features in random order. You can 
+accelerate development of a certain feature by sending me a patch ;)
 
-- MIDI interface (Josh Steiner is working on that)
+High priority milestones:
+-------------------------
 
-- port Bennos mmap technology into the new code
+I'd like to have this in 4.0:
 
-- more precise syncing
+- Rewrite the audio device layer, so that terminatorX operates at a fix block
+  size - this will allow correct playback of sequencer events even if played
+  back on a different soundcard then recorded.
 
-- a click filter for client triggers
+- Support ALSA drivers and allow usage of multiple audio devices at the same 
+  time.
+  
+- Switch the terminatorX set file format to XML so that sets recorded on one
+  platform can be loaded on other platforms, too.
 
-- code cleanup: I guess this will be on this list until development has stalled.
+- Support stereo LADSPA plugins somehow.
 
-DONE:
+- Move the "main buttons" on the top right to a menu bar in order to get the
+  GUI even more flexible.
 
-The following stuff has been on the list above and is now ipmlemented:
+Low priority milestones:
+------------------------
 
-[V3.71]
+This might come after 4.0:
 
-- stereo operation (this is up next)
+- Implement a sequencer editor GUI to delete, copy & paste, edit event etc.
 
-[V3.7]
+- Find a replacement for DGA mouse grabbing as that has some problems and 
+  might be gone sometime from now.
+  
+- Provide a MIDI interface to terminatorX.
 
-- support for LADSPA plugins
-
-[V3.6]
-
-- sequencer is here :)
-
-[V3.0]
-
-- Enhance audio quality with -DHANDLE_STOP -> no clicks.
-
-- Accept wavfiles that contain additional information (e.g. loops)
-
-- Support Y-mouse-movement for scratching
-
-[V2.4] Thanks to Adam Sjøgren <asjo@diku.dk> licmak.c is obsolete:
-
-- implement licmak with either perl, awk or sed.
-
-
-[V2.3] (use -DKEEP_DEV_OPEN in Makefile)
-
-- add a "keep device open" option and implement it
-  (this would help if you have problems opening device very often
-  due to memory fragmentation). And it would help me ;) as my card (or better
-  driver) clicks awfully when device is opened!
-
-OBSOLETE:
-
-[V3.0] no cmdline args anymore so...
-
-- correct getopt error handling.
+- Use libaudiofile, libvorbis, etc. for file loading to get rid of "piped
+  loading" and accelerate loading of ogg and mp3 files this way.
+  
+- Support other languages.