hal_ppmc.c

Source code for an Numeric Cmputer

/********************************************************************
* Description:  hal_ppmc.c
*               HAL driver for the the Pico Systems family of
*               parallel port motion control boards, including
*               the PPMC board set, the USC, and the UPC. 
*
* Usage:  halcmd loadrt hal_ppmc port_addr=<addr1>[,addr2[,addr3]]
*               where 'addr1', 'addr2', and 'addr3' are the addresses
*               of up to three parallel ports.
*
* Author: John Kasunich, Jon Elson, Stephen Wille Padnos
* License: GPL Version 2
*    
* Copyright (c) 2005 All rights reserved.
*
* Last change: 
# $Revision: 1.22 $
* $Author: cradek $
* $Date: 2006/01/20 21:01:50 $
********************************************************************/

/** The driver searches the entire address space of the enhanced
    parallel port (EPP) at 'port_addr', looking for any board(s)
    in the PPMC family.  It then exports HAL pins for whatever it
    finds, as well as a pair of functions, one that reads all 
    inputs, and one that writes all outputs.
*/

/** This program is free software; you can redistribute it and/or
    modify it under the terms of version 2.1 of the GNU General
    Public License as published by the Free Software Foundation.
    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111 USA

    THE AUTHORS OF THIS LIBRARY ACCEPT ABSOLUTELY NO LIABILITY FOR
    ANY HARM OR LOSS RESULTING FROM ITS USE.  IT IS _EXTREMELY_ UNWISE
    TO RELY ON SOFTWARE ALONE FOR SAFETY.  Any machinery capable of
    harming persons must have provisions for completely removing power
    from all motors, etc, before persons enter any danger area.  All
    machinery must be designed to comply with local and national safety
    codes, and the authors of this software can not, and do not, take
    any responsibility for such compliance.

    This code was written as part of the EMC HAL project.  For more
    information, go to www.linuxcnc.org.
*/

#ifndef RTAPI
#error This is a realtime component only!
#endif

#include <linux/slab.h>		/* kmalloc() */
#include "rtapi.h"		/* RTAPI realtime OS API */
#include "rtapi_app.h"		/* RTAPI realtime module decls */
#include "hal.h"		/* HAL public API decls */

#define MAX_BUS 3	/* max number of parports (EPP busses) */

#define	EPSILON		1e-20

#ifdef MODULE
/* module information */
MODULE_AUTHOR("John Kasunich");
MODULE_DESCRIPTION("HAL driver for Universal PWM Controller");
#ifdef MODULE_LICENSE
MODULE_LICENSE("GPL");
#endif /* MODULE_LICENSE */
int port_addr[MAX_BUS] = { 0x0378, 0, 0 };  /* default, 1 bus at 0x0378 */
MODULE_PARM(port_addr, "1-3i");
MODULE_PARM_DESC(port_addr, "port address(es) for EPP bus(es)");
#endif /* MODULE */

/***********************************************************************
*                DEFINES (MOSTLY REGISTER ADDRESSES)                   *
************************************************************************/

#define SPPDATA(addr) addr
#define STATUSPORT(addr) addr+1
#define CONTROLPORT(addr) addr+2
#define ADDRPORT(addr) addr+3
#define DATAPORT(addr) addr+4

#define NUM_SLOTS      16
#define SLOT_SIZE      16
#define SLOT_ID_OFFSET 15

#define ENCCNT0     0x00	/*  EPP address to read first byte of encoder counter */
#define ENCCNT1     0x03
#define ENCCNT2     0x06
#define ENCCNT3     0x09

#define ENCCTRL     0x03	/* EPP address of encoder control register */
#define ENCRATE     0x04	/* interrupt rate register, only on master encoder */
#define ENCISR      0x0C	/* index sense register */
#define ENCLOAD     0x00	/* EPP address to write into first byte of preset */
				/* register for channels 0 - 3 */

#define DAC_0       0x00	/* EPP address of low byte of DAC chan 0 */
#define DAC_1       0x02	/* EPP address of low byte of DAC chan 1 */
#define DAC_2       0x04	/* EPP address of low byte of DAC chan 2 */
#define DAC_3       0x06	/* EPP address of low byte of DAC chan 3 */

