parport.c

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////////////
//     
//    __                                ______
//   / /_______________  ____  ___     / ____/
//  / __/ ___/ ___/ __ \/ __ \/ _ \   /___ )  
// / /_(__  ) /__/ /_/ / /_/ /  __/  ____/ /  
// \__/____/\___/\____/ .___/\___/  /_____/   
//                   /_/                      
//     
/// \file parport.c
/// Definitions of parallel port functions.
/// \example parport01.c
/// \example parport02.c
/// \example parport03.c
////////////////////////////////////////////////////////////////////////////////


#include "../include/tscope5/parport.h"
#include "../include/tscope5/timer.h"
#include "../include/tscope5/parport_internal.h"
#include "../include/tscope5/system_internal.h"

#ifdef TS5_WINDOWS
    #include <windows.h>
    HINSTANCE hLib;
    typedef short (_stdcall *inbptr)(short portaddr);
    typedef short (_stdcall *outbptr)(short portaddr, short value);
    inbptr inb;
    outbptr outb;

#elif defined TS5_LINUX
    #include <unistd.h>
    #include <sys/io.h>

#endif


////////////////////////////////////////////////////////////////////////////////
/// @name Response registration
/// Parallel port boxes can be used as response devices. 
/// See timer.c for more information about response registration.
//@{
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// Define a parallel port button as a response button.
///
/// \param device Number of the parallel port (devices are numbered from 1).
/// \param button Number of the button (buttons are counted from 1).
///
/// \return The reponse number associated with the button.
///
/// Give a positive number for the button if you want to monitor button press events,
/// a negative number if you want to monitor button release events.
////////////////////////////////////////////////////////////////////////////////
int ts5_define_parport_button(int device, int button)
{
    ts5_check_parport2("ts5_define_parport_button");
    ts5_log(TS5_LOGLEVEL_3, "ts5_define_parport_button(%d,%d)\n", device, button);

    if (device<1 || device>_ts5_status.timer.num_parports) {
        ts5_fatal("%s: %s %d %s %d\n", "ts5_define_parport_button",
                    "device argument is", device,
                    "number of parallel ports is",
                    _ts5_status.timer.num_parports);
    }

    if (_ts5_status.timer.parport[device-1].is_trigger_input_device) {
        ts5_fatal("%s: %s %d %s\n", "ts5_define_parport_button",
                    "parallel port", device, 
                    "is already defined as a trigger input device");
    }

    if (_ts5_status.timer.parport[device-1].is_trigger_output_device) {
        ts5_fatal("%s: %s %d %s\n", "ts5_define_parport_button",
                    "parallel port", device, 
                    "is already defined as a trigger output device");
    }

    if (button==0) {
        ts5_fatal("%s: %s\n", "ts5_define_parport_button",
                    "button argument is 0, response buttons are numbered from 1");
    }
    
    if (abs(button)>_ts5_status.timer.parport[device-1].num_buttons) {
        ts5_fatal("%s: %s %d, %s %d is %d\n", "ts5_define_parport_button",
                    "button argument is", button, 
                    "number of parport buttons for device", device,
                    _ts5_status.timer.parport[device-1].num_buttons);
    }
    
    if (button>0 && _ts5_status.timer.parport[device-1]
                    .button_press_defined[button-1]!=0) {
        ts5_fatal("%s: %s %d %s\n", "ts5_define_parport_button",
                    "button press", button, "is already defined");
    }

    if (button<0 && _ts5_status.timer.parport[device-1]
                    .button_release_defined[-button-1]!=0) {
        ts5_fatal("%s: %s %d %s\n", "ts5_define_parport_button",
                    "button release", button, "is already defined");
    }

    _ts5_status.timer.parport_is_response_device = 1;
    _ts5_status.timer.num_defined_buttons++;
    _ts5_status.timer.num_active_buttons++;
    _ts5_status.timer.parport[device-1].num_defined_buttons++;
    _ts5_status.timer.parport[device-1].num_active_buttons++;

    if (button>0) {
        _ts5_status.timer.parport[device-1]
            .button_press_defined[button-1] =
            _ts5_status.timer.num_defined_buttons;

        _ts5_status.timer.parport[device-1]
            .button_press_active[button-1] =
            _ts5_status.timer.num_defined_buttons;
    }
    else {
        _ts5_status.timer.parport[device-1]
            .button_release_defined[-button-1] =
            _ts5_status.timer.num_defined_buttons;

        _ts5_status.timer.parport[device-1]
            .button_release_active[-button-1] =
            _ts5_status.timer.num_defined_buttons;
    }

    return _ts5_status.timer.num_defined_buttons;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the number of buttons available on a parallel port.
///
/// \param device Number of the parallel port (devices are numbered from 1).
///
/// \return The number of buttons on the parallel port.
////////////////////////////////////////////////////////////////////////////////
int ts5_get_num_parport_buttons(int device)
{
    ts5_check_parport2("ts5_get_num_parport_buttons");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_num_parport_buttons(%d)\n", device);
    
    return _ts5_status.timer.parport[device-1].num_buttons;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the button debounce time of a parallel port response box.
///
/// \param device Number of the parallel port
/// \param button_debounce_time Debounce time in seconds
///
/// \return The previous setting
///
///
/// The debounce time is the minimum amount of time between two state changes of
/// the buttons of the box before Tscope5 really counts it as a state change.
/// On some button boxes it is necessary to set this value because 
/// the press or release of a button causes a ripple in the electrical current
/// sent to the parallel port
/// (instead of a single state change between on and off).
///
/// The debounce time is the amount of time between the press and the release
/// of a button (or vice versa). 
/// So the minimum amount of time between two presses (or two releases)
/// will be twice the debounce time set here.
///
/// The default debounce time is set to 0.0
/// (The button boxes at our department have an internal debouncing circuit).
////////////////////////////////////////////////////////////////////////////////
double ts5_set_parport_button_debounce_time(int device, 
                                            double button_debounce_time)
{
    ts5_check_parport2("ts5_set_parport_button_debounce_time");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_parport_button_debounce_time(%d,%f)\n", 
                device, button_debounce_time);

    if (device<1 || device>_ts5_status.timer.num_parports) {
        ts5_fatal("%s: %s %d %s %d\n", "ts5_set_parport_button_debounce_time",
                    "device argument is", device,
                    "number of parallel ports is",
                    _ts5_status.timer.num_parports);
    }

    if (button_debounce_time < 0.0) {
        ts5_fatal("%s: %s (is %f)\n", "ts5_set_parport_button_debounce_time",
            "debounce time should be positive", button_debounce_time);
    }

    double retval = 
        _ts5_status.timer.parport[device-1].button_debounce_time;

    _ts5_status.timer.parport[device-1].button_debounce_time = 
        button_debounce_time;

    ts5_log(TS5_LOGLEVEL_4, "%s: %s %d to %f (was %f)\n", 
                "ts5_set_parport_button_debounce_time",
                "set debounce time of device", 
                device, 
                _ts5_status.timer.parport[device-1].button_debounce_time, 
                retval);

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the button debounce time of a parallel port response box.
///
/// \param device Number of the parallel port
///
/// \return The debounce time
////////////////////////////////////////////////////////////////////////////////
double ts5_get_parport_button_debounce_time(int device)
{
    ts5_check_parport2("ts5_get_parport_button_debounce_time");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_parport_button_debounce_time(%d)\n", 
                device);

    if (device<1 || device>_ts5_status.timer.num_parports) {
        ts5_fatal("%s: %s %d %s %d\n", "ts5_get_parport_button_debounce_time",
                    "device argument is", device,
                    "number of parallel ports is",
                    _ts5_status.timer.num_parports);

    }

    return _ts5_status.timer.parport[device-1].button_debounce_time;
}


////////////////////////////////////////////////////////////////////////////////
//@}
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// @name Trigger input/output
/// The parallel ports can be used as trigger input/output devices. 
/// See timer.c for more information about trigger input/output.
//@{
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// Define a parallel port as a trigger input device
///
/// \param device Number of the parallel port (devices are numbered from 1).
////////////////////////////////////////////////////////////////////////////////
void ts5_define_parport_trigger_input(int device)
{
    ts5_check_parport2("ts5_define_parport_trigger_input");
    ts5_log(TS5_LOGLEVEL_3, "ts5_define_parport_trigger_input(%d)\n", device);

    if (device<1 || device>_ts5_status.timer.num_parports) {
        ts5_fatal("%s: %s %d %s %d\n", "ts5_define_parport_trigger_input",
                    "device argument is", device,
                    "number of parallel ports is",
                    _ts5_status.timer.num_parports);
    }

    ts5_set_parport_trigger_input("ts5_define_parport_trigger_input", device);
}


////////////////////////////////////////////////////////////////////////////////
/// Turn on parallel port input simulation.
///
/// \param device Number of the parallel port (devices are numbered from 1).
/// \param value Input value that has to be simulated 
/// (0-255, 0 turns the simulation off).
/// \param interval Interval in seconds between two triggers.
////////////////////////////////////////////////////////////////////////////////
void ts5_simulate_parport_trigger_input(int device, unsigned char value, 
                                            double interval)
{
    ts5_check_parport2("ts5_simulate_parport_trigger_input");
    ts5_log(TS5_LOGLEVEL_3, "ts5_simulate_parport_trigger_input(%d,%d,%f)\n", 
                device, value, interval);

    if (device<1 || device>_ts5_status.timer.num_parports) {
        ts5_fatal("%s: %s %d %s %d\n", "ts5_simulate_parport_trigger_input",
                    "device argument is", device,
                    "number of parallel ports is",
                    _ts5_status.timer.num_parports);
    }

    _ts5_status.timer.parport[device-1].simulate_trigger_input = 
        value;
    
    _ts5_status.timer.parport[device-1].trigger_simulation_interval = 
        interval;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the trigger debounce time of a parallel port.
///
/// \param device Number of the parallel port
/// \param trigger_debounce_time Debounce time in seconds
///
/// \return The previous setting
///
/// The default debounce time is set to 0.0
////////////////////////////////////////////////////////////////////////////////
double ts5_set_parport_trigger_debounce_time(int device, 
                                                double trigger_debounce_time)
{
    ts5_check_parport2("ts5_set_parport_trigger_debounce_time");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_parport_trigger_debounce_time(%d,%f)\n", 
                device, trigger_debounce_time);

    if (device<1 || device>_ts5_status.timer.num_parports) {
        ts5_fatal("%s: %s %d %s %d\n", "ts5_set_parport_trigger_debounce_time",
                    "device argument is", device,
                    "number of parallel ports is",
                    _ts5_status.timer.num_parports);
    }

    if (trigger_debounce_time < 0.0) {
        ts5_fatal("%s: %s (is %f)\n", "ts5_set_parport_trigger_debounce_time",
                    "debounce time should be positive", trigger_debounce_time);
    }

    double retval = _ts5_status.timer.parport[device-1]
                        .trigger_debounce_time;

    _ts5_status.timer.parport[device-1].trigger_debounce_time = 
        trigger_debounce_time;

    ts5_log(TS5_LOGLEVEL_4, "%s: %s %d to %f (was %f)\n",
                "ts5_set_parport_trigger_debounce_time",
                "set debounce time of device",
                device, _ts5_status.timer.parport[device-1]
                .trigger_debounce_time, retval);

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the trigger debounce time of a parallel port.
///
/// \param device Number of the parallel port
///
/// \return The debounce time
////////////////////////////////////////////////////////////////////////////////
double ts5_get_parport_trigger_debounce_time(int device)
{
    ts5_check_parport2("ts5_get_parport_trigger_debounce_time");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_parport_trigger_debounce_time(%d)\n", 
                device);

    if (device<1 || device>_ts5_status.timer.num_parports) {
        ts5_fatal("%s: %s %d %s %d\n", "ts5_get_parport_trigger_debounce_time",
                    "device argument is", device,
                    "number of parallel ports is",
                    _ts5_status.timer.num_parports);
    }

    return _ts5_status.timer.parport[device-1].trigger_debounce_time;
}


////////////////////////////////////////////////////////////////////////////////
/// Send a trigger trough a parallel port
///
/// \param device Number of the parallel port (devices are numbered from 1).
/// \param value The trigger value that has to be sent (0-255).
////////////////////////////////////////////////////////////////////////////////
void ts5_send_parport_trigger(int device, unsigned char value)
{
    ts5_check_parport2("ts5_send_parport_trigger");
    ts5_log(TS5_LOGLEVEL_3, "ts5_send_parport_trigger(%d,%d)\n", device, value);

    if (device<1 || device>_ts5_status.timer.num_parports) {
        ts5_fatal("%s: %s %d %s %d\n", "ts5_send_parport_trigger",
                    "device argument is", device,
                    "number of parallel ports is",
                    _ts5_status.timer.num_parports);
    }

    ts5_set_parport_trigger_output("ts5_send_parport_trigger", device);

    #ifdef TS5_WINDOWS
        outb(_ts5_status.timer.parport_data_register[device-1], value);
        
        ts5_wait(_ts5_status.timer.parport[device-1]
                    .trigger_output_time);
        
        outb(_ts5_status.timer.parport_data_register[device-1], 0);

    #elif defined TS5_LINUX
        outb(value, _ts5_status.timer.parport_data_register[device-1]);
        
        ts5_wait(_ts5_status.timer.parport[device-1]
                    .trigger_output_time);
        
        outb(0, _ts5_status.timer.parport_data_register[device-1]);

    #endif
}


////////////////////////////////////////////////////////////////////////////////
/// Set the trigger output time of a parallel port.
///
/// \param device Number of the parallel port
/// \param trigger_output_time Output time in seconds
///
/// \return The previous setting
///
/// The default output time is 0.002 seconds.
////////////////////////////////////////////////////////////////////////////////
double ts5_set_parport_trigger_output_time(int device, 
                                            double trigger_output_time)
{
    ts5_check_parport2("ts5_set_parport_trigger_output_time");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_parport_trigger_output_time(%d,%f)\n", 
                device, trigger_output_time);

    if (device<1 || device>_ts5_status.timer.num_parports) {
        ts5_fatal("%s: %s %d %s %d\n", "ts5_set_parport_trigger_output_time",
                    "device argument is", device,
                    "number of parallel ports is",
                    _ts5_status.timer.num_parports);
    }

    if (trigger_output_time < 0.0) {
        ts5_fatal("%s: %s (is %f)\n", "ts5_set_parport_trigger_output_time", 
                    "output time should be positive", trigger_output_time);
    }

    double retval = _ts5_status.timer.parport[device-1]
                        .trigger_output_time;

    _ts5_status.timer.parport[device-1].trigger_output_time = 
        trigger_output_time;

    ts5_log(TS5_LOGLEVEL_4, "%s: %s %d to %f (was %f)\n",
                "ts5_set_parport_trigger_output_time", 
                "set output time of device", device, 
                _ts5_status.timer.parport[device-1].trigger_output_time, 
                retval);

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the trigger output time of a parallel port.
///
/// \param device Number of the parallel port
///
/// \return The output time
////////////////////////////////////////////////////////////////////////////////
double ts5_get_parport_trigger_output_time(int device)
{
    ts5_check_parport2("ts5_get_parport_trigger_output_time");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_parport_trigger_output_time(%d)\n", 
                device);

    if (device<1 || device>_ts5_status.timer.num_parports) {
        ts5_fatal("%s: %s %d %s %d\n", "ts5_get_parport_trigger_output_time",
                    "device argument is", device,
                    "number of parallel ports is",
                    _ts5_status.timer.num_parports);
    }

    return _ts5_status.timer.parport[device-1].trigger_output_time;
}


