hostmot2.9

CNC 的开放码,EMC2 V2.2.8版

.TH HOSTMOT2 "9" "2008-05-13" "EMC Documentation" "HAL Component"
.de TQ
.br
.ns
.TP \\$1
..
.SH NAME

hostmot2 \- EMC2 HAL driver for the Mesa Electronics HostMot2 firmware.
.SH SYNOPSIS

.HP
.B loadrt hostmot2 [debug_idrom=\fIN\fB] [debug_module_descriptors=\fIN\fB] [debug_pin_descriptors=\fIN\fB] [debug_modules=\fIN\fB]
.RS
.TP
\fBdebug_idrom\fR [default: 0]
Developer/debug use only!  Enable debug logging of the HostMot2
IDROM header.
.TP
\fBdebug_module_descriptors\fR [default: 0]
Developer/debug use only!  Enable debug logging of the HostMot2
Module Descriptors.
.TP
\fBdebug_pin_descriptors\fR [default: 0]
Developer/debug use only!  Enable debug logging of the HostMot2
Pin Descriptors.
.TP
\fBdebug_modules\fR [default: 0]
Developer/debug use only!  Enable debug logging of the HostMot2
Modules used.
.RE
.SH DESCRIPTION

hostmot2 is a device driver that interfaces the Mesa HostMot2 firmware
to the EMC2 HAL.  This driver by itself does nothing, the boards that
actually run the firmware require their own drivers before anything
can happen.  Currently drivers are available for the 5i20, 5i22, 5i23,
4i65, and 4i68 (all using the hm2_pci module) and the 7i43 (using the
hm2_7i43 module).

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

The HostMot2 firmware runs on an FPGA board.  The board interfaces with
the computer via PCI, PC-104/Plus, or EPP, and interfaces with motion
control hardware such as servos and stepper motors via I/O pins on
the board.

Each I/O pin can be configured, at board-driver load time, to serve
one of two purposes: either as a particular I/O pin of a particular
Module instance (encoder, pwmgen, or stepgen), or as a general purpose
digital I/O pin.  By default all Module instances are enabled, and all
the board's pins are used by the Module instances.

The user can disable Module instances at board-driver load time, by
specifying a hostmot2 config string modparam.  Any pins which belong to
Module instances that have been disabled automatically become GPIOs.

All IO pins have some HAL presence, whether they belong to an active
module instance or are full GPIOs.  GPIOs can be changed (at run-time)
between inputs, normal outputs, and open drains, and have a flexible
HAL interface.  IO pins that belongs to active module instances are
constrained by the requirements of the owning module, and have a more
limited interface in the HAL .  This is described in the General Purpose
I/O section below.
.SH config modparam

The board-driver modules accept a config string modparam at load time.
This config string is passed to and parsed by the hostmot2 driver when
the board-driver registers a HostMot2 instance.  The format of the config
string is:

.B [firmware=\fIF\fB] [num_encoders=\fIN\fB] [num_pwmgens=\fIN\fB] [num_stepgens=\fIN\fB] [enable_raw]
.RS
.TP
\fBfirmware\fR [optional]
Load the firmware specified by F into the FPGA on this board.  If no
"\fBfirmware=\fIF\fR" string is specified, the FPGA will not be
programmed, and had better have a valid configuration already.
.P
.RS
The requested firmware F is fetched by udev.  udev searches for the
firmware in the system's firmware search path, usually /lib/firmware.
F typically has the form "hm2/<BoardType>/file.bit"; a typical value
for F might be "hm2/5i20/SVST8_4.BIT".  If EMC2 is installed by the
Debian package (.deb), then the firmware files are already installed
in /lib/firmware.  If EMC2 is compiled from CVS and configured for
run-in-place, then the user must symlink the hostmot2 firmware into
/lib/firmware manually, by a command like this:
.P
.RS
\fBsudo ln -s $HOME/emc2-sandbox/src/hal/drivers/mesa-hostmot2/firmware
/lib/firmware/hm2\fR
.RE
.RE
.TP
\fBnum_encoders\fR [optional, default: -1]
Only enable the first N encoders.  If N is -1, all encoders are enabled.
If N is 0, no encoders are enabled.  If N is greater than the number of
encoders available in the firmware, the board will fail to register.
.TP
\fBnum_pwmgens\fR [optional, default: -1]
Only enable the first N pwmgens.  If N is -1, all pwmgens are enabled.
If N is 0, no pwmgens are enabled.  If N is greater than the number of
pwmgens available in the firmware, the board will fail to register.
.TP
\fBnum_stepgens\fR [optional, default: -1]
Only enable the first N stepgens.  If N is -1, all stepgens are enabled.
If N is 0, no stepgens are enabled.  If N is greater than the number of
stepgens available in the firmware, the board will fail to register.
.TP
\fBenable_raw\fR [optional]
If specified, this turns on a raw access mode, whereby a user can peek and
poke the firmware from HAL.  See Raw Mode below.
.RE
.SH encoder

