#include <stdint.h>

Include dependency graph for exSID.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	XS_VERSION "2.0pre"

#define	exSID_write(addr, data) exSID_clkdwrite(0, addr, data)

#define	exSID_read(addr) exSID_clkdread(0, addr)

Enumerations
enum	{ XS_CS_CHIP0, XS_CS_CHIP1, XS_CS_BOTH }

enum	{ XS_AU_6581_8580, XS_AU_8580_6581, XS_AU_8580_8580, XS_AU_6581_6581, XS_AU_MUTE, XS_AU_UNMUTE }

enum	{ XS_CL_PAL, XS_CL_NTSC, XS_CL_1MHZ }

enum	{ XS_MD_STD, XS_MD_PLUS }

Functions
int	exSID_init (void)

void	exSID_exit (void)

void	exSID_reset (uint_least8_t volume)

int	exSID_hwmodel (void)

uint16_t	exSID_hwversion (void)

int	exSID_clockselect (int clock)

int	exSID_audio_op (int operation)

void	exSID_chipselect (int chip)

void	exSID_delay (uint_fast32_t cycles)

void	exSID_clkdwrite (uint_fast32_t cycles, uint_least8_t addr, uint8_t data)

uint8_t	exSID_clkdread (uint_fast32_t cycles, uint_least8_t addr)

const char *	exSID_error_str (void)

Detailed Description

libexsid interface header file.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Chip selection values for exSID_chipselect()

Enumerator

XS_CS_CHIP0

6581

XS_CS_CHIP1

8580

XS_CS_BOTH

Both chips.

Warning: Invalid for reads: undefined behaviour!

◆ anonymous enum

anonymous enum

Audio output operations for exSID_audio_op()

Enumerator
XS_AU_6581_8580	mix: 6581 L / 8580 R
XS_AU_8580_6581	mix: 8580 L / 6581 R
XS_AU_8580_8580	mix: 8580 L and R
XS_AU_6581_6581	mix: 6581 L and R
XS_AU_MUTE	mute output
XS_AU_UNMUTE	unmute output

◆ anonymous enum

anonymous enum

Clock selection values for exSID_clockselect()

Enumerator
XS_CL_PAL	select PAL clock
XS_CL_NTSC	select NTSC clock
XS_CL_1MHZ	select 1MHz clock

◆ anonymous enum

anonymous enum

Hardware model return values for exSID_hwmodel()

Enumerator
XS_MD_STD	exSID USB
XS_MD_PLUS	exSID+ USB

Function Documentation

◆ exSID_audio_op()

int exSID_audio_op ( int operation )

exSID+ audio operations routine. Selects the audio mixing / muting option. Only implemented in exSID+ devices.

Warning: all these operations (excepting unmuting obviously) will mute the output by default.

Note: no accounting for SID cycles consumed.

Parameters

operation audio operation value, see exSID.h.

Returns: execution status

◆ exSID_chipselect()

void exSID_chipselect ( int chip )

SID chipselect routine. Selects which SID will play the tunes. If neither CHIP0 or CHIP1 is chosen, both SIDs will operate together. Accounts for elapsed cycles.

Parameters

chip	SID selector value, see exSID.h.

◆ exSID_clkdread()

uint8_t exSID_clkdread	(	uint_fast32_t	cycles,
		uint_least8_t	addr
	)

BLOCKING Timed read routine, attempts cycle-accurate reads. The following description is based on exSID (standard). This function will be cycle-accurate provided that no two consecutive reads or writes are less than XS_CYCIO apart and leftover delay is <= max_adj SID clock cycles. Read result will only be available after a full XS_CYCIO, giving clkdread() the same run time as clkdwrite(). There's a 2-cycle negative adjustment in the code because that's the actual offset from the write calls ('/' denotes falling clock edge latch), which the following ASCII tries to illustrate:
Write looks like this in firmware:

...|_/_|...

