Shared library / DLL for accessing the driver, windows specific code. More...

#include <stdlib.h>
#include "archlib_ex.h"
#include "xum1541.h"

Macros
#define	OPENCBM_PLUGIN
	mark: We are building the DLL */

Functions
const char *CBMAPIDECL	opencbm_plugin_get_driver_name (const char *const Port)
	Get the name of the driver for a specific parallel port. More...

int CBMAPIDECL	opencbm_plugin_driver_open (CBM_FILE HandleDevice, const char const Port)
	Opens the driver. More...

void CBMAPIDECL	opencbm_plugin_driver_close (CBM_FILE HandleDevice)
	Closes the driver. More...

void CBMAPIDECL	opencbm_plugin_lock (CBM_FILE HandleDevice)
	Lock the parallel port for the driver. More...

void CBMAPIDECL	opencbm_plugin_unlock (CBM_FILE HandleDevice)
	Unlock the parallel port for the driver. More...

int CBMAPIDECL	opencbm_plugin_raw_write (CBM_FILE HandleDevice, const void *Buffer, size_t Count)
	Write data to the IEC serial bus. More...

int CBMAPIDECL	opencbm_plugin_raw_read (CBM_FILE HandleDevice, void *Buffer, size_t Count)
	Read data from the IEC serial bus. More...

int CBMAPIDECL	opencbm_plugin_listen (CBM_FILE HandleDevice, unsigned char DeviceAddress, unsigned char SecondaryAddress)
	Send a LISTEN on the IEC serial bus. More...

int CBMAPIDECL	opencbm_plugin_talk (CBM_FILE HandleDevice, unsigned char DeviceAddress, unsigned char SecondaryAddress)
	Send a TALK on the IEC serial bus. More...

int CBMAPIDECL	opencbm_plugin_open (CBM_FILE HandleDevice, unsigned char DeviceAddress, unsigned char SecondaryAddress)
	Open a file on the IEC serial bus. More...

int CBMAPIDECL	opencbm_plugin_close (CBM_FILE HandleDevice, unsigned char DeviceAddress, unsigned char SecondaryAddress)
	Close a file on the IEC serial bus. More...

int CBMAPIDECL	opencbm_plugin_unlisten (CBM_FILE HandleDevice)
	Send an UNLISTEN on the IEC serial bus. More...

int CBMAPIDECL	opencbm_plugin_untalk (CBM_FILE HandleDevice)
	Send an UNTALK on the IEC serial bus. More...

int CBMAPIDECL	opencbm_plugin_get_eoi (CBM_FILE HandleDevice)
	Get EOI flag after bus read. More...

int CBMAPIDECL	opencbm_plugin_clear_eoi (CBM_FILE HandleDevice)
	Reset the EOI flag. More...

int CBMAPIDECL	opencbm_plugin_reset (CBM_FILE HandleDevice)
	RESET all devices. More...

unsigned char CBMAPIDECL	opencbm_plugin_pp_read (CBM_FILE HandleDevice)
	Read a byte from a XP1541/XP1571 cable. More...

void CBMAPIDECL	opencbm_plugin_pp_write (CBM_FILE HandleDevice, unsigned char Byte)
	Write a byte to a XP1541/XP1571 cable. More...

int CBMAPIDECL	opencbm_plugin_iec_poll (CBM_FILE HandleDevice)
	Read status of all bus lines. More...

void CBMAPIDECL	opencbm_plugin_iec_set (CBM_FILE HandleDevice, int Line)
	Activate a line on the IEC serial bus. More...

void CBMAPIDECL	opencbm_plugin_iec_release (CBM_FILE HandleDevice, int Line)
	Deactivate a line on the IEC serial bus. More...

void CBMAPIDECL	opencbm_plugin_iec_setrelease (CBM_FILE HandleDevice, int Set, int Release)
	Activate and deactive a line on the IEC serial bus. More...

int CBMAPIDECL	opencbm_plugin_iec_wait (CBM_FILE HandleDevice, int Line, int State)
	Wait for a line to have a specific state. More...

int CBMAPIDECL	xum1541_plugin_control_msg (CBM_FILE HandleDevice, unsigned int cmd)
	Sends a command to the xum1541 device. More...

