WINBUILD/archlib.c File Reference

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

#include <windows.h>
#include <windowsx.h>
#include <mmsystem.h>
#include "debug.h"
#include <winioctl.h>
#include "cbmioctl.h"
#include <stdlib.h>
#include "i_opencbm.h"
#include "archlib.h"

Go to the source code of this file.

Defines
#define	DBG_USERMODE
#define	DBG_DLL
#define	DBG_PROGNAME   "OPENCBM.DLL"
#define	DBG_IS_DEBUG_C
#define	DLL
	mark: We are building the DLL */
Functions
BOOL	opencbm_init (IN HANDLE Module, IN DWORD Reason, IN LPVOID Reserved)
	DLL initialization und unloading.
BOOL CBMAPIDECL	cbm_i_driver_install (OUT PULONG Buffer, IN ULONG BufferLen)
	Complete driver installation, "external version".
void	cbmarch_lock (CBM_FILE HandleDevice)
	Lock the parallel port for the driver.
void	cbmarch_unlock (CBM_FILE HandleDevice)
	Unlock the parallel port for the driver.
int	cbmarch_raw_write (CBM_FILE HandleDevice, const void *Buffer, size_t Count)
	Write data to the IEC serial bus.
int	cbmarch_raw_read (CBM_FILE HandleDevice, void *Buffer, size_t Count)
	Read data from the IEC serial bus.
int	cbmarch_listen (CBM_FILE HandleDevice, __u_char DeviceAddress, __u_char SecondaryAddress)
	Send a LISTEN on the IEC serial bus.
int	cbmarch_talk (CBM_FILE HandleDevice, __u_char DeviceAddress, __u_char SecondaryAddress)
	Send a TALK on the IEC serial bus.
int	cbmarch_open (CBM_FILE HandleDevice, __u_char DeviceAddress, __u_char SecondaryAddress)
	Open a file on the IEC serial bus.
int	cbmarch_close (CBM_FILE HandleDevice, __u_char DeviceAddress, __u_char SecondaryAddress)
	Close a file on the IEC serial bus.
int	cbmarch_unlisten (CBM_FILE HandleDevice)
	Send an UNLISTEN on the IEC serial bus.
int	cbmarch_untalk (CBM_FILE HandleDevice)
	Send an UNTALK on the IEC serial bus.
int	cbmarch_get_eoi (CBM_FILE HandleDevice)
	Get EOI flag after bus read.
int	cbmarch_clear_eoi (CBM_FILE HandleDevice)
	Reset the EOI flag.
int	cbmarch_reset (CBM_FILE HandleDevice)
	RESET all devices.
__u_char	cbmarch_pp_read (CBM_FILE HandleDevice)
	Read a byte from a XP1541/XP1571 cable.
void	cbmarch_pp_write (CBM_FILE HandleDevice, __u_char Byte)
	Write a byte to a XP1541/XP1571 cable.
int	cbmarch_iec_poll (CBM_FILE HandleDevice)
	Read status of all bus lines.
void	cbmarch_iec_set (CBM_FILE HandleDevice, int Line)
	Activate a line on the IEC serial bus.
void	cbmarch_iec_release (CBM_FILE HandleDevice, int Line)
	Deactivate a line on the IEC serial bus.
void	cbmarch_iec_setrelease (CBM_FILE HandleDevice, int Set, int Release)
	Activate and deactive a line on the IEC serial bus.
int	cbmarch_iec_wait (CBM_FILE HandleDevice, int Line, int State)
	Wait for a line to have a specific state.

---

Detailed Description

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

**************************************************************

Author:

Michael Klein, Spiro Trikaliotis

Version:

Id

archlib.c,v 1.15 2006/04/11 16:57:50 trikalio Exp

Definition in file WINBUILD/archlib.c.

---

Define Documentation

#define DBG_DLL

Mark: We are building the DLL Definition at line 30 of file WINBUILD/archlib.c.

#define DBG_IS_DEBUG_C

This file is "like" debug.c, that is, define some variables Definition at line 36 of file WINBUILD/archlib.c.

#define DBG_PROGNAME   "OPENCBM.DLL"

The name of the executable Definition at line 33 of file WINBUILD/archlib.c.

#define DBG_USERMODE

Mark: We are in user-space (for debug.h) Definition at line 27 of file WINBUILD/archlib.c.

---

Function Documentation

BOOL CBMAPIDECL cbm_i_driver_install (  OUT PULONG  Buffer, IN ULONG  BufferLen )

Complete driver installation, "external version". This function performs anything that is needed to successfully complete the driver installation. Parameters: Buffer  Pointer to a buffer which will return the install information BufferLen  The length of the buffer Buffer points to (in bytes). Returns: FALSE on success, TRUE on error This function is for use of the installation routines only! This version of this function is for exporting out of the DLL. Definition at line 251 of file WINBUILD/archlib.c.

int cbmarch_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 682 of file WINBUILD/archlib.c. References cbm_ioctl(), CBMCTRL, FUNC_ENTER, and FUNC_LEAVE_INT. Referenced by cbm_clear_eoi().

