M7I43_HM2

m7i43_hm2 − RTAI driver for the Mesa Electronics 7i43 EPP Anything IO board with HostMot2 firmware.

loadrt m7i43_hm2 [ioaddr=N] [ioaddr_hi=N] [epp_wide=N] [num_encoders=N] [num_pwmgens=N] [num_stepgens=N] [watchdog_timeout_ns=N] [debug_epp=N] [debug_idrom=N] [debug_module_descriptors=N] [debug_pin_descriptors=N] [debug_functions=N]

ioaddr [default: 0x378]

The base address of the parallel port.

ioaddr_hi [default: 0]

The secondary address of the parallel port, used to set EPP mode. 0 means to use ioaddr + 0x400.

epp_wide [default: 1]

Set to zero to disable the "wide EPP mode". "Wide" mode allows a 16- and 32-bit EPP transfers, which can reduce the time spent in the read and write functions. However, this may not work on all EPP parallel ports.

num_encoders [default: -1]

Defaults to -1, which means "use all the encoder instances the firmware has". If num_encoders is smaller than the number of encoder instances present in the firmware, only the first num_encoders instances are enabled; all later encoder instances are disabled and their I/O pins become digital I/O pins.

num_pwmgens [default: -1]

Defaults to -1, which means "use all the pwmgen instances the firmware has". If num_pwmgens is smaller than the number of pwmgen instances present in the firmware, only the first num_pwmgens instances are enabled; all later pwmgen instances are disabled and their I/O pins become digital I/O pins.

num_stepgens [default: -1]

Defaults to -1, which means "use all the stepgen instances the firmware has". If num_stepgens is smaller than the number of stepgen instances present in the firmware, only the first num_stepgens instances are enabled; all later stepgen instances are disabled and their I/O pins become digital I/O pins.

watchdog_timeout_ns [default: 1000000]

Watchdog timeout in nanoseconds. Defaults to 1,000,000 ns (1 ms). The pet_watchdog() function must be called at least this frequently, or it will bite. When the watchdog bites, all I/O pins are reset to inputs (high with pullups) and all communication with the 7i43 stops. Each board exports a binary HAL pin called "watchdog.has_bit", which is set to 1 when the watchdog bites. When this pin is True, the driver will not communicate with the board. When the user sets the pin to False, the driver will reset the board’s I/O pins to the configuration selected at load-time, and communications will resume.

debug_epp [default: 0]

Developer/debug use only! Enable debug logging of most EPP transfers.

debug_idrom [default: 0]

Developer/debug use only! Enable debug logging of the HostMot2 IDROM header.

debug_module_descriptors [default: 0]

Developer/debug use only! Enable debug logging of the HostMot2 Module Descriptors.

debug_pin_descriptors [default: 0]

Developer/debug use only! Enable debug logging of the HostMot2 Pin Descriptors.

debug_functions [default: 0]

Developer/debug use only! Enable debug logging of the HostMot2 Functions used.

NOTE: This driver is deprecated, and will be removed in the future! All users are encouraged to transition to the hostmot2 driver, which is being actively developed!

m7i43_hm2 is an RTAI device driver that interfaces the Mesa 7i43 board with the HostMot2 firmware to the EMC2 HAL. Both the 200K and the 400K FPGAs are supported.

The driver talks with the 7i43 over the parallel port, not over USB. USB can be used to power the 7i43, but not to talk to it. USB communication with the 7i43 will not be supported any time soon, since USB has poor real-time qualities.

The driver sends the HostMot2 firmware to the board at module load time. The board should be ready to accept new firmware before loading the driver, ie both the INIT and DONE lights should be on.

Jumper settings

The board must be configured to get its firmware from the EPP port. To do this, jumpers W4 and W5 must both be down, ie toward the USB connector.

The board must be configured to power on whether or not the USB interface is active. This is done by setting jumper W7 up, ie away from the edge of the board.

Firmware

The HostMot2 firmware provides encoders, PWM generators, step/dir generators, and general purpose I/O pins (GPIOs). These things are called "Functions". The firmware is configured, at firmware compile time, to provide zero or more instances of each of these four Functions.

The firmware also provides a watchdog function, described in the Watchdog section below.

Communicating with the board

The 7i43 communicates with the EMC computer over EPP, the Enhanced Parallel Port. This provides about 1 MBps of throughput, and the communication latency is very predictable and reasonably low.

EPP is very reliable under normal circumstances, but bad cabling or excessively long cabling runs may cause communication timeouts. The driver exports a parameter named m7i43_hm2.<BoardNum>.epp_errors to inform HAL of this condition. When the driver detects an EPP timeout, it sets epp_errors to 1 and stops communicating with the 7i43 board. Setting epp_errors back to 0 makes the driver start trying to communicate with the 7i43 again.

Watchdog

The 7i43 FPGA firmware implements a watchdog function. The timeout is settable a driver load time using the watchdog_timeout_ns modparam described below. The "pet-watchdog" function must be called no more than that many nanoseconds appart, or the watchdog will bite.

When the watchdog bites, all board’s I/O pins revert to inputs (pulled high), and all communication with the board stops. This condition is reported to HAL by the watchdog.has-bit pin going high. The user must set the pin back to low to restart communication with the board.

Board I/O Pins

