Merge pull request #2391 from LinuxCNC/hal_parport-is-realtime

docs: rename hal_parport.1 to hal_parport.9, because it's a realtime …

Author: SebKuzminsky

README.realtime-nomenclature

@@ -0,0 +1,18 @@
+problematic stuff remaining:
+
+halcmd:
+    loadusr
+    unloadusr
+
+    "show comp" has a Type column that says either "RT" or "User"
+
+halcompile:
+    --userspace
+    option userspace
+    option userinit
+    user_mainloop()
+
+hal_lib:
+    ULAPI vs RTAPI
+
+hal_parport should move from man1 to man9

debian/linuxcnc.install.in

@@ -161,7 +161,6 @@ usr/share/man/man1/hal-histogram.1
 usr/share/man/man1/hal_input.1
 usr/share/man/man1/hal_manualtoolchange.1
 usr/share/man/man1/halmeter.1
-usr/share/man/man1/hal_parport.1
 usr/share/man/man1/halreport.1
 usr/share/man/man1/halrmt.1
 usr/share/man/man1/halrun.1

docs/man/man1/debuglevel.1

@@ -24,7 +24,7 @@
 .\"
 .TH DEBUGLEVEL "1"  "2020-08-26" "LinuxCNC Documentation" "The Enhanced Machine Controller"
 .SH NAME
-debuglevel \- sets the debug level for the userspace part of LinuxCNC
+debuglevel \- sets the debug level for the non-realtime part of LinuxCNC
 .SH SYNOPSIS
 .B debuglevel
 \fI\-ini\fR \fIINIFILE\fR

docs/man/man1/gs2_vfd.1

@@ -26,7 +26,7 @@
 .TH gs2_vfd "1" "January 1, 2009" "GS2 VFD" "LinuxCNC Documentation"
 
 .SH NAME
-\fBgs2_vfd\fR \- HAL userspace component for Automation Direct GS2 VFD's
+\fBgs2_vfd\fR \- HAL non-realtime component for Automation Direct GS2 VFD's
 
 .SH SYNOPSIS
 .B gs2_vfd

docs/man/man1/hal_manualtoolchange.1

@@ -1,4 +1,4 @@
-.\" Man page for hal_manualtoolchange userspace component.
+.\" Man page for hal_manualtoolchange non-realtime component.
 .\" Written 05 APR 2017 by Joe Hildreth (joeh@threerivershospital.com)
 .\"
 .\" This is free documentation; you can redistribute it and/or
@@ -20,13 +20,13 @@
 .\" License along with this manual; if not, write to the Free
 .\" Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
 .\" USA.
-.TH hal_manualtoolchange 1 "04 APR 2017" "LinuxCNC Documentation" "HAL Userspace Component"
+.TH hal_manualtoolchange 1 "04 APR 2017" "LinuxCNC Documentation" "HAL Non-realtime Component"
 .SH NAME
-hal_manualtoolchange \- HAL userspace component to enable manual tool changes.
+hal_manualtoolchange \- HAL non-realtime component to enable manual tool changes.
 .SH SYNOPSIS
 loadusr hal_manualtoolchange
 .SH DESCRIPTION
-hal_manualtoolchange is a LinuxCNC userspace component that allows users with machines lacking automatic tool changers to make manual tool changes.
+hal_manualtoolchange is a LinuxCNC non-realtime component that allows users with machines lacking automatic tool changers to make manual tool changes.
 In use when a M6 tool change is encountered, the motion component will stop the spindle and pause the program.
 The hal_manualtoolchange component will then receive a signal from the motion component causing it to display a tool change window prompting the user which tool number to load based on the last T\- number programmed.
 The dialog will stay active until the "continue" button is pressed.  When the "continue" button is pressed, hal_manualtoolchange will then signal the motion component that the tool change is complete thus allowing motion to turn the spindle back on and resume program execution.
@@ -50,10 +50,10 @@ Signifies that the tool change is complete.
 Pin to allow an external switch to signify that the tool change is complete.
 .SH USAGE
 Normal usage is to load the component in your HAL file and net the appropriate pins from the\fI motion\fR and\fI io\fR components.
-The following lines are typical in a HAL file when using the hal_manualtoolchange userspace component.
+The following lines are typical in a HAL file when using the hal_manualtoolchange non-realtime component.
 .TP
 .B loadusr \-W hal_manualtoolchange