int cbmarch_close (  CBM_FILE  HandleDevice, __u_char  DeviceAddress, __u_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 552 of file WINBUILD/archlib.c. References cbm_ioctl(), CBMCTRL, FUNC_ENTER, FUNC_LEAVE_INT, CBMT_IECADDRESS::PrimaryAddress, and CBMT_IECADDRESS::SecondaryAddress. Referenced by cbm_close().

int cbmarch_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 655 of file WINBUILD/archlib.c. References cbm_ioctl(), CBMCTRL, FUNC_ENTER, and FUNC_LEAVE_INT. Referenced by cbm_get_eoi().

int cbmarch_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 822 of file WINBUILD/archlib.c. References cbm_ioctl(), CBMCTRL, FUNC_ENTER, and FUNC_LEAVE_INT. Referenced by cbm_iec_get(), and cbm_iec_poll().

void cbmarch_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 885 of file WINBUILD/archlib.c. References cbm_ioctl(), CBMCTRL, FUNC_ENTER, FUNC_LEAVE, and CBMT_LINE::Line. Referenced by cbm_iec_release().

void cbmarch_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 853 of file WINBUILD/archlib.c. References cbm_ioctl(), CBMCTRL, FUNC_ENTER, FUNC_LEAVE, and CBMT_LINE::Line. Referenced by cbm_iec_set().

void cbmarch_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 926 of file WINBUILD/archlib.c. References cbm_ioctl(), CBMCTRL, FUNC_ENTER, FUNC_LEAVE, CBMT_LINESTATE::Line, and CBMT_LINESTATE::State. Referenced by cbm_iec_setrelease().

int cbmarch_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 967 of file WINBUILD/archlib.c. References cbm_iec_get(), FUNC_ENTER, and FUNC_LEAVE_INT. Referenced by cbm_iec_wait().

int cbmarch_listen (  CBM_FILE  HandleDevice, __u_char  DeviceAddress, __u_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 430 of file WINBUILD/archlib.c. References cbm_ioctl(), CBMCTRL, FUNC_ENTER, FUNC_LEAVE_INT, CBMT_IECADDRESS::PrimaryAddress, and CBMT_IECADDRESS::SecondaryAddress. Referenced by cbm_exec_command(), cbm_listen(), and cbm_upload().

void cbmarch_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 284 of file WINBUILD/archlib.c. References cbm_ioctl(), CBMCTRL, FUNC_ENTER, and FUNC_LEAVE. Referenced by cbm_lock().

int cbmarch_open (  CBM_FILE  HandleDevice, __u_char  DeviceAddress, __u_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 508 of file WINBUILD/archlib.c. References cbm_ioctl(), CBMCTRL, FUNC_ENTER, FUNC_LEAVE_INT, CBMT_IECADDRESS::PrimaryAddress, and CBMT_IECADDRESS::SecondaryAddress. Referenced by cbm_open().

__u_char cbmarch_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 752 of file WINBUILD/archlib.c. References cbm_ioctl(), CBMCTRL, FUNC_ENTER, and FUNC_LEAVE_UCHAR. Referenced by cbm_pp_read().

void cbmarch_pp_write (  CBM_FILE  HandleDevice, __u_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 787 of file WINBUILD/archlib.c. References CBMT_SINGLEBYTE::Byte, cbm_ioctl(), CBMCTRL, FUNC_ENTER, and FUNC_LEAVE. Referenced by cbm_pp_write().

int cbmarch_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 386 of file WINBUILD/archlib.c. References FUNC_ENTER, and FUNC_LEAVE_INT. Referenced by cbm_identify(), and cbm_raw_read().

int cbmarch_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 345 of file WINBUILD/archlib.c. References FUNC_ENTER, and FUNC_LEAVE_INT. Referenced by cbm_exec_command(), cbm_raw_write(), and cbm_upload().

int cbmarch_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 715 of file WINBUILD/archlib.c. References cbm_ioctl(), CBMCTRL, FUNC_ENTER, and FUNC_LEAVE_INT. Referenced by cbm_reset().

int cbmarch_talk (  CBM_FILE  HandleDevice, __u_char  DeviceAddress, __u_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 470 of file WINBUILD/archlib.c. References cbm_ioctl(), CBMCTRL, FUNC_ENTER, FUNC_LEAVE_INT, CBMT_IECADDRESS::PrimaryAddress, and CBMT_IECADDRESS::SecondaryAddress. Referenced by cbm_device_status(), cbm_identify(), and cbm_talk().

int cbmarch_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 590 of file WINBUILD/archlib.c. References cbm_ioctl(), CBMCTRL, FUNC_ENTER, and FUNC_LEAVE_INT. Referenced by cbm_exec_command(), cbm_unlisten(), and cbm_upload().

void cbmarch_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 311 of file WINBUILD/archlib.c. References cbm_ioctl(), CBMCTRL, FUNC_ENTER, and FUNC_LEAVE. Referenced by cbm_unlock().

int cbmarch_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 622 of file WINBUILD/archlib.c. References cbm_ioctl(), CBMCTRL, FUNC_ENTER, and FUNC_LEAVE_INT. Referenced by cbm_device_status(), cbm_identify(), and cbm_untalk().

BOOL opencbm_init (  IN HANDLE  Module, IN DWORD  Reason, IN LPVOID  Reserved )

DLL initialization und unloading. This function is called whenever the DLL is loaded or unloaded. It ensures that the driver is loaded to be able to call its functions. Parameters: Module  Handle of the module; this is not used. Reason  DLL_PROCESS_ATTACH if the DLL is loaded, DLL_PROCESS_DETACH if it is unloaded. Reserved  Not used. Returns: Returns TRUE on success, else FALSE. If this function returns FALSE, windows reports that loading the DLL was not successful. If the DLL is linked statically, the executable refuses to load with STATUS_DLL_INIT_FAILED (0xC0000142) Definition at line 129 of file WINBUILD/archlib.c. References cbm_i_driver_start(), cbm_i_driver_stop(), DBG_ASSERT, DBG_ERROR, DBG_PREFIX, FUNC_ENTER, FUNC_LEAVE_BOOL, IEC_ATN, IEC_CLOCK, IEC_DATA, IEC_LINE_ATN, IEC_LINE_CLOCK, IEC_LINE_DATA, IEC_LINE_RESET, IEC_RESET, and IsDriverStartedAutomatically().

---