Encoders have names like "hm2_<BoardType>.<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.

Each encoder uses three or four input IO pins, depending on how the
firmware was compiled.  Three-pin encoders use A, B, and Index (sometimes
also known as Z).  Four-pin encoders use A, B, Index, and Index-mask.

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 in position units (count / scale).
(Like CDI.)

(float out) velocity: Estimated encoder velocity in position units
per second.  (Like CDI.)

(bit in) reset: When this pin is TRUE, the count and position pins are
set to 0.  The driver does not reset this pin to FALSE after resetting
the count to 0, that is the user's job.  (Like CDI.)

(bit in/out) index-enable: When this pin is set to True, the count
(and therefore also position) are reset to zero on the next Index
(Phase-Z) pulse.  At the same time, index-enable is reset to zero to
indicate that the pulse has occurred.  (Like CDI.)

(s32 out) rawcount: Total number of encoder counts since the start,
not adjusted for index or reset.  (Like the software encoder component.)

Parameters:

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

(bit r/w) index-invert: If set to True, the rising edge of the Index
input pin triggers the Index event (if index-enable is True).  If set
to False, the falling edge triggers.

(bit r/w) index-mask: If set to True, the Index input pin only has an
effect if the Index-Mask input pin is True (or False, depending on the
index-mask-invert pin below).

(bit r/w) index-mask-invert: If set to True, Index-Mask must be False
for Index to have an effect.  If set to False, the Index-Mask pin must
be True.

(bit r/w) counter-mode: Set to False (the default) for Quadrature.
Set to True for Up/Down.

(bit r/w) filter: If set to True (the default), the quadrature counter
needs 15 clocks to register a change on any of the three input lines
(any pulse shorter than this is rejected as noise).  If set to False, the
quadrature counter needs only 3 clocks to register a change.  The encoder
sample clock runs at 33 MHz on the PCI AnyIO cards and 50 MHz on the 7i43.

(float r/w) vel-timeout: When the encoder is moving slower than one
pulse for each time that the driver reads the count from the FPGA (in
the hm2_read() function), the velocity is harder to estimate.  The driver
can wait several iterations for the next pulse to arrive, all the while
reporting the upper bound of the encoder velocity, which can be accurately
guessed.  This parameter specifies how long to wait for the next pulse,
before reporting the encoder stopped.  This parameter is in seconds.
.SH pwmgen

pwmgens have names like "hm2_<BoardType>.<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 pwmgen representation is modeled on the pwmgen software component
as far as possible.  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), 2
(Up on Out0 and Down on Out1), 3 (PDM mode, PDM on Out0 and Dir on Out1),
and 4 (Direction on Out0 and PWM on Out1, "for locked antiphase").

In addition to the per-instance HAL Parameters listed above, there are
a couple of HAL Parameters that affect all the pwmgen instances:

(u32 rw) pwm_frequency: This specifies the PWM frequency, in Hz, of all