diff --git a/docs/man/man9/hal_pru_generic.9.asciidoc b/docs/man/man9/hal_pru_generic.9.asciidoc new file mode 100644 index 0000000000..84a198100b --- /dev/null +++ b/docs/man/man9/hal_pru_generic.9.asciidoc @@ -0,0 +1,332 @@ +--- +--- +:skip-front-matter: + += HAL_PRU_GENERIC(9) +:manmanual: HAL Components +:mansource: ../man/man9/hal_pru_generic.9.asciidoc +:man version : + +== NAME +hal_pru_generic - Machinekit HAL driver for the TI Programmable Realtime Unit (PRU). + +== SYNOPSIS +**loadrt hal_pru_generic [argument]...** + +Valid arguments are: + +* **prucode=**____ +* **pru=**__[0|1]__ +* **pru_period=**__N__ +* **halname=**____ +* **num_stepgens=**__N__ +* **num_pwmgens=**__N[,N]__ +* **num_encoders=**__N[,N]__ +* **disabled=**__[0|1]__] + +=== **prucode** [required] +Binary PRU firmware to load and run on the specified PRU. + +=== **pru** [optional, default: 1] +Which PRU (0 or 1) to use to run the code. This only matters if you are using +direct PRU I/O pins, in which case the PRU specified needs to be able to access +the pins used in the HAL configuration. + +=== **pru_period** [optional, default: 10000] +The task period time for the PRU, in nano-seconds. The default of 10000 nS +results in a PRU task frequency of 100 KHz. Smaller values here provide better +timing performance for pwm and step/dir generators, but the setting must be +large enough to allow all PRU tasks to complete. + +=== **halname** [optional, default: hal_pru_generic] +This identifier is used to prefix all created HAL pins and parameters. The +default is for legacy configurations and should otherwise be avoided. Recent +convention sets halname=hpg to provide for shorter HAL names. + +=== **num_stepgens** [optional, default: 0] +Create N stepgen instances. + +=== **num_pwmgens** [optional, default: 0] +Create pwmgen instance[s] with N channels. + +=== **num_encoders** [optional, default: 0] +Create N encoder instances. + +=== **disabled** [optional, default: 0] +If you set disabled=1, the driver will start with the PRU in the disabled +state, which can be useful for debugging. In this state, it is possible to +single-step through the PRU startup code after the driver is loaded. + +== DESCRIPTION +hal_pru_generic is a device driver that uses the PRU subsystem available +in Texas Instruments Sitara processors like on +the BeagleBone SBC to perform high-speed hard-real-time bit-twiddling to +generate step/direction and PWM outputs, avoiding the need to run a base +thread on the ARM core which has fairly poor latency. + +The driver is written for flexibility rather than raw speed (hence the +'generic' in the name). Various functions are supported by small bits +of PRU code (tasklets) that are linked into a function chain for the PRU +when the driver is first loaded. The minimum pru_period (and thus the +maximum step frequency) is determined by how long the PRU takes to execute +all configured tasklets, so simple configurations can run faster than +complex setups with lots of outputs. + +Currently, there are tasklets written for step/direction generation, PWM +output, and encoder inputs (using direct PRU input pins). + +== I/O PINS +The hal_pru_generic driver runs on a BeagleBone and has used a variety of +numbering schemes to identify I/O pins. All legacy pin numbering schemes +are still supported for backwards compatibility, but are not documented here +to avoid confusion (see fixup_pin() the code if you really need to know +how the previous schemes worked). The current numbering scheme is based on +the P8/P9 pin headers found on the BeagleBone. + +Pins are specified using a 4 digit value. The four digit value is composed +of three fields: + +direction digit - an optional prefix to indicate direct PRU I/O:: +* 0 or no prefix = standard GPIO pin +* 1 = PRU direct output +* 2 = PRU direct input +header digit:: +* 8 or 9 to indicate the header (P8 or P9) +pin number on P8 or P9 header:: +* 2 digits to represent the specific pin on the P8 or P9 header + +Examples: + + 0811 = GPIO on P8, pin 11 + 811 = GPIO on P8, pin 11 (identical to above) + 1811 = PRU direct output on P8, pin 11 + 2927 = PRU direct input on P9, pin 27 + +Note that not all P8/P9 pins can be used as I/O (some pins are dedicated +to specific signals or power) and not all GPIO pins can be used as PRU +direct input or output. + +WARNING: Direct PRU I/O pins are attatched to a specific PRU. If you choose to use +direct I/O pins, you are responsible for selecting a valid combination of +pin numbers and pru= such that the PRU code runs on a PRU core that can +access the configured pins. + +This driver does not setup any pin multiplexing or GPIO settings (pin +direction, pull-up/down). The user is required to configure these +settings prior to launching the driver, typically by using either a +device tree overlay or the cape-universal overlay and the config-pin +utility. + +== STEPGEN + +stepgens have names like "hpg.stepgen.____". +"Instance" is a two-digit number that corresponds to the stepgen +instance number. There are 'num_stepgens' instances, starting with 00. + +Each stepgen uses 2 IO pins, one for the step signal and one for the direction +signal. + +Each stepgen instance has the following pins and parameters: + +=== Pins: + +*position-cmd* (float input):: Target position of stepper motion, in +arbitrary position units. This pin is only used when the stepgen is in +position control mode (control-type=0). + +*velocity-cmd* (float input):: Target velocity of stepper motion, in +arbitrary position units per second. This pin is only used when the +stepgen is in velocity control mode (control-type=1). + +*position-fb* (float output):: Feedback position in arbitrary position +units. This is similar to "counts/position_scale", but has finer than +step resolution. + +*velocity-fb* (float output):: Feedback velocity in arbitrary position +units per second. + +*counts* (s32 output):: Feedback position in counts (number of steps). + +*enable* (bit input):: This pin enables the step generator instance. +When True, the stepgen instance works as expected. When False, no steps +are generated and velocity-fb goes immediately to 0. If the stepgen is +moving when enable goes false it stops immediately, without obeying the +maxaccel limit. + +*control-type* (bit input):: Switches between position control mode (0) +and velocity control mode (1). Defaults to position control (0). + +*position-scale* (float input):: Converts from counts to position units. +position = counts / position_scale + +*maxvel* (float input):: Maximum speed, in position units per second. If set +to 0, the driver will always use the maximum possible velocity based +on the current step timings and position-scale. The max velocity will +change if the step timings or position-scale changes. Defaults to 0. + +*maxaccel* (float input):: Maximum acceleration, in position units per second +per second. Defaults to 1.0. If set to 0, the driver will not limit its +acceleration at all - this requires that the position-cmd or velocity-cmd +pin is driven in a way that does not exceed the machine's capabilities. +This is probably what you want if you're going to be using the LinuxCNC +trajectory planner to jog or run G-code. + +*steplen* (u32 input):: Minimum duration of the step signal, in nanoseconds. + +*stepspace* (u32 input):: Minimum interval between step signals, in +nanoseconds. + +*dirsetup* (u32 input):: Minimum duration of stable Direction signal before +a step begins, in nanoseconds. + +*dirhold* (u32 input):: Minimum duration of stable Direction signal after a +step ends, in nanoseconds. + +*step_pin* (u32 input):: I/O pin to use for the step output + +*dir_pin* (u32 input):: I/O pin to use for the direction output + +*stepinvert* (bit input):: Inverts the step output (normally high with pulses going low) + +== PWMGEN +pwmgens have names like "hpg.pwmgen.____.out.____". +"Instance" is a two-digit number that corresponds to the pwmgen +instance number. Each channel number value passed to 'num_pwmgens' +creates a pwmgen instance, starting with 00. "Channel" is a two-digit +number that corresponds to a specific pwmgen channel in a pwmgen +instance, starting with 00. + +Each pwmgen instance has a single pwm_peroid, so all channels in that +instance have the same pwm frequency. To support multiple PWM +frequencies, it is possible to create more than one PWM instance, with +each instance having a configurable number of channels. To do so, pass +multiple values separated by commas to num_pwmgens, eg: num_pwmgens=2,1 +would create 2 pwmgen instances with a total of 3 channels: + +[indent=4] +==== +hpg.pwmgen.00.out.00 +hpg.pwmgen.00.out.01 +hpg.pwmgen.01.out.00 +==== + +Each pwmgen uses 1 IO pin + +=== Pins: + +*enable* (bit input):: If true, the pwmgen will output pulses. +If 'enable' is false, pwmgen will not output any signals. + +*value* (float input):: The current pwmgen command value, in arbitrary units. + +*scale* (float input):: 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, anything outside that range gets clipped. +The default scale is 1.0. + +*pin* (u32 input):: I/O pin to use for the pwm output ++ +In addition to the per-channel pins listed above, there is one +setting that affects all pwmgen channels in an instance: + +*pwm_period* (u32 input):: This specifies the PWM period, in nS. The default is 10,000,000 nS, or +100 Hz. The lower bound is determined by the pru_period and the desired +resolution. The longer the pwm_period, the more bits of resolution are +available but the lower the PWM frequency. + + +== ENCODER +Encoders have names like "hpg.encoder.____.out.____". +"Instance" is a two-digit number that corresponds to the encoder +instance number. Each channel number value passed to 'num_encoders' +creates an encoder instance, starting with 00. "Channel" is a two-digit +number that corresponds to a specific encoder channel in an encoder +instance, starting with 00. + +Currently, there is no particular reason to use multiple encoder +instances unless you happen to prefer the way the pins are exported to +HAL (perhaps to keep encoders for motion separate from encoders for a +jog wheel). Support for multiple instances is intended to allow for +different settings for high-speed encoder instances using direct PRU +input pins and lower-speed instances that access standard GPIO pins. + +Currently all encoders **MUST** use direct PRU input pins. + +Each encoder uses up to three PRU direct input pins, depending on the +counting mode. + +WARNING: The encoder uses different pin numbering than the rest of the +hal_pru_generic driver. The pin number values for (A|B|index)-pin +should be the PRU dedicated input pin number, a value in the range of +0-16 inclusive. It is the user's responsibility to insure the physical +I/O pins used are available as direct PRU input pins on the PRU used +to run the hal_pru_generic PRU binary. Unused pins should be assigned +to a PRU input that will not change value (the 'unconnected' inputs +17-29 work well for this). + +Each encoder instance has the following pins: + +=== Pins: + +*count* (s32 output):: Number of encoder counts since the previous reset. +*position* (float output):: Encoder position in position units (count / scale). +*velocity* (float output):: Estimated encoder velocity in position units per second. +*reset* (bit input):: Currently unsupported, included for compatability with hm2. +*index-enable* (bit in/out):: Currently unsupported, included for compatability with hm2. +*rawcount* (s32 output):: Total number of encoder counts since the start, not adjusted for index or reset. +*scale* (float input):: Converts from 'count' units to 'position' units. +*A-pin* (u32 input):: PRU direct input pin to use for the A signal +*A-invert* (bit input):: If True, inverts the polarity of the A signal +*B-pin* (u32 input):: PRU direct input pin to use for the B signal +*B-invert* (bit input):: If True, inverts the polarity of the B signal +*index-pin* (u32 input):: PRU direct input pin to use for the index (Z) signal +*index-invert* (bit input):: If 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. +*index-mask* (bit input):: Currently unsupported, included for compatability with hm2. +*index-mask-invert* (bit input):: Currently unsupported, included for compatability with hm2. +*counter-mode* (u32 input):: ++ +[cols="2*", options="header"] +|=== +|Value +|Function + +|0 +|Quadrature mode (default) + +|1 +|Step/Dir mode (A = Step, B = Up/Down) + +|2 +|Up counter (counts rising edges on A, B is ignored) + +|3 +|Quadrature x1 mode (matches HAL software encoder x1 mode) + +|All other values +|reserved +|=== + +*filter* (bit input):: Currently unsupported, included for compatability with hm2. + +*vel-timeout* (float input):: When the encoder is moving slower than one +pulse for each time that the driver reads the count from the PRU (in +the capture-position() 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. + + +== FUNCTIONS +*.capture-position*:: This reads the encoder counters and stepgen feedbacks from the PRU. + +*.update*:: This updates the PWM duty cycles and stepgen rates on the PRU. Any +changes to configuration pins such as stepgen timing, inversions, +etc, are also effected by this function. + + +== SEE ALSO + +== LICENSE +GPL