stepgen.c

Source code for an Numeric Cmputer

/********************************************************************
* Description:  stepgen.c
*               This file, 'stepgen.c', is a HAL component that 
*               provides software based step pulse generation.
*
* Author: John Kasunich
* License: GPL Version 2
*    
* Copyright (c) 2003 All rights reserved.
*
********************************************************************/
/** This file, 'stepgen.c', is a HAL component that provides software
    based step pulse generation.  The maximum step rate will depend
    on the speed of the PC, but is expected to exceed 1KHz for even
    the slowest computers, and may reach 10KHz on fast ones.  It is
    a realtime component.

    It supports up to 8 pulse generators.  Each generator can produce
    several types of outputs in addition to step/dir, including
    quadrature, half- and full-step unipolar and bipolar, three phase,
    and five phase.  A 32 bit feedback value is provided indicating
    the current position of the motor (assuming no lost steps).
    The number of step generators and type of outputs is determined
    by the insmod command line parameter 'step_type'.  It accepts
    a comma separated (no spaces) list of up to 8 stepping types
    to configure up to 8 channels.  So a command line like this:
          insmod stepgen step_type=0,0,1,2
    will install four step generators, two using stepping type 0,
    one using type 1, and one using type 2.

    The driver exports three functions.  'stepgen.make-pulses', is
    responsible for actually generating the step pulses.  It must
    be executed in a fast thread to reduce pulse jitter.  The other
    two functions are normally called from a much slower thread.
    'stepgen.update-freq' reads the frequency command and sets
    internal variables used by 'stepgen.make-pulses'.
    'stepgen.capture-position' captures and scales the current
    values of the position feedback counters.  Both 'update-freq' and
    'capture-position' use floating point, 'make-pulses' does not.

    The component can optionally create two threads, one that
    supports floating point and one that does not.  The 'period'
    parameter (at insmod time) determines the period of the non-FP
    thread, which is called 'stepgen.thread'.  The 'fp_period'
    parameter sets the period of the floating point thread, which
    is called 'stepgen.threadFP'

    Polarity:

    All signals from this module have fixed polarity (active high
    in most cases).  If the driver needs the opposite polarity,
    the signals can be inverted using parameters exported by the
    hardware driver(s) such as ParPort.

    Stepping Types:

    This module supports a number of stepping types, as follows:

    Type 0:  Step and Direction
                       _____         _____              _____
    STEP  ____________/     \_______/     \____________/     \___
                      |     |       |     |
              |--(1)--|-(2)-|--(3)--|     |--(4)--|
          ____|___________________________________|_____________
    DIR   ____X___________________________________X_____________

    There are two output pins, STEP and DIR.  Timing is controlled
    by HAL parameters.  The parameters are (1): 'stepgen.n.dirsetup'
    minimum delay from a change on the DIR line to the beginning of
    a step pulse, (2): 'stepgen.n.steplen' length of the step pulse,
    (3): 'stepgen.n.stepspace', space between step pulses, and
    (4): 'stepgen.n.dirhold', minimum delay after step pulse before
    DIR may change.  The default values for all four parameters are
    1, which means 1 period of the thread.  A positive frequency
    command results in DIR low, negative frequency command means
    DIR high.  The minimum time between step pulses is 'steplen' +
    'stepspace' periods, and the frequency command is clamped to
    avoid exceeding these limits.

    Type 1:  Up/Down (aka Pseudo-PWM)

    There are two output pins, UP and DOWN.  Whenever a step is
    required, either UP or DOWN is asserted for a single period.
    The frequency command is not clamped, so a step may be
    required every period, and the UP or DOWN line may be asserted
    for several periods in a row.  (At the maximum freqency
    command, UP or DOWN will be constantly asserted.)  This type
    of signal may be usefull with some stepper drives, but is
    primarily intended as a simple and cheap DAC.  A filter
    and differential amp connected between UP and DOWN can
    produce a +/-10V signal, with bandwidth and resolution
    determined by the filter (in general, faster bandwidth
    gives lower resolution, and vice-versa.)

    All the remaining stepping types are simply different patterns
    of output states.  For all of these types, a step can occur
    in every period.  When a step occurs, the output state changes
    to the next (or previous) state in the state listings that
    follow.  There are from two to five output pins, called
    'PhaseA' thru 'PhaseE'.

    Type 2:  Quadrature (aka Gray/Grey code)

    State   Phase A   Phase B
      0        1        0
      1        1        1
      2        0        1
      3        0        0
      0        1        0

    Type 3:  Three Wire

    State   Phase A   Phase B   Phase C
      0        1        0         0
      1        0        1         0
      2        0        0         1
      0        1        0         0

    Type 4:  Three Wire HalfStep

    State   Phase A   Phase B   Phase C
      0        1        0         0
      1        1        1         0
      2        0        1         0
      3        0        1         1
      4        0        0         1
      5        1        0         1
      0        1        0         0

    Type 5:  Unipolar Full Step (one winding on)

    State   Phase A   Phase B   Phase C   Phase D
      0        1        0         0         0
      1        0        1         0         0
      2        0        0         1         0
      3        0        0         0         1
      0        1        0         0         0

    Type 6:  Unipolar Full Step (two windings on)

    State   Phase A   Phase B   Phase C   Phase D
      0        1        1         0         0
      1        0        1         1         0
      2        0        0         1         1
      3        1        0         0         1
      0        1        1         0         0

    Type 7:  Bipolar Full Step (one winding on)

    State   Phase A   Phase B   Phase C   Phase D
      0        1        0         0         0
      1        1        1         1         0
      2        0        1         1         1
      3        0        0         0         1
      0        1        0         0         0

    Type 8:  Bipolar Full Step (two windings on)

    State   Phase A   Phase B   Phase C   Phase D
      0        1        0         1         0
      1        0        1         1         0
      2        0        1         0         1
      3        1        0         0         1
      0        1        0         1         0

    Type 9:  Unipolar Half Step

    State   Phase A   Phase B   Phase C   Phase D
      0        1        0         0         0
      1        1        1         0         0
      2        0        1         0         0
      3        0        1         1         0
      4        0        0         1         0
      5        0        0         1         1
      6        0        0         0         1
      7        1        0         0         1
      0        1        0         0         0

    Type 10:  Bipolar Half Step

    State   Phase A   Phase B   Phase C   Phase D
      0        1        0         0         0
      1        1        0         1         0
      2        1        1         1         0
      3        0        1         1         0
      4        0        1         1         1
      5        0        1         0         1
      6        0        0         0         1
      7        1        0         0         1
      0        1        0         0         0

    Type 11:  Five Wire Unipolar

    State   Phase A   Phase B   Phase C   Phase D  Phase E
      0        1        0         0         0        0
      1        0        1         0         0        0
      2        0        0         1         0        0
      3        0        0         0         1        0
      4        0        0         0         0        1
      0        1        0         0         0        0

    Type 12:  Five Wire Wave

    State   Phase A   Phase B   Phase C   Phase D  Phase E
      0        1        1         0         0        0
      1        0        1         1         0        0
      2        0        0         1         1        0
      3        0        0         0         1        1
      4        1        0         0         0        1
      0        1        1         0         0        0

    Type 13:  Five Wire Unipolar HalfStep

    State   Phase A   Phase B   Phase C   Phase D  Phase E
      0        1        0         0         0        0
      1        1        1         0         0        0
      2        0        1         0         0        0
      3        0        1         1         0        0
      4        0        0         1         0        0
      5        0        0         1         1        0
      6        0        0         0         1        0
      7        0        0         0         1        1
      8        0        0         0         0        1
      9        1        0         0         0        1
      0        1        0         0         0        0

    Type 14:  Five Wire Wave HalfStep

    State   Phase A   Phase B   Phase C   Phase D  Phase E
      0        1        1         0         0        0
      1        1        1         1         0        0
      2        0        1         1         0        0
      3        0        1         1         1        0
      4        0        0         1         1        0
      5        0        0         1         1        1
      6        0        0         0         1        1
      7        1        0         0         1        1
      8        1        0         0         0        1
      9        1        1         0         0        1
      0        1        1         0         0        0

*/