...end of data byte read | cycle during which write is enacted / next cycle | etc...
Read looks like this in firmware:

...|_|_|_/_|_|...

...end of address byte read | 2 cycles for address processing | cycle during which SID is read / then half a cycle later the CYCCHR-long data TX starts, cycle completes | another cycle | etc...
This explains why reads happen a relative 2-cycle later than then should with respect to writes.

Note: The actual time the read will take to complete depends on the USB bus activity and settings. It should complete in XS_USBLAT ms, but not less, meaning that read operations are bound to introduce timing inaccuracy. As such, this function is only really provided as a proof of concept but SHOULD BETTER BE AVOIDED.

Parameters

cycles	how many SID clocks to wait before the actual data read.
addr	target address.

Returns: data read from address.

◆ exSID_clkdwrite()

void exSID_clkdwrite	(	uint_fast32_t	cycles,
		uint_least8_t	addr,
		uint8_t	data
	)

Timed write routine, attempts cycle-accurate writes. This function will be cycle-accurate provided that no two consecutive reads or writes are less than write_cycles apart and the leftover delay is <= max_adj SID clock cycles.

Parameters

cycles	how many SID clocks to wait before the actual data write.
addr	target address.
data	data to write at that address.

◆ exSID_clockselect()

int exSID_clockselect ( int clock )

exSID+ clock selection routine. Selects between PAL, NTSC and 1MHz clocks.

Note: upon clock change the hardware resync itself and resets the SIDs, which takes approximately 50us: this function waits for enough time before resuming execution via a call to usleep(); Output should be muted before execution

Parameters

clock clock selector value, see exSID.h.

Returns: execution status

◆ exSID_delay()

void exSID_delay ( uint_fast32_t cycles )

Cycle accurate delay routine. Applies the most efficient strategy to delay for cycles SID clocks while leaving enough lead time for an I/O operation.

Parameters

cycles how many SID clocks to loop for.

◆ exSID_error_str()

const char* exSID_error_str ( void )

Returns a string describing the last recorded error.

Returns: error message (max 256 bytes long).

◆ exSID_exit()

void exSID_exit ( void )

Device exit routine. Must be called to release the device. Resets the SIDs and clears RX/TX buffers, releases all resources allocated in exSID_init().

◆ exSID_hwmodel()

int exSID_hwmodel ( void )

Device hardware model. Queries the driver for the hardware model currently identified.

Returns: hardware model as enumerated in exSID.h, negative value on error.

◆ exSID_hwversion()

uint16_t exSID_hwversion ( void )

Hardware and firmware version of the device. Queries the device for the hardware revision and current firmware version and returns both in the form of a 16bit integer: MSB is an ASCII character representing the hardware revision (e.g. 0x42 = "B"), and LSB is a number representing the firmware version in decimal integer. Does NOT account for elapsed cycles.

Returns: version information as described above.

◆ exSID_init()

int exSID_init ( void )

Device init routine. Must be called once before any operation is attempted on the device. Opens first available device, and sets various parameters: baudrate, parity, flow control and USB latency, and finally clears the RX and TX buffers.

Returns: 0 on success, !0 otherwise.

◆ exSID_reset()

void exSID_reset ( uint_least8_t volume )

SID reset routine. Performs a hardware reset on the SIDs.

Note: since the reset procedure in firmware will stall the device, reset forcefully waits for enough time before resuming execution via a call to usleep();

Parameters

volume volume to set the SIDs to after reset.

Macros

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

◆ anonymous enum

◆ anonymous enum

Function Documentation

◆ exSID_audio_op()

◆ exSID_chipselect()

◆ exSID_clkdread()

◆ exSID_clkdwrite()

◆ exSID_clockselect()

◆ exSID_delay()

◆ exSID_error_str()

◆ exSID_exit()

◆ exSID_hwmodel()

◆ exSID_hwversion()

◆ exSID_init()

◆ exSID_reset()