Detailed Description

Shared library / DLL for accessing the driver, windows specific code.

Author: Michael Klein, Spiro Trikaliotis

Definition in file plugin/xum1541/archlib.c.

Function Documentation

int CBMAPIDECL opencbm_plugin_clear_eoi ( CBM_FILE HandleDevice )

Reset the EOI flag.

This function resets the EOI ("End of Information") flag which might be still set after reading the IEC serial bus.

Parameters

HandleDevice A CBM_FILE which contains the file handle of the driver.

Returns: 0 on success, != 0 means an error has occured.

If cbm_driver_open() did not succeed, it is illegal to call this function.

Definition at line 483 of file plugin/xum1541/archlib.c.

References xum1541_ioctl().

int CBMAPIDECL opencbm_plugin_close	(	CBM_FILE	HandleDevice,
		unsigned char	DeviceAddress,
		unsigned char	SecondaryAddress
	)

Close a file on the IEC serial bus.

This function closes a file on the IEC serial bus.

Parameters

HandleDevice	A CBM_FILE which contains the file handle of the driver.
DeviceAddress	The address of the device on the IEC serial bus. This is known as primary address, too.
SecondaryAddress	The secondary address for the device on the IEC serial bus.

Returns: 0 on success, else failure

If cbm_driver_open() did not succeed, it is illegal to call this function.

Definition at line 370 of file plugin/xum1541/archlib.c.

References xum1541_write().

void CBMAPIDECL opencbm_plugin_driver_close ( CBM_FILE HandleDevice )

Closes the driver.

Closes the driver, which has be opened with cbm_driver_open() before.

Parameters

HandleDevice A CBM_FILE which contains the file handle of the driver.

cbm_driver_close() should be called to balance a previous call to cbm_driver_open().

If cbm_driver_open() did not succeed, it is illegal to call cbm_driver_close().

Definition at line 130 of file plugin/xum1541/archlib.c.

References xum1541_close().

int CBMAPIDECL opencbm_plugin_driver_open	(	CBM_FILE *	HandleDevice,
		const char *const	Port
	)

Opens the driver.

This function Opens the driver.

Parameters

HandleDevice	Pointer to a CBM_FILE which will contain the file handle of the driver.
Port	The port specification for the driver to open. If not set (== NULL), the "default" driver is used. The exact meaning depends upon the plugin.

Returns: ==0: This function completed successfully !=0: otherwise

PortNumber is not allowed to exceed 10.

cbm_driver_open() should be balanced with cbm_driver_close().

Definition at line 104 of file plugin/xum1541/archlib.c.

References xum1541_init().

const char* CBMAPIDECL opencbm_plugin_get_driver_name ( const char *const Port )

Get the name of the driver for a specific parallel port.

Parameters

Port	The port specification for the driver to open. If not set (== NULL), the "default" driver is used. The exact meaning depends upon the plugin.

Returns: Returns a pointer to a null-terminated string containing the driver name, or NULL if an error occurred.

Bug:: PortNumber is not allowed to exceed 255.

Definition at line 72 of file plugin/xum1541/archlib.c.

References xum1541_device_path().

int CBMAPIDECL opencbm_plugin_get_eoi ( CBM_FILE HandleDevice )

Get EOI flag after bus read.

This function gets the EOI ("End of Information") flag after reading the IEC serial bus.

Parameters

HandleDevice A CBM_FILE which contains the file handle of the driver.

Returns: != 0 if EOI was signalled, else 0.

If a previous read returned less than the specified number of bytes, there are two possible reasons: Either an error occurred on the IEC serial bus, or an EOI was signalled. To find out the cause, check with this function.

If cbm_driver_open() did not succeed, it is illegal to call this function.

Definition at line 462 of file plugin/xum1541/archlib.c.

References xum1541_ioctl().

int CBMAPIDECL opencbm_plugin_iec_poll ( CBM_FILE HandleDevice )

Read status of all bus lines.

This function reads the state of all lines on the IEC serial bus.

Parameters

HandleDevice A CBM_FILE which contains the file handle of the driver.