/** Copyright (C) 2003 John Kasunich
                       <jmkasunich AT users DOT sourceforge DOT net>
*/

/** 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/ctype.h>	/* isspace() */
#include "rtapi.h"		/* RTAPI realtime OS API */
#include "rtapi_app.h"		/* RTAPI realtime module decls */
#include "hal.h"		/* HAL public API decls */

#include <linux/types.h>
 /*! \todo FIX ME - Need an ugly hack here to get rid of compile warnings. */
#ifdef __attribute_used__
#undef __attribute_used__
#endif
#ifdef __attribute_pure__
#undef __attribute_pure__
#endif
#include <sys/cdefs.h>
#include <float.h>
#include <math.h>

#define MAX_CHAN 8

#ifdef MODULE
/* module information */
MODULE_AUTHOR("John Kasunich");
MODULE_DESCRIPTION("Step Pulse Generator for EMC HAL");
#ifdef MODULE_LICENSE
MODULE_LICENSE("GPL");
#endif				/* MODULE_LICENSE */
int step_type[MAX_CHAN] = { -1, -1, -1, -1, -1, -1, -1, -1 };
MODULE_PARM(step_type, "1-8i");
MODULE_PARM_DESC(step_type, "stepping types for up to 8 channels");
static long period = 0;		/* non-FP thread period, default = none */
MODULE_PARM(period, "l");
MODULE_PARM_DESC(period, "non-FP thread period (nsecs)");
static long fp_period = 0;	/* FP thread period, default = none */
MODULE_PARM(fp_period, "l");
MODULE_PARM_DESC(fp_period, "floating point thread period (nsecs)");
#endif				/* MODULE */