#define DAC_MODE_0  0x4C
#define DAC_WRITE_0 0x48

#define DAC_MODE_1  0x5C
#define DAC_WRITE_1 0x58

#define PWM_GEN_0       0x10	/* EPP addr of low byte of PWM generator 0 LSB */
//      PWM_GEN_0a      0x11	/* high byte MSB */
#define PWM_GEN_1       0x12
#define PWM_GEN_2       0x14
#define PWM_GEN_3       0x16
/* FIXME - I don't know if this is the right address... the map shows it as
   0x1C, but the text on the webpage says it follows right after the data
   registers, which would be 0x18...  yet another ambiguous document */
#define PWM_CTRL_0      0x1C
#define PWM_FREQ_LO     0x1D
#define PWM_FREQ_HI     0x1E

#define RATE_GEN_0      0x10	/* EPP addr of low byte of rate generator 0 LSB */
//      RATE_GEN_0a     0x11	/* middle byte */
//      RATE_GEN_0b     0x12	/* MSB */
#define RATE_GEN_1      0x13
#define RATE_GEN_2      0x16
#define RATE_GEN_3      0x19
#define RATE_CTRL_0     0x1C
#define RATE_SETUP_0    0x1D
#define RATE_WIDTH_0    0x1E

#define UxC_DINA        0x0D	/* EPP address of digital inputs on univstep */
#define UxC_DINB        0x0E
#define UxC_ESTOP_IN    0x0E
/* The "estop" input will always report OFF to the software, regardless
   of the actual state of the physical input, unless the "estop" output
   has being turned on by the software. */

#define UxC_DOUTA       0x1F	/* EPP address of digital outputs */
#define UxC_ESTOP_OUT   0x1F
/* The physical output associated with the "estop" output will not come on
   unless the physical "estop" input is also on.  All physical outputs
   will not come on unless the physical "estop" output is on. */
   
/* These strange interactions between inputs and outputs are just a little
   crazy in my humble opinion */

#define DIO_DINA        0x00	/* EPP address of digital inputs on DIO */
#define DIO_DINB        0x01
#define DIO_ESTOP_IN    0x02

#define DIO_DOUTA       0x00	/* EPP address of digital outputs */
#define DIO_ESTOP_OUT   0x01

/***********************************************************************
*                       STRUCTURE DEFINITIONS                          *
************************************************************************/

/* this structure contains the runtime data for a digital output */
typedef struct {
    hal_bit_t *data;		/* output pin value */
    hal_bit_t invert;		/* parameter to invert output pin */
} dout_t;

/* this structure contains the runtime data for a digital input */
typedef struct {
    hal_bit_t *data;		/* input pin value */
    hal_bit_t *data_not;	/* inverted input pin value */
} din_t;

/* this structure contains the runtime data for a step pulse generator */
typedef struct {
    hal_bit_t *enable;		/* enable pin for step generator */
    hal_float_t *vel;		/* velocity command pin*/
    hal_float_t scale;		/* parameter: scaling for vel to Hz */
    hal_float_t max_vel;	/* velocity limit */
    hal_float_t freq;		/* parameter: velocity cmd scaled to Hz */
} stepgen_t;

/* runtime data for a set of 4 step pulse generators */
typedef struct {
    stepgen_t sg[4];		/* per generator data */
    hal_u8_t setup_time;	/* setup time in 100nS increments */
    hal_u8_t pulse_width;	/* pulse width in 100nS increments */
    hal_u8_t pulse_space;	/* min pulse space in 100nS increments */
} stepgens_t;

#define BOOT_NORMAL 0
#define BOOT_REV    1
#define BOOT_FWD    2

