  Using The DOSEMU Sound System (SBEMU)
  Author: Alistair MacDonald, <A.MacDon-
  ald@slitesys.demon.co.uk>
  version dosemu-0.98.3

  The document describes the use of the DOSEMU Sound code (SBEMU), and
  what you can expect from it.
  ______________________________________________________________________

  Table of Contents


  1. Introduction

  2. What to (and what not to!) expect

     2.1 FM
        2.1.1 Technical Explanation
     2.2 MPU-401
     2.3 SB (Digital)
     2.4 DMA

  3. Using SBEMU

     3.1 DOSEMU Compile-time Configuration
     3.2 DOSEMU Run-time Configuration
        3.2.1 Changing the SBEMU settings
        3.2.2 Configuring Midi
           3.2.2.1 Using Midid
           3.2.2.2 Sending Midi direct to a device
     3.3 Configuring DOS
     3.4 Configuring the Applications
        3.4.1 Midi with Digital Audio
        3.4.2 SB Music with SB Audio
        3.4.3 Midi Music, No Audio

  4. Debugging SBEMU



  ______________________________________________________________________

  11..  IInnttrroodduuccttiioonn

  It is much better to be pessimistic about the capabilities of DOSEMU's
  sound code. The code itself provides an _E_M_U_L_A_T_I_O_N of the popular SB
  cards. The actual level of emulation that can be achieved is dependant
  upon the capabilities of the sound driver on your system. Currently
  the emulation can only talk to the OSS driver (included in the Linux
  kernel) although it has been written in a modular fashion to allow
  other drivers to be written. For more details on the internals please
  see the WWW pages at
  http://www.slitesys.demon.co.uk/a.macdonald/dosemu/sound/.

  It should be pointed out that not all of this information comes from
  my own knowledge and that parts come from the other developers and
  from users who have contributed code & comments. Unfortunately I tend
  to forget names and lose emails, so their names are not included.


  22..  WWhhaatt ttoo ((aanndd wwhhaatt nnoott ttoo!!)) eexxppeecctt

  The emulation consists of a number of parts, and I'll examine these
  separately.


  22..11..  FFMM

  The FM driver is the least complete. Most of the chip functions are
  there, but no audio output occurs. This means that software which uses
  the presence/operation of the timer should detect the timer presence,
  but if the audio needs/uses FM you will hear nothing.


  22..11..11..  TTeecchhnniiccaall EExxppllaannaattiioonn

  There are a number of problems with the FM emulation:


  1. Any FM output will have to be translated to appropriate OSS
     sequencer calls. These vary according to the SoundCard family
     (mainly between the cards with real FM synthesis and those with
     wavetable synthesis) You actually need to detect the card type and
     program it accordingly.

  2. The OSS sequencer doesn't allow you to change the parameters whilst
     a note is playing. Many games do this to provide their sound.


  22..22..  MMPPUU--440011

  This is the MIDI emulation. This should be fairly complete, but relies
  on the external daemon 'midid'. This is supplied and can be built
  easily.


  22..33..  SSBB ((DDiiggiittaall))

  This is the digital aspect of the audio output. It is the most mature,
  and also the buggiest aspect (because it is the most complex!) Most of
  the functionality up to SB-16 is implemented, although some things
  don't work. Note that SB (DSP) MIDI is not implemented, although
  MPU-401 emulation (above) is.


  22..44..  DDMMAA

  Whilst technically not part of the Sound System, the DMA emulation
  routines where developed primarily for SBEMU. These routines may have
  their own problems which may well impact on the running of SBEMU. As
  far as we know the only limitation is that they don't interface with
  the real DMA controller.


  33..  UUssiinngg SSBBEEMMUU

  SBEMU needs to be compiled into DOSEMU, AND turned on at run-time.
  Then your DOS applications need to be configured to use the emulation.
  (Just as they need to be configured to use your real sound card). The
  basic steps are given below.


  33..11..  DDOOSSEEMMUU CCoommppiillee--ttiimmee CCoonnffiigguurraattiioonn

  By default, DOSEMU is built with SBEMU support.


  33..22..  DDOOSSEEMMUU RRuunn--ttiimmee CCoonnffiigguurraattiioonn

  The default settings are:


      Base Address:   220
      IRQ:            5
      DMA:            1
      Midi Port:      330 (Not normally needed)




  Note that these do _N_O_T need to be the same as your real sound card.


  33..22..11..  CChhaannggiinngg tthhee SSBBEEMMUU sseettttiinnggss

  The DOSEMU Sound settings are controlled by the following entries in
  /etc/dosemu.conf (-- Note that there is some overlap here with the
  configuration notes in the README. This will be addressed at a later
  stage--) :


  $_sound = (off)         # sound support on/off
  $_sb_base = (0x220)
  $_sb_irq = (5)
  $_sb_dma = (1)
  $_sb_dsp = "/dev/dsp"
  $_sb_mixer = "/dev/mixer"
  $_mpu_base = "0x330"




  Note that these are the default values. $_sb_dsp and $_sb_mixer are
  pre-configured to work with the standard OSS-Free driver. You are
  unlikely to need to change these values unless you have multiple
  drivers in your kernel.( eg such as the Ultra project drivers).


  33..22..22..  CCoonnffiigguurriinngg MMiiddii

  The midi driver can be used in two way. It is possible to direct the
  output of the SBEMU midi driver directly to a sound card, or through
  the midid daemon. All midi traffic is directed at
  ~/.dosemu/run/dosemu-midi. You will need to create this, or link it to
  the appropriate device, according to your configuration. Details about
  this are given below.


  33..22..22..11..  UUssiinngg MMiiddiidd

  This is the preferred method of producing MIDI output. The midid is
  _N_O_T built at the same time as DOSEMU, but it is simple to build:



       % make midid





  This will create src/arch/linux/dosext/sound/midid/midid. You will
  probably want to copy this somewhere on your path, such as /usr/bin.
  Next you will need to create the output pipe for the SBEMU driver:




  % mkdir -p ~/.dosemu/run
  % rm -f ~/.dosemu/run/dosemu-midi
  % mknod ~/.dosemu/run/dosemu-midi p




  If you already have a ~/.dosemu/run directory then the mkdir will
  fail. This is not a problem.


  Finally, you need to start the midid program:



       % midid < ~/.dosemu/run/dosemu-midi &





  This will run the driver in the background, giving you your prompt
  back.You should now run DOSEMU. Midid will terminate when DOSEMU
  terminates.


  Note that midid currently only supports the Ultra driver (autodetected
  when DOSEMU is configured), OSS/Free (partially) and a NULL driver
  (which just outputs the data stream as text). Midid should detect
  which is applicable. Running midid with the argument -h will list the
  options.


  33..22..22..22..  SSeennddiinngg MMiiddii ddiirreecctt ttoo aa ddeevviiccee

  _T_h_i_s _w_i_l_l _O_N_L_Y _w_o_r_k _i_f _y_o_u_r _M_i_d_i _d_e_v_i_c_e _a_c_c_e_p_t_s _r_a_w _m_i_d_i _d_a_t_a _a_n_d _y_o_u
  _h_a_v_e _e_i_t_h_e_r _p_r_e_l_o_a_d_e_d _i_n_s_t_r_u_m_e_n_t_s _p_a_t_c_h_e_s_, _o_r _i_t _h_a_s _h_a_r_d_w_a_r_e _p_a_t_c_h_e_s_.
  _U_s_e _t_h_i_s _m_e_t_h_o_d _O_N_L_Y _i_f _y_o_u _c_a_n_n_o_t _u_s_e _t_h_e _p_r_e_v_i_o_u_s _m_e_t_h_o_d_, _a_n_d _d_o _n_o_t
  _E_X_P_E_C_T _s_u_p_p_o_r_t_.


  To use this method you simply need to link the SBEMU midi output file
  to the input of your MIDI device. The simplest method of doing this
  is:



       % mkdir -p ~/.dosemu/run
       % rm -f ~/.dosemu/run/dosemu-midi
       % ln -s /dev/MyMidiDevice ~/.dosemu/run/dosemu-midi




  Where /dev/MyMidiDevice is the path to your midi device. If you
  already have a ~/.dosemu/run directory then the mkdir will fail. This
  is not a problem.


  33..33..  CCoonnffiigguurriinngg DDOOSS

  You should set your BLASTER environment variable to match your DOSEMU
  settings. Note that these don't need to correspond to your real sound
  card. For a base SB with the values above, use the following DOS
  command:

  set BLASTER=A220 I5 D1 T1




  The T1 identifies this as a Type 1 SB device eg old! The precise
  version of 'SB' is up to you, but the lower the model, the more likely
  it is to work.


  33..44..  CCoonnffiigguurriinngg tthhee AApppplliiccaattiioonnss

  Bearing in mind what was stated above, the following are the
  recommended methods for configuring applications to use SBEMU. The
  first is the preferred method. If you need to manually set any
  parameters remember to use those you configured DOSEMU with.


  33..44..11..  MMiiddii wwiitthh DDiiggiittaall AAuuddiioo

  Configure the applications to use 'General Midi' for Music, and 'SB'
  for Digital Audio.


  33..44..22..  SSBB MMuussiicc wwiitthh SSBB AAuuddiioo

  Configure the application with 'SB' for Music & Audio. Note that if
  the system plans to use FM for the music you will not get music.


  33..44..33..  MMiiddii MMuussiicc,, NNoo AAuuddiioo

  Configure the application with 'General Midi' for Music and no Audio.


  44..  DDeebbuuggggiinngg SSBBEEMMUU

  The debugging output for SBEMU is enabled in the same way as all
  DOSEMU debug, and collected in the same manner. The debug flag for
  sound is 'S'. Because the DMA controller is hardware it uses the debug
  flag 'h'. To get basic debugging information into a file called
  sound.out use:



       % dos -D-a+Sh -o sound.out




  You can get slightly more verbose output is you use level 2 debugging
  (eg use -D-a+2Sh). If you need someone else to look at the debug
  output then feel free to send it to the list, but _P_L_E_A_S_E_, _r_e_m_o_v_e _a_n_y
  _u_n_n_e_c_e_s_s_a_r_y _d_e_b_u_g _o_u_t_p_u_t_, _a_n_d _g_i_v_e _a _D_E_T_A_I_L_E_D _d_e_s_c_r_i_p_t_i_o_n _o_f _t_h_e
  _p_r_o_b_l_e_m_. _I_d_e_a_l_l_y_, _u_s_e _t_h_e _b_u_g _r_e_p_o_r_t_i_n_g _t_o_o_lsubmit-bug-report.











