NEC PC Programmers Reference/PC-98xx Series Programmers Reference/Sound BIOS

The Sound BIOS is a toolkit for operating the OPN music playback/sound generation system. It has no default interrupt -- the interrupt must be established by the application.


Requirements

edit

The Sound BIOS requires a sound card that supports OPN MUSIC BIOS. It can only be used in normal mode.

Setting the Sound BIOS Interrupt

edit

The Sound BIOS interrupt is established by setting the byte at address 0xCEE00 to the interrupt number desired for use.

N88-BASIC sets Sound BIOS interrupt to 0xD2 by default.

Setup

edit

Sound BIOS expects access to specific regions of memory for its operation, among other requirements.

  • the DWORD beginning at 0000:05E0 must be reserved to it.
  • Status area of 256 bytes
  • Work area of 512 bytes
  • 96 bytes stack space

The status and work areas must be contiguous. To reserve space for Sound BIOS, set the offset into the segment so reserved where the work area begins to the WORD at 0xCEE06 (0 is acceptable). Before using Sound BIOS, set ES to 0xCEE0 and DI to the WORD at 0xCEE06. Set SS to the designated BIOS stack area segment and SI to the offset into the same.

Operation of the Sound BIOS

edit

The Sound BIOS is accessed by calling its designated interrupt with the command number in CPU reg AH. Each Sound BIOS command requires specific parameters. The following list of Sound BIOS commands explains the commands available and how to pass parameters to them.

Table of Sound BIOS Commands
AH Command Purpose Setup Config Struct Offset
0 INIT Setup PLAY command environment and song params. Sets tempo to 1 (120 bpm, 48 steps/min), note length to whole, and all track pointers to null. Must be called before using any other commands.

ES = Sound BIOS config/work segment. PLAY buffer should be configured before call.

1 PLAY Play note/operation macros stored to a buffer. ES:BX points to the 28-byte pointer table for each channel/track.

The first DWORD of the table contains the segment which contains the song. The succeeding DWORDS contain the offsets (in bytes 1-2) and the lengths in bytes (in bytes 3-4) of the track in the segment. The song cannot be more than 64k bytes in total.

  • 0x0: WORD Segment containing pointer table
  • 0x2: WORD pointer table offset
  • 0x4: WORD buffer length
  • 0x6: WORD pointer to beginning of song data
  • 0x8: WORD space allocated to buffer
2 CLEAR Clear PLAY buffer. If AL = 0, reset song. If AL = 1, clear for new song.
10 READ REG Reads a port on the music playback device. Takes AL as port to read; returns data to BX
11 WRITE REG Writes to a music playback device. This command can be invoked manually or in a PLAY buffer.
  • Manual use: AL takes port to write, BL takes data
  • Buffer: 1st byte = 0x81; 2nd byte = port; 3rd byte = data
12 SET TOUCH Specify length of note ("gate") as a proportion of the beat (called the "step"). Use this function to set the default length (or "staff") of a set of notes. Ratio is expressed in type of note - 1 / 8 (0 = eighth, 1 = quarter, 3 = half, 7 = full) Command can be invoked manually or in a PLAY buffer.
  • Manual use: AL takes playback channel to change, BL takes ratio of note to beat
  • Buffer: 1st byte = 0x82; 2nd byte = ratio of note to beat
0x12
13 NOTE Sounds a note on an instrument channel. Notes range from 0-96 (0-0x60), where 0x80 is a rest. May be invoked manually or in a PLAY buffer. This command operates in context of TOUCH setting. Length of note may be omitted, in which case default established by SET LENGTH is used.
  • Manual use: Instrument channel to AL. Key to BH. Duration to BL.
  • Buffer: 1st byte = note to play; 2nd byte = duration of note.
0x10
14 SET LENGTH Default note duration for succeeding notes on a channel as a fraction of the step. Modulated by SUSTAIN, ignored when duration is supplied with NOTE. May be invoked manually or in a PLAY buffer.
  • Manual use: Instrument channel to AL. Duration to BL.
  • Buffer: 1st byte = 83; 2nd byte = duration.
0x11
15 SET TEMPO Sets playback rate of the song. Each point of tempo counts for 48 beats per minute. May be invoked manually or in a PLAY buffer.
  • Manual use: song tempo to BL
  • Buffer: 1st byte = 84; 2nd byte = tempo.
0xC0
16 SET PARAM BLOCK Param input setup for a channel. May be invoked manually or in a PLAY buffer.
  • Manual use
    • AL = instrument channel to affect
    • ES:BX = start of block
    • DL = type of block (0 for WORD, 1 for byte)
  • Buffer: 1st byte = 85; 2nd byte = block type; WORD 3-4 = block offset; WORD 6-5 = block segment
17 READ PARAMS Read a FM synthesizer tone parameter into BX.
  • AL = channel to read from
  • BL = index number of tone param
18 WRITE PARAMS Write a tone param to FM synth channel. May be invoked manually or in a PLAY buffer.
  • Manual use:
    • AL = channel to modify
    • BL = tone param to write to
    • DX = value to write
  • Buffer: 1st byte = 0x86; 2nd byte = target param; 3rd byte/word = value
19 STOP Stops playback from PLAY buffer. Interrupt callback is disabled.
1A RESUME Resumes note playback from PLAY buffer.
1B LFO ON Unconditionally applies LFO effect to a channel. May be invoked manually or in a PLAY buffer.
  • Manual use: AL = channel to target
  • Buffer: byte = 0x87
1C LFO OFF Disables LFO effect on a channel. May be invoked manually or in a PLAY buffer.
  • Manual use: AL = channel to target
  • Buffer: byte = 0x87
1D PROC ON END Enable/disable proc call at track end
  • AL = channel to watch
  • ES:BX = address to call
  • CX
    • MSB: 1 - enabled; 0 - disabled
    • rest: length of track
  • 0xA: WORD proc call on song end
    • MSB: 1 - enabled; 0 - disabled
    • D14-0: length of track
  • 0xC: DWORD absolute address of call
1E SUSTAIN Sustain channel output. Use duration of 0 to omit. May be invoked manually or in a PLAY buffer.
  • Manual use:
    • AL = channel to sustain
    • BL = duration
  • Buffer: 1st byte = 0x89; 2nd byte = duration
1F VOLUME Channel volume. Operates on volume of carrier waveform. Influenced by param FB_ALG. May be invoked manually or in a PLAY buffer.
  • Manual use:
    • AL = channel
    • BL = volume
  • Buffer: 1st byte = 0x8A; 2nd byte = volume

Callback timing

edit

Sound BIOS uses OPN reg A as a tempo clock/metronome and reg B for modulation timing. It latches onto the PIC and monitors these regs to determine what action to take in accordance with the commands given. The metronome ticks at at least 5 msecs.

Compatibility with Manual Port Operations

edit

It is possible that manual operation of the sound card will interfere with the proper operation of Sound BIOS commands, causing unexpected behavior.