/* this structure contains the runtime data for a PWM generator */
typedef struct {
    hal_bit_t *enable;		/* enable pin for PWM generator */
    hal_float_t *value;		/* value command pin */
    hal_float_t scale;		/* parameter: scaling */
    hal_float_t max_dc;		/* maximum duty cycle 0.0-1.0 */
    hal_float_t min_dc;		/* minimum duty cycle 0.0-1.0 */
    hal_float_t duty_cycle;	/* actual duty cycle output */
    hal_bit_t bootstrap;	/* enable bootstrap mode (pulses at startup) */
    unsigned char boot_state;	/* state for bootstrap state machine */
    unsigned char old_enable;	/* used to detect rising edge, for boot */
} pwmgen_t;

/* runtime data for a set of 4 PWM generators */
typedef struct {
    pwmgen_t pg[4];		/* per generator data */
    hal_float_t freq;		/* PWM frequency */
    hal_float_t old_freq;	/* previous value, to detect changes */
    unsigned short period;	/* period in clock ticks */
    double period_recip;	/* reciprocal of period */
} pwmgens_t;

/* runtime data for a single encoder */
typedef struct {
    hal_float_t *position;      /* output: scaled position pointer */
    hal_s32_t *count;           /* output: unscaled encoder counts */
    hal_s32_t *delta;		/* output: delta counts since last read */
    hal_float_t scale;          /* parameter: scale factor */
    hal_bit_t *index;           /* output: index flag */
    signed long oldreading;     /* used to detect overflow / underflow of the counter */
} encoder_t;

/* this structure contains the runtime data for a single EPP bus slot */
/* A single slot can contain a wide variety of "stuff", ranging 
   from PWM or stepper or DAC outputs, to encoder inputs, to digital
   I/O.  at runtime, the proper function(s) need to be invoked to 
   handle it.  We do that by having an array of functions that are
   called in order.  The entries are filled in when the init code
   scans the bus and determines what is in each slot */

#define MAX_FUNCT 10

struct slot_data_s;

typedef void (slot_funct_t)(struct slot_data_s *slot);

typedef struct slot_data_s {
    unsigned char id;		/* slot id code */
    unsigned char ver;		/* slot version code */
    unsigned char strobe;	/* does this slot need a latch strobe */
    unsigned char slot_base;	/* base addr of this 16 byte slot */
    unsigned int port_addr;	/* addr of parport */
    unsigned char first_rd;	/* first epp address needed by read_all */
    unsigned char last_rd;	/* last epp address needed by read_all */
    unsigned char num_rd_functs;/* number of read functions */
    unsigned char rd_buf[32];	/* cached data read from epp bus */
    slot_funct_t *rd_functs[MAX_FUNCT];	/* array of read functions */
    unsigned char first_wr;	/* first epp address needed by write_all */
    unsigned char last_wr;	/* last epp address needed by write_all */
    unsigned char num_wr_functs;/* number of write functions */
    unsigned char wr_buf[32];	/* cached data to be written to epp bus */
    slot_funct_t *wr_functs[MAX_FUNCT];	/* array of write functions */
    dout_t *digout;		/* ptr to shmem data for digital outputs */
    din_t *digin;		/* ptr to shmem data for digital inputs */
    stepgens_t *stepgen;	/* ptr to shmem data for step generators */
    pwmgens_t *pwmgen;		/* ptr to shmem data for PWM generators */
    encoder_t *encoder;         /* ptr to shmem data for encoders */
} slot_data_t;

/* this structure contains the runtime data for a complete EPP bus */

typedef struct {
//    unsigned int port_addr;	/* addr of parport to talk to board */
    int busnum;			/* bus number */
    unsigned char have_master;	/* true if a master has been configured */
    unsigned int last_digout;	/* used for numbering digital outputs */
    unsigned int last_digin;	/* used for numbering digital outputs */
    unsigned int last_stepgen;	/* used for numbering step generators */
    unsigned int last_pwmgen;	/* used for numbering PWM generators */
    unsigned int last_encoder;	/* used for numbering encoders */
    char slot_valid[NUM_SLOTS];	/* tags for slots that are used */
    slot_data_t slot_data[NUM_SLOTS];  /* data for slots on EPP bus */
} bus_data_t;


/***********************************************************************
*                          GLOBAL VARIABLES                            *
************************************************************************/

static bus_data_t *bus_array[MAX_BUS];
static int comp_id;		/* component ID */

