libexsid
2.1
|
exSID/exSID+ USB I/O library More...
#include "exSID.h"
#include "exSID_defs.h"
#include "exSID_ftdiwrap.h"
#include <stdio.h>
#include <unistd.h>
#include <inttypes.h>
#include <stdlib.h>
#include <errno.h>
#include <time.h>
Go to the source code of this file.
Data Structures | |
struct | xSconsts_s |
This private structure holds hardware-dependent constants. More... | |
struct | _exsid |
exSID private handle More... | |
Macros | |
#define | ARRAY_SIZE(x) (sizeof(x) / sizeof(x[0])) |
#define | XS_ERRORBUF 256 |
#define | xserror(xs, format, ...) snprintf(xs->xSerrstr, XS_ERRORBUF, "(%s) ERROR " format, __func__, ## __VA_ARGS__) |
Typedefs | |
typedef int_fast32_t | clkdrift_t |
cycles is uint_fast32_t. More... | |
Functions | |
const char * | exSID_error_str (void *const exsid) |
Returns a string describing the last recorded error. More... | |
void * | exSID_new (void) |
Allocate an exSID handle. More... | |
void | exSID_free (void *exsid) |
Deallocate an exSID handle. More... | |
int | exSID_init (void *const exsid) |
Device init routine. More... | |
int | exSID_exit (void *const exsid) |
Device exit routine. More... | |
int | exSID_reset (void *const exsid) |
SID reset routine. More... | |
int | exSID_clockselect (void *const exsid, int clock) |
exSID+ clock selection routine. More... | |
int | exSID_audio_op (void *const exsid, int operation) |
exSID+ audio operations routine. More... | |
int | exSID_chipselect (void *const exsid, int chip) |
SID chipselect routine. More... | |
int | exSID_hwmodel (void *const exsid) |
Device hardware model. More... | |
uint16_t | exSID_hwversion (void *const exsid) |
Hardware and firmware version of the device. More... | |
int | exSID_delay (void *const exsid, uint_fast32_t cycles) |
Cycle accurate delay routine. More... | |
int | exSID_clkdwrite (void *const exsid, uint_fast32_t cycles, uint_least8_t addr, uint8_t data) |
Timed write routine, attempts cycle-accurate writes. More... | |
int | exSID_clkdread (void *const exsid, uint_fast32_t cycles, uint_least8_t addr, uint8_t *data) |
BLOCKING Timed read routine, attempts cycle-accurate reads. More... | |
exSID/exSID+ USB I/O library
This driver will control the first exSID device available. All public API functions are only valid after a successful call to exSID_init(). To release the device and resources, exSID_exit() and exSID_free() must be called.
The return value for public routines returning an integer is 0 for successful execution and !0 for error, unless otherwise noted.
Definition in file exSID.c.
#define ARRAY_SIZE | ( | x | ) | (sizeof(x) / sizeof(x[0])) |
Definition at line 46 of file exSID.c.
Referenced by exSID_init().
#define xserror | ( | xs, | |
format, | |||
... | |||
) | snprintf(xs->xSerrstr, XS_ERRORBUF, "(%s) ERROR " format, __func__, ## __VA_ARGS__) |
Definition at line 48 of file exSID.c.
Referenced by exSID_exit(), and exSID_init().
typedef int_fast32_t clkdrift_t |
int exSID_audio_op | ( | void *const | exsid, |
int | operation | ||
) |
exSID+ audio operations routine.
Selects the audio mixing / muting option. Only implemented in exSID+ devices.
exsid | exsid handle |
operation | audio operation value, see exSID.h. |
Definition at line 617 of file exSID.c.
References _exsid::cst, xSconsts_s::model, XS_AU_6581_6581, XS_AU_6581_8580, XS_AU_8580_6581, XS_AU_8580_8580, XS_AU_MUTE, XS_AU_UNMUTE, XS_MODEL_PLUS, xsdbg, XSP_AD_IOCTA0, XSP_AD_IOCTA1, XSP_AD_IOCTA2, XSP_AD_IOCTA3, XSP_AD_IOCTAM, and XSP_AD_IOCTAU.
int exSID_chipselect | ( | void *const | exsid, |
int | chip | ||
) |
SID chipselect routine.
Selects which SID will play the tunes.
exsid | exsid handle |
chip | SID selector value, see exSID.h. |
Definition at line 663 of file exSID.c.
References _exsid::clkdrift, xSconsts_s::csioctl_cycles, _exsid::cst, XS_AD_IOCTS0, XS_AD_IOCTS1, XS_AD_IOCTSB, XS_CS_BOTH, XS_CS_CHIP0, XS_CS_CHIP1, and xsdbg.
int exSID_clkdread | ( | void *const | exsid, |
uint_fast32_t | cycles, | ||
uint_least8_t | addr, | ||
uint8_t * | data | ||
) |
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.
exsid | exsid handle |
cycles | how many SID clocks to wait before the actual data read. |
addr | target address. |
data | pointer to store data read from address. |
Definition at line 909 of file exSID.c.
References _exsid::clkdrift, _exsid::cst, exSID_delay(), likely, xSconsts_s::max_adj, xSconsts_s::mindel_cycles, xSconsts_s::read_offset_cycles, xSconsts_s::read_post_cycles, xSconsts_s::read_pre_cycles, unlikely, and xsdbg.
int exSID_clkdwrite | ( | void *const | exsid, |
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 writes are less than write_cycles apart and the leftover delay is <= max_adj SID clock cycles.
exsid | exsid handle |
cycles | how many SID clocks to wait before the actual data write. |
addr | target address. |
data | data to write at that address. |
Definition at line 816 of file exSID.c.
References _exsid::clkdrift, _exsid::cst, exSID_delay(), likely, xSconsts_s::max_adj, xSconsts_s::mindel_cycles, unlikely, xSconsts_s::write_cycles, and xsdbg.
int exSID_clockselect | ( | void *const | exsid, |
int | clock | ||
) |
exSID+ clock selection routine.
Selects between PAL, NTSC and 1MHz clocks. Only implemented in exSID+ devices.
exsid | exsid handle |
clock | clock selector value, see exSID.h. |
Definition at line 576 of file exSID.c.
References _exsid::clkdrift, _exsid::cst, xSconsts_s::model, XS_CL_1MHZ, XS_CL_NTSC, XS_CL_PAL, XS_MODEL_PLUS, xsdbg, XSP_AD_IOCTC1, XSP_AD_IOCTCN, and XSP_AD_IOCTCP.
int exSID_delay | ( | void *const | exsid, |
uint_fast32_t | cycles | ||
) |
Cycle accurate delay routine.
Delay for cycles SID clocks while leaving enough lead time for an I/O operation.
exsid | exsid handle |
cycles | how many SID clocks to loop for. |
Definition at line 769 of file exSID.c.
References _exsid::clkdrift, _exsid::cst, unlikely, and xSconsts_s::write_cycles.
Referenced by exSID_clkdread(), and exSID_clkdwrite().
const char* exSID_error_str | ( | void *const | exsid | ) |
Returns a string describing the last recorded error.
exsid | exsid handle |
Definition at line 177 of file exSID.c.
References _exsid::xSerrstr.
int exSID_exit | ( | void *const | exsid | ) |
Device exit routine.
Must be called to release the device. Resets the SIDs, frees buffers and closes FTDI device.
exsid | exsid handle |
Definition at line 489 of file exSID.c.
References _exsid::backbuf, _exsid::clkdrift, exSID_reset(), _exsid::ftdi, XS_AD_IOCTD1, xsdbg, xserror, xSfw_dlclose(), xSfw_free, xSfw_get_error_string, and xSfw_usb_close.
void exSID_free | ( | void * | exsid | ) |
Deallocate an exSID handle.
Frees up all memory used by the exSID handle.
exsid | exsid handle |
Definition at line 354 of file exSID.c.
References _exsid::backbuf, _exsid::ftdi, and xSfw_free.
int exSID_hwmodel | ( | void *const | exsid | ) |
Device hardware model.
Queries the driver for the hardware model currently identified.
exsid | exsid handle |
Definition at line 697 of file exSID.c.
References _exsid::cst, xSconsts_s::model, XS_MD_PLUS, XS_MD_STD, XS_MODEL_PLUS, XS_MODEL_STD, and xsdbg.
uint16_t exSID_hwversion | ( | void *const | exsid | ) |
Hardware and firmware version of the device.
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 reach the hardware (information is fetched once in exSID_init()).
exsid | exsid handle |
Definition at line 731 of file exSID.c.
References _exsid::hwvers.
int exSID_init | ( | void *const | exsid | ) |
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.
exsid | allocated exsid handle generated with exSID_new() |
Definition at line 384 of file exSID.c.
References ARRAY_SIZE, _exsid::backbuf, xSconsts_s::buff_size, _exsid::cst, desc, EXSID_VERSION, _exsid::ftdi, _exsid::hwvers, XS_AD_IOCTFV, XS_AD_IOCTHV, XS_BDRATE, XSC_USBLAT, xsdbg, xserror, xSfw_dlopen(), xSfw_free, xSfw_get_error_string, xSfw_new, xSfw_usb_open_desc, and xSfw_usb_setup().
void* exSID_new | ( | void | ) |
int exSID_reset | ( | void *const | exsid | ) |
SID reset routine.
Performs a hardware reset on the SIDs. This also resets the internal drift adjustment counter.
exsid | exsid handle |
Definition at line 549 of file exSID.c.
References _exsid::clkdrift, XS_AD_IOCTRS, and xsdbg.
Referenced by exSID_exit().
const char* desc |
const struct xSconsts_s xsc |