Returns: The state of the lines. The result is an OR between the bit flags IEC_DATA, IEC_CLOCK, IEC_ATN, and IEC_RESET.

This function just reads the port. No handshaking is performed at all.

If cbm_driver_open() did not succeed, it is illegal to call this function.

Bug:: This function can't signal an error, thus, be careful!

Definition at line 597 of file plugin/xum1541/archlib.c.

References xum1541_ioctl().

void CBMAPIDECL opencbm_plugin_iec_release	(	CBM_FILE	HandleDevice,
		int	Line
	)

Deactivate a line on the IEC serial bus.

This function deactivates (sets to 5V) a line on the IEC serial bus.

Parameters

HandleDevice	A CBM_FILE which contains the file handle of the driver.
Line	The line to be deactivated. This must be exactly one of IEC_DATA, IEC_CLOCK, IEC_ATN, or IEC_RESET.

If cbm_driver_open() did not succeed, it is illegal to call this function.

Bug:: This function can't signal an error, thus, be careful!

Definition at line 646 of file plugin/xum1541/archlib.c.

References xum1541_ioctl().

void CBMAPIDECL opencbm_plugin_iec_set	(	CBM_FILE	HandleDevice,
		int	Line
	)

Activate a line on the IEC serial bus.

This function activates (sets to 0V) a line on the IEC serial bus.

Parameters

HandleDevice	A CBM_FILE which contains the file handle of the driver.
Line	The line to be activated. This must be exactly one of IEC_DATA, IEC_CLOCK, IEC_ATN, or IEC_RESET.

If cbm_driver_open() did not succeed, it is illegal to call this function.

Bug:: This function can't signal an error, thus, be careful!

Definition at line 622 of file plugin/xum1541/archlib.c.

References xum1541_ioctl().

void CBMAPIDECL opencbm_plugin_iec_setrelease	(	CBM_FILE	HandleDevice,
		int	Set,
		int	Release
	)

Activate and deactive a line on the IEC serial bus.

This function activates (sets to 0V, L) and deactivates (set to 5V, H) lines on the IEC serial bus.

Parameters

HandleDevice	A CBM_FILE which contains the file handle of the driver.
Set	The mask of which lines should be set. This has to be a bitwise OR between the constants IEC_DATA, IEC_CLOCK, IEC_ATN, and IEC_RESET
Release	The mask of which lines should be released. This has to be a bitwise OR between the constants IEC_DATA, IEC_CLOCK, IEC_ATN, and IEC_RESET

If cbm_driver_open() did not succeed, it is illegal to call this function.

Bug:: This function can't signal an error, thus, be careful!

Remarks: If a bit is specified in the Set as well as in the Release mask, the effect is undefined.

Definition at line 679 of file plugin/xum1541/archlib.c.

References xum1541_ioctl().

int CBMAPIDECL opencbm_plugin_iec_wait	(	CBM_FILE	HandleDevice,
		int	Line,
		int	State
	)

Wait for a line to have a specific state.

This function waits for a line to enter a specific state on the IEC serial bus.

Parameters

HandleDevice	A CBM_FILE which contains the file handle of the driver.
Line	The line to be deactivated. This must be exactly one of IEC_DATA, IEC_CLOCK, IEC_ATN, and IEC_RESET.
State	If zero, then wait for this line to be deactivated. If not zero, then wait for this line to be activated.

Returns: The state of the IEC bus on return (like cbm_iec_poll).

If cbm_driver_open() did not succeed, it is illegal to call this function.

Bug:: This function can't signal an error, thus, be careful!

Definition at line 711 of file plugin/xum1541/archlib.c.

References xum1541_ioctl().

int CBMAPIDECL opencbm_plugin_listen	(	CBM_FILE	HandleDevice,
		unsigned char	DeviceAddress,
		unsigned char	SecondaryAddress
	)

Send a LISTEN on the IEC serial bus.

This function sends a LISTEN on the IEC serial bus. This prepares a LISTENer, so that it will wait for our bytes we will write in the future.

Parameters

HandleDevice	A CBM_FILE which contains the file handle of the driver.
DeviceAddress	The address of the device on the IEC serial bus. This is known as primary address, too.
SecondaryAddress	The secondary address for the device on the IEC serial bus.