////////////////////////////////////////////////////////////////////////////////
//@}
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// @name Port settings
/// On older motherboards there were three parallel ports, 
/// with addresses 0x378, 0x278, 0x3BC. 
///
/// This is the default setting in Tscope5.
///
/// On newer motherboards there are no parallel ports, 
/// but PCI parallel port cards can be added.
///
/// If you have such a card, 
/// you will need set the number of parallel ports
/// and their addresses using the functions below.
//@{
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// Set the number of parallel ports that are connected to the system.
///
/// \param num_parports 
///
/// \return The previous setting.
////////////////////////////////////////////////////////////////////////////////
int ts5_set_num_parports(int num_parports)
{
    ts5_check_parport("ts5_get_num_parports");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_num_parports(%d)\n", num_parports);

    int retval = _ts5_status.timer.num_parports;

    if (num_parports < 0) {
        ts5_fatal("ts5_set_num_parports: num_parports should be >= 0\n");
    }

    if (num_parports > TS5_PARPORT_MAXPORT) {
        ts5_fatal("ts5_set_num_parports: num_parports should be < %d\n", 
                    TS5_PARPORT_MAXPORT);
    }

    _ts5_status.timer.num_parports = num_parports;

    ts5_log(TS5_LOGLEVEL_4, 
                "ts5_set_num_parports: set num_parports to %d (was %d)\n",
                _ts5_status.timer.num_parports, retval);

    return retval;  
}