-This will load the hal_manualtoolchange userspace component waiting for the component to be ready before continuing.
+This will load the hal_manualtoolchange non-realtime component waiting for the component to be ready before continuing.
 .TP
 .B net tool\-change iocontrol.0.tool\-change => hal_manualtoolchange.change
 When an M6 code is run, motion sets \fI iocontrol.0.tool\-change \fR to high indicating a tool change.

docs/man/man1/halcmd.1

@@ -101,7 +101,7 @@ Anything following '\fB#\fR' on a line is a comment.
 module called \fImodname\fR.  \fBhalcmd\fR looks for the module
 in a directory specified at compile time.
 
-In systems with realtime-support, \fBhalcmd\fR calls the
+In systems with kernel-based realtime support (e.g. RTAI), \fBhalcmd\fR calls the
 \fBlinuxcnc_module_helper\fR to load realtime modules.
 \fBlinuxcnc_module_helper\fR is a setuid program and is compiled with
 a whitelist of modules it is allowed to load.  This is currently
@@ -112,10 +112,11 @@ restrict which users can load these \fBLinuxCNC\fR-related kernel
 modules can do this by setting the permissions and group on
 \fBlinuxcnc_module_helper\fR appropriately.
 
-In systems without realtime-support \fBhalcmd\fR calls the
-\fBrtapi_app\fR which creates the simulated realtime environment
-if it did not yet exist, and then loads the requested component
-with a call to \fBdlopen(3)\fR.
+In systems with userspace-based realtime support (e.g. Preempt-RT) and in
+systems without realtime support \fBhalcmd\fR calls the \fBrtapi_app\fR
+which creates the realtime environment (simulated realtime, on systems
+with no userspace realtime support) if it did not yet exist, and then
+loads the requested component with a call to \fBdlopen(3)\fR.
 .TP
 \fBunloadrt\fR \fImodname\fR
 (\fIunload\fR \fIr\fReal\fIt\fRime module)  Unloads a realtime HAL
@@ -126,7 +127,7 @@ also works by execing \fBlinuxcnc_module_helper\fR or \fBrtapi_app\fR, just like
 .TP
 \fBloadusr\fR \fI[flags]\fR \fIunix-command\fR
 (\fIload\fR \fIUs\fRe\fIr\fRspace component) Executes the given