/***********************************************************************
*                STRUCTURES AND GLOBAL VARIABLES                       *
************************************************************************/

/** These structures contains the runtime data for a single generator.
    The 'st0_t' struct has data needed for stepping type 0 only, and
    'st2_t' has data needed for stepping types 2 and higher only.  A
    union is used so the two structs can share space in the main
    'stepgen_t' structure.  This keeps the frequently accessed parts
    of the main structure smaller, allowing them to occupy fewer cache
    lines.  This improves speed as well as conserving shared memory.
    Data is arranged in the structs in the order in which it will be
    accessed, so fetching one item will load the next item(s) into cache.
*/

typedef struct {
    unsigned char step_type;	/* stepping type - see list above */
    unsigned char need_step;	/* non-zero if we need to step */
    unsigned char setup_timer;	/* timer for dir setup time */
    unsigned char hold_timer;	/* timer for dir hold time */
    unsigned char space_timer;	/* timer for pulse spacing */
    unsigned char len_timer;	/* timer for pulse length */
    hal_u8_t dir_setup;		/* parameter: direction setup time */
    hal_u8_t dir_hold;		/* parameter: direction hold time */
    hal_u8_t step_len;		/* parameter: step pulse length */
    hal_u8_t step_space;	/* parameter: min step pulse spacing */
} st0_t;

typedef struct {
    unsigned char step_type;	/* stepping type - see list above */
    unsigned char state;	/* current position in state table */
    unsigned char cycle_max;	/* cycle length for step types 2 and up */
    unsigned char num_phases;	/* number of phases for types 2 and up */
    unsigned char *lut;		/* pointer to lookup table */
} st2_t;

typedef struct {
    signed long deltalim;	/* max allowed change per period */
    signed long newaddval;	/* desired freq generator add value */
    signed long addval;		/* actual frequency generator add value */
    unsigned long accum;	/* frequency generator accumulator */
    double old_pos_cmd;		/* previous position command (counts) */
    union {
	st0_t st0;		/* working data for step type 0 */
	st2_t st2;		/* working data for step types 2 and up */
    } wd;
    hal_bit_t *phase[5];	/* pins for output signals */
    hal_bit_t *enable;		/* pin for enable stepgen */
    hal_s32_t rawcount;		/* param: position feedback in counts */
    hal_s32_t *count;		/* pin: captured feedback in counts */
    hal_float_t pos_scale;	/* param: steps per position unit */
    float old_scale;		/* stored scale value */
    double scale_recip;		/* reciprocal value used for scaling */
    hal_float_t *pos_cmd;	/* pin: position command (position units) */
    hal_float_t *pos_fb;	/* pin: position feedback (position units) */
    hal_float_t freq;		/* param: frequency command */
    hal_float_t maxvel;		/* param: max velocity, (pos units/sec) */
    hal_float_t maxaccel;	/* param: max accel (pos units/sec^2) */
} stepgen_t;

/* ptr to array of stepgen_t structs in shared memory, 1 per channel */
static stepgen_t *stepgen_array;

/* lookup tables for stepping types 2 and higher - phase A is the LSB */

static const unsigned char master_lut[][10] = {
    {1, 3, 2, 0, 0, 0, 0, 0, 0, 0},	/* type 2: Quadrature */
    {1, 2, 4, 0, 0, 0, 0, 0, 0, 0},	/* type 3: Three Wire */
    {1, 3, 2, 6, 4, 5, 0, 0, 0, 0},	/* type 4: Three Wire Half Step */
    {1, 2, 4, 8, 0, 0, 0, 0, 0, 0},	/* 5: Unipolar Full Step 1 */