Tips for running Csound under Linux
-----------------------------------

1. Compiling the kernel
-----------------------

The following notes apply to version 2.4.18 (should be OK with newer
2.4 kernels, but definitely not 2.5, 2.2, or old 2.4).

1.1 Editing kernel headers
--------------------------

In include/asm-i386/param.h, these lines should be modified:

  #ifndef HZ
  #define HZ 1024       /* (was originally 100) */
  #endif

  [...]

  #ifdef __KERNEL__
  # define CLOCKS_PER_SEC 1024    /* frequency at which times() counts */
  #endif                          /* (should be the same as HZ) */

this increases the frequency of the kernel timer from 100 to 1024 Hz,
allowing better real-time performance (i.e. smaller buffers and less
latency with stable playback).
There are two possible disadvantages: average performance might be
slightly reduced due to the more frequent interrupts, and the changed
HZ value may break some programs (though, in practice, only some
top-like utilities (not including top) were found to work incorrectly,
and I have been using Linux with an increased HZ for years without
problems).

Additionally, these lines can be changed in include/linux/sched.h
for shorter time slices in multitasking operation:

  #define DEF_COUNTER     (10)    /* 10.24 ms time slice */
  #define MAX_COUNTER     (20)

1.2 Kernel configuration
------------------------

When configuring the kernel, it is recommended to enable these (of
particular importance is enabling IDE DMA if you have any IDE disks):

  Processor type and features:
    MTRR (Memory Type Range Register) support
  ATA/IDE/MFM/RLL support:
    Generic PCI bus-master DMA support
    (do not forget to include modules for the motherboard chipset
    you are using)
  Kernel hacking:
    Magic System Request Key support

I have also attached the configuration file (.config) I used when
compiling the kernel. Of course it cannot be used on other machines
with different hardware setup and different kernel version, but it
can be useful for tips on setting some configuration parameters.

2. Setting system parameters at boot time
-----------------------------------------

The following code can be added to a script that runs once during
system start-up (it depends on distribution which file should be
changed. On RedHat/Mandrake it is (AFAIK) /etc/rc.d/rc.local, on
SuSE it is /etc/init.d/boot.local; do not know about Debian).
You may need to customize it to match your hardware configuration,
and experimenting with some parameters is encouraged.

WARNING: incorrect use of hdparm can result in system hangs or
crashes, as well as loss or corruption of data. Use this utility
with caution.

  # this line enables use of the SysRq key
  echo -e "1" > /proc/sys/kernel/sysrq

  sync
  # set hard disk parameters (do not forget to change /dev/hda to
  # whatever you are using). If there are multiple hard disks, more
  # similar lines can be added.
  # The relevant parameters are:
  #   -d1     enable use of DMA (this is very important ! Without DMA,
  #           hard disk transfer speed can be reduced to 1-2 MB / sec,
  #           and CPU usage significantly increased)
  #   -u1     unmask IRQ during disk operations. Improves the
  #           performance of any application that is running while disk
  #           transfers occur.
  #   -A1     enable drive read-lookahead
  #   -W1     enable write caching (this may be dangerous, so you can
  #           omit this option for safety; I do not have problems with
  #           it, though)
  #   -a192   increase read-ahead (improves the performance of
  #           sequential reading of multiple large files (e.g. when
  #           mixing sound files)) to 96k. May need some experimenting
  #           to find the best value.
  hdparm -f -d1 -u1 -A1 -W1 -a192 /dev/hda
  sync
  # same as above, but for CD-ROM (this supports less parameters).
  # Again, /dev/hdc should be replaced with the device you have.
  hdparm -f -d1 -u1 -a192 /dev/hdc
  sync
  # the following line controls the buffering of disk writes. Note that
  # it assumes a Hz value of 1024. For the exact meaning of parameters,
  # refer to kernel documentation. The purpose of the changes here is
  # to have the buffers flushed earlier.
  echo -e "15 4096 64 256 1536 5120 30 0 0"	> /proc/sys/vm/bdflush
  # this line sets swap parameters. Read Documentation/sysctl/vm.txt
  # and experiment to find the best values.
  echo -e "4096 32 64"				> /proc/sys/vm/kswapd
  sync

3. Creating ext2fs filesystem
-----------------------------

When formatting partitions to be used under Linux, using the right
parameters for mke2fs can improve filesystem performance.
In particular, it is recommended to add -b 4096 -g 16384 to increase
block/group size.
Also, some space can be saved with -m 1 (the default would be 5), or,
on non-root partitions even -m 0, as well as using less inodes on
large partitions (but at least about 300,000 is recommended); if the
partition size is greater than 3 GB, use -i 8192, and above 6 GB
-i 16384 (in the latter case also -g 32768).

4. Running Csound
-----------------

For real-time use, the -d -m0 -H0 command line flags are recommended
(especially under X). To get rid of all console messages, add
> /dev/null 2>&1 to the end of the command (this makes it impossible
to see error messages, so use it only with well tested orchestras;
alternatively, the messages can be redirected to a file for later
reading).

If you have Csound 4.23.4.1 or newer, the --expression-opt flag can
be added for improved performance (note: this does not allow using
the i() function with expression argument - though that is not
recommended in general even without --expression-opt).

The --sched option can improve real-time performance, but note that
  * it requires Csound to be installed setuid root (which is actually
    done by default).
  * this option works only from the command line, and *not* from the
    CSD options tag, or .csoundrc.
  * --sched can be dangerous, as it can hang the system if CPU usage
    of Csound reaches 100%. In this case, the only way to get back
    control over the system is using Alt+SysRq key combinations to
    terminate all running programs.

For ALSA, the -B option sets the total buffer size (which controls
latency), while -b is the period size (this determines the rate at
which polling occurs) and is expected to have a value that is less
than that of -B. In practice, -b 32 seems to be sufficient, while
-B depends on sound card and system (I can use -B 128 with --sched).

The best results for deferred time benchmarking can be achieved with
  csound -d -m128 -H0 -f -h -o dac -n --sched --expression-opt
(the -o dac is there only to avoid the error message due to using
--sched in deferred time; it is overridden by -n)
Warning: this hangs the system until Csound performance is finished.