/***********************************************************************
*                    REALTIME FUNCTION DECLARATIONS                    *
************************************************************************/

static void read_all(void *arg, long period);
static void write_all(void *arg, long period);

static void read_digins(slot_data_t *slot);
static void write_digouts(slot_data_t *slot);
static void write_stepgens(slot_data_t *slot);
static void write_pwmgens(slot_data_t *slot);
static void read_encoders(slot_data_t *slot);

/***********************************************************************
*                  REALTIME I/O FUNCTION DECLARATIONS                  *
************************************************************************/

static void BusReset(unsigned int port_addr);
static int ClrTimeout(unsigned int port_addr);
static unsigned short SelRead(unsigned char epp_addr, unsigned int port_addr);
static unsigned short ReadMore(unsigned int port_addr);
static void SelWrt(unsigned char byte, unsigned char epp_addr, unsigned int port_addr);
static void WrtMore(unsigned char byte, unsigned int port_addr);


/***********************************************************************
*                  LOCAL FUNCTION DECLARATIONS                         *
************************************************************************/

static int add_rd_funct(slot_funct_t *funct, slot_data_t *slot, int min_addr, int max_addr );
static int add_wr_funct(slot_funct_t *funct, slot_data_t *slot, int min_addr, int max_addr );

static int export_UxC_digin(slot_data_t *slot, bus_data_t *bus);
static int export_UxC_digout(slot_data_t *slot, bus_data_t *bus);
static int export_USC_stepgen(slot_data_t *slot, bus_data_t *bus);
static int export_UPC_pwmgen(slot_data_t *slot, bus_data_t *bus);
static int export_encoders(slot_data_t *slot, bus_data_t *bus);

/***********************************************************************
*                       INIT AND EXIT CODE                             *
************************************************************************/

int rtapi_app_main(void)
{
    int msg, rv, rv1, busnum, slotnum, n, boards;
    int idcode, id, ver;
    bus_data_t *bus;
    slot_data_t *slot;
    char buf[HAL_NAME_LEN + 2];

    rtapi_print_msg(RTAPI_MSG_INFO, "PPMC: installing driver\n");
    /* This function exports a lot of stuff, which results in a lot of
       logging if msg_level is at INFO or ALL. So we save the current value
       of msg_level and restore it later.  If you actually need to log this
       function's actions, change the second line below */
    msg = rtapi_get_msg_level();
//    rtapi_set_msg_level(RTAPI_MSG_WARN);

    /* validate port addresses */
    n = 0;
    /* if an error occurs, bailing out in the middle of init can leave
       a mess of partially allocated stuff.  So we don't normally bail
       out, instead we set rv non-zero to indicate failure, and carry
       on.  Later, we see that rv is set, and clean up anything that
       might have been allocated before we return. */
    rv = 0;
    for ( busnum = 0 ; busnum < MAX_BUS ; busnum++ ) {
	/* init pointer to bus data */
	bus_array[busnum] = NULL;
	/* check to see if a port address was specified */
	if ( port_addr[busnum] == 0 ) {
	    /* nope, skip it */
	    continue;
	}
	/* is it legal? */
	if ( port_addr[busnum] > 65535 ) {
	    /* nope, complain and skip it */
	    rtapi_print_msg(RTAPI_MSG_ERR, 
		"PPMC: ERROR: invalid port_addr: %0X\n", port_addr[busnum]);
	    rv = -1;
	    continue;
	}
	/* got a good one */
	n++;
    }
    if ( rv != 0 ) {
	/* one or more invalid addresses, already printed msg */
	return -1;
    }
    if ( n == 0 ) {
	rtapi_print_msg(RTAPI_MSG_ERR, 
	    "PPMC: ERROR: no ports specified\n");
	return -1;
    }
    /* have valid config info, connect to the HAL */
    comp_id = hal_init("hal_ppmc");
    if (comp_id < 0) {
	rtapi_print_msg(RTAPI_MSG_ERR, "PPMC: ERROR: hal_init() failed\n");
	return -1;
    }
    /* begin init - loop thru all busses */
    for ( busnum = 0 ; busnum < MAX_BUS ; busnum++ ) {