# 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

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

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

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

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

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

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