////////////////////////////////////////////////////////////////////////////////
/// Get the number of parallel ports that are connected to the system.
///
/// \return The number of parallel ports that are connected to the system.
////////////////////////////////////////////////////////////////////////////////
int ts5_get_num_parports()
{
    ts5_check_parport2("ts5_get_num_parports");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_num_parports()\n");

    return _ts5_status.timer.num_parports;  
}


////////////////////////////////////////////////////////////////////////////////
/// Set the address of a parallel port.
///
/// \param device Number of the parallel port
/// \param address The address of the parallel port
/// 
/// \return The previous address of the parallel port.
////////////////////////////////////////////////////////////////////////////////
short ts5_set_parport_address(int device, short address)
{
    ts5_check_parport("ts5_set_parport_address");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_parport_address(%d, %d)\n", device, address);

    if (device < 1) {
        ts5_fatal("ts5_set_parport_address: device should be >= 1\n");
    }

    if (device > _ts5_status.timer.num_parports) {
        ts5_fatal("ts5_set_parport_address: device should be <= %d\n", 
                    _ts5_status.timer.num_parports);
    }   
        
    short retval = _ts5_status.timer.parport_base_address[device-1];

    _ts5_status.timer.parport_base_address[device-1] = address;

    _ts5_status.timer.parport_data_register[device-1] = 
        _ts5_status.timer.parport_base_address[device-1];

    _ts5_status.timer.parport_status_register[device-1] = 
        _ts5_status.timer.parport_base_address[device-1]+1;

    _ts5_status.timer.parport_control_register[device-1] = 
        _ts5_status.timer.parport_base_address[device-1]+2;
    
    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the address of a parallel port.
///
/// \param device Number of the parallel port
///
/// \return The address of the parallel port.
////////////////////////////////////////////////////////////////////////////////
short ts5_get_parport_address(int device)
{
    ts5_check_parport2("ts5_get_parport_address");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_parport_address(%d)\n", device);

    if (device < 1) {
        ts5_fatal("ts5_get_parport_address: device should be >= 1\n");
    }

    if (device > _ts5_status.timer.num_parports) {
        ts5_fatal("ts5_get_parport_address: device should be <= %d\n", 
                    _ts5_status.timer.num_parports);
    }   
    
    return _ts5_status.timer.parport_base_address[device-1];    
}


////////////////////////////////////////////////////////////////////////////////
//@}
////////////////////////////////////////////////////////////////////////////////