The 7i43 board has 48 I/O pins, 0-23 on the P4 connector and 24-47 on the P3 connector (see Mesa Electronics’ manual for details on the pinout). Each pin can be configured, at driver load time, to serve one of two purposes: either as a particular I/O pin of a particular Function instance (encoder, pwmgen, or stepgen), or as a general purpose digital I/O pin. By default all firmware functions are enabled, and all the board’s pins are used by the Function instances.

The user can disable Function instances at driver load time, by specifying the module parameters num_encoders, num_pwmgens, and num_stepgens (described above). Any pins which belong to Function instances that have been disabled automatically become GPIOs.

encoder

Very basic support, more to come. This is what’s implemented so far:

Encoders have names like "m7i43_hm2.<BoardNum>.encoder.<Instance>". Instance is a two-digit number that corresponds to the HostMot2 encoder instance number. There are ’num_encoders’ instances, starting with 00.

In HM2, each encoder uses three input IO pins: A, B, and Index (sometimes also known as Z). Index is currently not used, this will be fixed in the nearish future.

Each encoder instance has the following pins and parameters:

Pins:

(s32 out) count: Number of encoder counts since the previous reset. (Like CDI.)

(float out) position: Encoder position (count / scale). (Like CDI.)

Parameters:

(float r/w) scale: Converts from ’count’ units to ’position’ units. (Like CDI.)

pwmgen

Very basic support, more to come. This is what’s implemented so far:

pwmgens have names like "m7i43_hm2.<BoardNum>.pwmgen.<Instance>". Instance is a two-digit number that corresponds to the HostMot2 pwmgen instance number. There are ’num_pwmgens’ instances, starting with 00.

In HM2, each pwmgen uses three output IO pins: Not-Enable, Out0, and Out1.

The function of the Out0 and Out1 IO pins varies with output-type parameter (see below).

The m7i43_hm2 pwmgen representation is modeled on the pwmgen software component. Each pwmgen instance has the following pins and parameters:

Pins:

(bit input) enable: If true, the pwmgen will set its Not-Enable pin false and output its PWM and Direction signals. If ’enable’ is false, pwmgen will set its Not-Enable pin true and not output any signals.

(float input) value: The current pwmgen command value, in arbitrary units.

Parameters:

(float rw) scale: Scaling factor to convert ’value’ from arbitrary units to duty cycle: dc = value / scale. Duty cycle has an effective range of -1.0 to +1.0 inclusive.

(s32 rw) output-type: This emulates the output_type load-time argument to the software pwmgen component. This parameter may be changed at runtime, but most of the time you probably want to set it at startup and then leave it alone. Accepted values are 1 (PWM on Out0 and Direction on Out1) and 2 (Up on Out0 and Down on Out1).

stepgen

Very basic support. This is what’s implemented so far:

stepgens have names like "m7i43_hm2.<BoardNum>.stepgen.<Instance>. Instance is a two-digit number that corresponds to the HostMot2 stepgen instance number. There are ’num_stepgens’ instances, starting with 00.

Currently only Step/Dir output and Position-mode control is supported.

Each stepgen allocates 6 IO pins, but only uses two: Step and Direction outputs.

The m7i43_hm2 stepgen representation is modeled on the stepgen software component. Each stepgen instance has the following pins and parameters:

Pins:

(float input) position_cmd: Target of stepper motion, in arbitrary position units.

(float output) counts: Feedback position in counts (number of steps).

(float output) position-fb: Feedback position in arbitrary position units (counts / position_scale).

(float output) velocity-fb: Feedback velocity in arbitrary position units per second.

Params:

(float r/w) position_scale: Converts from counts to position units. position = counts / position_scale

(float r/w) steplen: Duration of the step signal, in seconds.

(float r/w) stepspace: Minimum interval between step signals, in seconds.

(float r/w) dirsetup: Minimum duration of stable Direction signal before a step begins, in seconds.

(float r/w) dirhold: Minimum duration of stable Direction signal after a step ends, in seconds.

General Purpose I/O

Pins which are not used by one of the Functions above are exported to HAL as GPIO pins. GPIO pins have names like "m7i43_hm2.<BoardNum>.gpio.<PinNum>". PinNum is a three-digit number that corresponds to the I/O Pin number as given in Mesa Electronics’ manual for the 7i43 board.

Each GPIO has the following pins:

(bit out) in & in_not: State (normal and inverted) of the hardware input pin. (Like CDI for Digital Input).

(bit in) out: Value to be written (possibly inverted) to the hardware output pin. (Like the CDI for Digital Output.)

Each GPIO has the following params:

(bin r/w) is_output: If set to 1, the GPIO is an output, and the values of the "in" and "in_not" HAL pins are undefined. If set to 0, the GPIO is an input, and writes to the "out" HAL pin have no effect.

(bin r/w) invert_output: If set to 1, the value that will appear on the board’s I/O pin will be the inverse of the value written to HAL’s "out" pin. (This corresponds to the ’invert’ parameter in the CDI for Digital Output.)

m7i43-hm2.gpio-read

Read GPIO pins.

m7i43-hm2.gpio-write

Write GPIO pins.

m7i43-hm2.encoder-update-counters

Read encoder counts.

m7i43-hm2.encoder-capture-position (uses floating-point)

Compute encoder position.

m7i43-hm2.pwmgen-update (uses floating-point)

Write pwmgen values.

m7i43-hm2.stepgen-update (uses floating-point)

Update stepgen values.

m7i43-hm2.pet-watchdog

Pet the watchdog to keep it from biting us for a while.

m7i43-hm2.ignore bit in

ignore this pin, comp needs it

GPL