-\fIunix-command\fR, usually to load a userspace component.
+\fIunix-command\fR, usually to load a non-realtime component.
 \fI[flags]\fR may be one or more of:
 .RS
 .IP \(bu 4
@@ -142,21 +143,21 @@ name.
 .RE
 .TP
 \fBwaitusr\fR \fIname\fR
-(\fIwait\fR for \fIUs\fRe\fIr\fRspace component) Waits for user
-space component \fIname\fR to disconnect from HAL (usually on exit).
+(\fIwait\fR for \fIUs\fRe\fIr\fRspace component) Waits for non-realtime
+component \fIname\fR to disconnect from HAL (usually on exit).
 The component must already be loaded.  Useful near the end of a
 HAL file to wait until the user closes some user interface component
 before cleaning up and exiting.
 .TP
 \fBunloadusr\fR \fIcompname\fR
-(\fIunload\fR \fIUs\fRe\fIr\fRspace component)  Unloads a userspace
+(\fIunload\fR \fIUs\fRe\fIr\fRspace component)  Unloads a non-realtime
 component called \fIcompname\fR.  If \fIcompname\fR is "all", it will
-unload all userspace components.  \fBunloadusr\fR
-works by sending SIGTERM to all userspace components.
+unload all non-realtime components.  \fBunloadusr\fR
+works by sending SIGTERM to all non-realtime components.
 .TP
 \fBunload\fR \fIcompname\fR
-Unloads a userspace component or realtime module.  If \fIcompname\fR is "all",
-it will unload all userspace components and realtime modules.
+Unloads a non-realtime component or realtime module.  If \fIcompname\fR is "all",
+it will unload all non-realtime components and realtime modules.
 .TP
 \fBnewsig\fR \fIsigname\fR \fItype\fR
 (OBSOLETE - use \fBnet\fR instead) (\fInew\fR \fIsig\fRnal)

docs/man/man1/halcompile.1

@@ -61,7 +61,7 @@ to set the maximum of  personality items to 4:
 .IP \(bu 4
 Compile \fB.comp\fR and \fB.c\fR files into \fB.so\fR or \fB.ko\fR HAL realtime components (the \fB\-\-compile\fR flag)
 .IP \(bu 4
-Compile \fB.comp\fR and \fB.c\fR files into HAL userspace components (the \fB\-\-compile \-\-userspace\fR flag)
+Compile \fB.comp\fR and \fB.c\fR files into HAL non-realtime components (the \fB\-\-compile \-\-userspace\fR flag)
 .IP \(bu 4
 Preprocess \fB.comp\fR files into \fB.c\fR files (the \fB\-\-preprocess\fR flag)
 .IP \(bu 4
@@ -71,12 +71,12 @@ Display documentation from \fB.comp\fR files onscreen (the \fB\-\-view\-doc\fR f
 .IP \(bu 4
 Compile and install \fB.comp\fR and \fB.c\fR files into the proper directory for HAL realtime components (the \fB\-\-install\fR flag), which may require \fIsudo\fR to write to system directories.
 .IP \(bu 4
-Install \fB.c\fR and \fB.py\fR files into the proper directory for HAL userspace components (the \fB\-\-install \-\-userspace\fR flag), which may require \fIsudo\fR to write to system directories.
+Install \fB.c\fR and \fB.py\fR files into the proper directory for HAL non-realtime components (the \fB\-\-install \-\-userspace\fR flag), which may require \fIsudo\fR to write to system directories.
 .IP \(bu 4
 Extract documentation from \fB.comp\fR files into \fB.9\fR manpage files in the proper system directory (the \fB\-\-install\fR flag), which may require \fIsudo\fR to write to system directories.
 .IP \(bu 4
 Preprocess \fB.comp\fR files into \fB.c\fR files (the \fB\-\-preprocess\fR flag)
 .SH "SEE ALSO"
 \fIHalcompile HAL Component Generator\fR in the LinuxCNC documentation for a full description of the \fB.comp\fR syntax, along with examples
 
-\fBpydoc, HAL\fR and \fICreating Userspace Python Components\fR in the LinuxCNC documentation for documentation on the Python interface to HAL components
+\fBpydoc, HAL\fR and \fICreating Non-realtime Python Components\fR in the LinuxCNC documentation for documentation on the Python interface to HAL components

docs/man/man1/halsampler.1

@@ -39,7 +39,7 @@ are used together to sample HAL data in real time and store it in a file.
 is a realtime HAL component that exports HAL pins and creates a FIFO in shared memory.
 It then begins sampling data from the HAL and storing it to the FIFO.
 .B halsampler
-is a user space program that copies data from the FIFO to stdout, where it can
+is a non-realtime program that copies data from the FIFO to stdout, where it can
 be redirected to a file or piped to some other program.
 
 .SH OPTIONS

docs/man/man1/hy_vfd.1

@@ -25,7 +25,7 @@
 .TH hy_vfd "1" "April 25, 2015" "Huanyang VFD" "LinuxCNC Documentation"
 
 .SH NAME
-\fBhy_vfd\fR \- HAL userspace component for Huanyang VFDs
+\fBhy_vfd\fR \- HAL non-realtime component for Huanyang VFDs
 
 .SH SYNOPSIS
 .B hy_vfd

docs/man/man1/io.1

@@ -1,7 +1,7 @@
 .TH "IOCONTROL - IO" "1" "2007-08-25" "LinuxCNC Documentation" "HAL Component" 
 
 .SH NAME
-iocontrol \- interacts with HAL or G-code in userspace
+iocontrol \- interacts with HAL or G-code in non-realtime
 
 .SH SYNOPSIS
 
@@ -12,12 +12,12 @@ iocontrol \- interacts with HAL or G-code in userspace
 .SH DESCRIPTION
 
 I/O control handles I/O tasks like coolant, toolchange, E-stop and lube.
-The signals are turned on and off in userspace with G-code or in the case of E-stop in HAL. 
+The signals are turned on and off in non-realtime with G-code or in the case of E-stop in HAL. 
 
-The following pins are created by the userspace IO controller, usually found in $LINUXCNC_HOME/bin/io
+The following pins are created by the non-realtime IO controller, usually found in $LINUXCNC_HOME/bin/io
 .P
-iocontrol is a userspace process - if you have strict timing requirements
-or simply need more I/O, consider using the realtime synchronized I/oO
+iocontrol is a non-realtime process - if you have strict timing requirements
+or simply need more I/O, consider using the realtime synchronized I/O
 provided by \fBmotion\fR(9) instead.
 .P
 The INI file is searched for in the directory from which halcmd was run,