Returns: 0 means success, else failure

If cbm_driver_open() did not succeed, it is illegal to call this function.

Definition at line 272 of file plugin/xum1541/archlib.c.

References xum1541_write().

void CBMAPIDECL opencbm_plugin_lock ( CBM_FILE HandleDevice )

Lock the parallel port for the driver.

This function locks the driver onto the parallel port. This way, no other program or driver can allocate the parallel port and interfere with the communication.

Parameters

HandleDevice A CBM_FILE which contains the file handle of the driver.

If cbm_driver_open() did not succeed, it is illegal to call cbm_driver_close().

Remarks: A call to cbm_lock() is undone with a call to cbm_unlock().

Note that it is not necessary to call this function (or cbm_unlock()) when all communication is done with the handle to opencbm open (that is, between cbm_driver_open() and cbm_driver_close(). You only need this function to pin the driver to the port even when cbm_driver_close() is to be executed (for example, because the program terminates).

Definition at line 161 of file plugin/xum1541/archlib.c.

int CBMAPIDECL opencbm_plugin_open	(	CBM_FILE	HandleDevice,
		unsigned char	DeviceAddress,
		unsigned char	SecondaryAddress
	)

Open a file on the IEC serial bus.

This function opens a file on the IEC serial bus.

Parameters

HandleDevice	A CBM_FILE which contains the file handle of the driver.
DeviceAddress	The address of the device on the IEC serial bus. This is known as primary address, too.
SecondaryAddress	The secondary address for the device on the IEC serial bus.

Returns: 0 means success, else failure

If cbm_driver_open() did not succeed, it is illegal to call this function.

Definition at line 338 of file plugin/xum1541/archlib.c.

References xum1541_write().

unsigned char CBMAPIDECL opencbm_plugin_pp_read ( CBM_FILE HandleDevice )

Read a byte from a XP1541/XP1571 cable.

This function reads a single byte from the parallel portion of an XP1541/1571 cable.

Parameters

HandleDevice A CBM_FILE which contains the file handle of the driver.

Returns: the byte which was received on the parallel port

This function reads the current state of the port. No handshaking is performed at all.

If cbm_driver_open() did not succeed, it is illegal to call this function.

Bug:: This function can't signal an error, thus, be careful!

Definition at line 541 of file plugin/xum1541/archlib.c.

References xum1541_ioctl().

void CBMAPIDECL opencbm_plugin_pp_write	(	CBM_FILE	HandleDevice,
		unsigned char	Byte
	)

Write a byte to a XP1541/XP1571 cable.

This function writes a single byte to the parallel portion of a XP1541/1571 cable.

Parameters

HandleDevice	A CBM_FILE which contains the file handle of the driver.
Byte	the byte to be output on the parallel port

This function just writes on the port. No handshaking is performed at all.

If cbm_driver_open() did not succeed, it is illegal to call this function.

Bug:: This function can't signal an error, thus, be careful!

Definition at line 570 of file plugin/xum1541/archlib.c.

References xum1541_ioctl().

int CBMAPIDECL opencbm_plugin_raw_read	(	CBM_FILE	HandleDevice,
		void *	Buffer,
		size_t	Count
	)

Read data from the IEC serial bus.

This function retrieves data after a cbm_talk().

Parameters

HandleDevice	A CBM_FILE which contains the file handle of the driver.
Buffer	Pointer to a buffer which will hold the bytes read.
Count	Number of bytes to be read at most.

Returns: >= 0: The actual number of bytes read. <0 indicates an error.

At most Count bytes are read.

If cbm_driver_open() did not succeed, it is illegal to call this function.

Definition at line 241 of file plugin/xum1541/archlib.c.

References xum1541_read().

int CBMAPIDECL opencbm_plugin_raw_write	(	CBM_FILE	HandleDevice,
		const void *	Buffer,
		size_t	Count
	)

Write data to the IEC serial bus.

This function sends data after a cbm_listen().

Parameters

HandleDevice	A CBM_FILE which contains the file handle of the driver.
Buffer	Pointer to a buffer which hold the bytes to write to the bus.
Count	Number of bytes to be written.

Returns: >= 0: The actual number of bytes written. <0 indicates an error.

This function tries to write Count bytes. Anyway, if an error occurs, this function can stop prematurely.

If cbm_driver_open() did not succeed, it is illegal to call this function.

Definition at line 212 of file plugin/xum1541/archlib.c.

References xum1541_write().

int CBMAPIDECL opencbm_plugin_reset ( CBM_FILE HandleDevice )

RESET all devices.

This function performs a hardware RESET of all devices on the IEC serial bus.

Parameters

HandleDevice A CBM_FILE which contains the file handle of the driver.

Returns: 0 on success, else failure

Don't overuse this function! Normally, an initial RESET should be enough.

Control is returned after a delay which ensures that all devices are ready again.

If cbm_driver_open() did not succeed, it is illegal to call this function.

Definition at line 510 of file plugin/xum1541/archlib.c.

References xum1541_control_msg().

int CBMAPIDECL opencbm_plugin_talk	(	CBM_FILE	HandleDevice,
		unsigned char	DeviceAddress,
		unsigned char	SecondaryAddress
	)

Send a TALK on the IEC serial bus.

This function sends a TALK on the IEC serial bus. This prepares a TALKer, so that it will prepare to send us some bytes in the future.

Parameters

HandleDevice	A CBM_FILE which contains the file handle of the driver.
DeviceAddress	The address of the device on the IEC serial bus. This is known as primary address, too.
SecondaryAddress	The secondary address for the device on the IEC serial bus.

Returns: 0 means success, else failure

If cbm_driver_open() did not succeed, it is illegal to call this function.

Definition at line 306 of file plugin/xum1541/archlib.c.

References xum1541_write().

int CBMAPIDECL opencbm_plugin_unlisten ( CBM_FILE HandleDevice )

Send an UNLISTEN on the IEC serial bus.

This function sends an UNLISTEN on the IEC serial bus. Other than LISTEN and TALK, an UNLISTEN is not directed to just one device, but to all devices on that IEC serial bus.

Parameters

HandleDevice A CBM_FILE which contains the file handle of the driver.

Returns: 0 on success, else failure

At least on a 1541 floppy drive, an UNLISTEN also undoes a previous TALK.

If cbm_driver_open() did not succeed, it is illegal to call this function.

Definition at line 401 of file plugin/xum1541/archlib.c.

References xum1541_write().

void CBMAPIDECL opencbm_plugin_unlock ( CBM_FILE HandleDevice )

Unlock the parallel port for the driver.

This function unlocks the driver from the parallel port. This way, other programs and drivers can allocate the parallel port and do their own communication with whatever device they use.

Parameters

HandleDevice A CBM_FILE which contains the file handle of the driver.

If cbm_driver_open() did not succeed, it is illegal to call cbm_driver_close().

Remarks: Look at cbm_lock() for an explanation of this function.

Definition at line 183 of file plugin/xum1541/archlib.c.

int CBMAPIDECL opencbm_plugin_untalk ( CBM_FILE HandleDevice )

Send an UNTALK on the IEC serial bus.

This function sends an UNTALK on the IEC serial bus. Other than LISTEN and TALK, an UNTALK is not directed to just one device, but to all devices on that IEC serial bus.

Parameters

HandleDevice A CBM_FILE which contains the file handle of the driver.

Returns: 0 on success, else failure

At least on a 1541 floppy drive, an UNTALK also undoes a previous LISTEN.

If cbm_driver_open() did not succeed, it is illegal to call this function.

Definition at line 431 of file plugin/xum1541/archlib.c.

References xum1541_write().

int CBMAPIDECL xum1541_plugin_control_msg	(	CBM_FILE	HandleDevice,
		unsigned int	cmd
	)

Sends a command to the xum1541 device.

This function sends a control message respectively a command to the xum1541 device.

Parameters

HandleDevice	A CBM_FILE which contains the file handle of the driver.
cmd	The command to run at the xum1541 device.

Returns: Returns the value the USB device sent back.

Definition at line 731 of file plugin/xum1541/archlib.c.

References xum1541_control_msg().

Referenced by main().

Macros

Functions

Detailed Description

Function Documentation