From f9cecb511142dd3b8c0527c09403f5b8437e1f7f Mon Sep 17 00:00:00 2001 From: Hans Unzner Date: Fri, 16 Aug 2024 14:04:33 +0200 Subject: [PATCH 1/5] Use asciidoctor to generate man pages from asciidoc sources --- docs/src/Submakefile | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/src/Submakefile b/docs/src/Submakefile index 011f96cc140..25593964e62 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -999,10 +999,9 @@ TARGETS += manpages GENERATED_MANPAGES += $(patsubst $(DOC_DIR)/src/man/%.adoc, $(DOC_DIR)/man/%, $(wildcard $(DOC_DIR)/src/man/man?/*.adoc)) $(DOC_DIR)/man/%: $(DOC_DIR)/src/man/%.adoc @mkdir -p `dirname $@` - a2x -v --doctype manpage \ - --format manpage \ - --destination-dir `dirname $@` \ - --xsltproc-opts="--nonet" \ - -a mansource=LinuxCNC \ - -a manmanual='LinuxCNC Documentation' \ + asciidoctor -b manpage \ + -a doctype=manpage \ + -a doctitle="$(basename $(@F)) ($(patsubst .%,%,$(suffix $(@F))))" \ + -a manname=$(basename $(@F)) \ + --destination-dir $(@D) \ $< From 6b63e01c8f43906b46d63786ee04a77dcf630c3e Mon Sep 17 00:00:00 2001 From: Hans Unzner Date: Mon, 19 Aug 2024 22:20:20 +0200 Subject: [PATCH 2/5] removed no longer needed entry in makefile for spanish man pages --- docs/src/Submakefile | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/src/Submakefile b/docs/src/Submakefile index 25593964e62..22471996ba8 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -17,9 +17,6 @@ MAN_SRCS = $(sort \ $(wildcard $(DOC_DIR)/man/man1/*.1) \ $(wildcard $(DOC_DIR)/man/man3/*.3*) \ $(wildcard $(DOC_DIR)/man/man9/*.9) \ - $(wildcard $(DOC_DIR)/man/es/man1/*.1) \ - $(wildcard $(DOC_DIR)/man/es/man3/*.3*) \ - $(wildcard $(DOC_DIR)/man/es/man9/*.9) \ $(GENERATED_MANPAGES)) ../docs/man/man1/linuxcnc.1: $(DOC_SRCDIR)/man/man1/linuxcnc.1.in config.status From a84c689128e6a18396e701ee8b2fe34fe6d5ee18 Mon Sep 17 00:00:00 2001 From: Hans Unzner Date: Sat, 24 Aug 2024 09:46:58 +0200 Subject: [PATCH 3/5] Try to install asciidoctor automatically via depends --- debian/control.main-pkg.in | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/debian/control.main-pkg.in b/debian/control.main-pkg.in index 6eecc4db12a..2f0c27d8613 100644 --- a/debian/control.main-pkg.in +++ b/debian/control.main-pkg.in @@ -30,7 +30,8 @@ Depends: tclx, @QTVCP_DEPENDS@, procps, psmisc, - udev + udev, + asciidoctor Recommends: linuxcnc-doc-en | linuxcnc-doc, librsvg2-dev, From 8ee1c910230fc598ed4ffde7be85c53b12204a28 Mon Sep 17 00:00:00 2001 From: Hans Unzner Date: Sun, 1 Sep 2024 21:14:12 +0200 Subject: [PATCH 4/5] Remove mention of millturngui in milltun to avoid include --- docs/src/man/man1/millturn.1.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/man/man1/millturn.1.adoc b/docs/src/man/man1/millturn.1.adoc index c14d4f2702a..d3890247f8f 100644 --- a/docs/src/man/man1/millturn.1.adoc +++ b/docs/src/man/man1/millturn.1.adoc @@ -2,7 +2,7 @@ == NAME -millturn, millturngui - Vismach Virtual Machine GUI +millturn - Vismach Virtual Machine GUI == DESCRIPTION From 305997be0f47a094c2ce0e69c7535adaf7368adc Mon Sep 17 00:00:00 2001 From: Hans Unzner Date: Mon, 2 Sep 2024 13:05:22 +0200 Subject: [PATCH 5/5] Started to create an adoc man page for eachman page --- docs/man/.gitignore | 17 ++-- docs/src/man/man3/EXPORT_FUNCTION.3rtapi.adoc | 9 +++ docs/src/man/man3/MODULE_AUTHOR.3rtapi.adoc | 7 ++ .../man/man3/MODULE_DESCRIPTION.3rtapi.adoc | 7 ++ docs/src/man/man3/MODULE_LICENSE.3rtapi.adoc | 7 ++ .../man/man3/RTAPI_MP_ARRAY_INT.3rtapi.adoc | 9 +++ .../man/man3/RTAPI_MP_ARRAY_LONG.3rtapi.adoc | 9 +++ .../man3/RTAPI_MP_ARRAY_STRING.3rtapi.adoc | 9 +++ docs/src/man/man3/RTAPI_MP_INT.3rtapi.adoc | 9 +++ docs/src/man/man3/RTAPI_MP_LONG.3rtapi.adoc | 9 +++ docs/src/man/man3/RTAPI_MP_STRING.3rtapi.adoc | 9 +++ .../man/man3/hal_add_funct_to_thread.3.adoc | 2 +- docs/src/man/man3/hal_bit_t.3.adoc | 9 +++ docs/src/man/man3/hal_bool.3.adoc | 9 +++ .../man/man3/hal_del_funct_from_thread.3.adoc | 51 ++++++++++++ docs/src/man/man3/hal_export_funct.3.adoc | 2 +- docs/src/man/man3/hal_export_functf.3.adoc | 27 +++++++ docs/src/man/man3/hal_get_lock.3.adoc | 23 ++++++ docs/src/man/man3/hal_port_t.3.adoc | 9 +++ docs/src/man/man3/hal_s32_t.3.adoc | 9 +++ docs/src/man/man3/hal_set_lock.3.adoc | 7 +- docs/src/man/man3/hal_type_t.3.adoc | 69 +---------------- docs/src/man/man3/hal_type_t.3.body | 67 ++++++++++++++++ docs/src/man/man3/hal_u32_t.3.adoc | 9 +++ docs/src/man/man3/ireal_t.3.adoc | 9 +++ docs/src/man/man3/real_t.3.adoc | 9 +++ docs/src/man/man3/rtapi_module_param.3.adoc | 77 +------------------ docs/src/man/man3/rtapi_module_param.3.body | 75 ++++++++++++++++++ 28 files changed, 408 insertions(+), 156 deletions(-) create mode 100644 docs/src/man/man3/EXPORT_FUNCTION.3rtapi.adoc create mode 100644 docs/src/man/man3/MODULE_AUTHOR.3rtapi.adoc create mode 100644 docs/src/man/man3/MODULE_DESCRIPTION.3rtapi.adoc create mode 100644 docs/src/man/man3/MODULE_LICENSE.3rtapi.adoc create mode 100644 docs/src/man/man3/RTAPI_MP_ARRAY_INT.3rtapi.adoc create mode 100644 docs/src/man/man3/RTAPI_MP_ARRAY_LONG.3rtapi.adoc create mode 100644 docs/src/man/man3/RTAPI_MP_ARRAY_STRING.3rtapi.adoc create mode 100644 docs/src/man/man3/RTAPI_MP_INT.3rtapi.adoc create mode 100644 docs/src/man/man3/RTAPI_MP_LONG.3rtapi.adoc create mode 100644 docs/src/man/man3/RTAPI_MP_STRING.3rtapi.adoc create mode 100644 docs/src/man/man3/hal_bit_t.3.adoc create mode 100644 docs/src/man/man3/hal_bool.3.adoc create mode 100644 docs/src/man/man3/hal_del_funct_from_thread.3.adoc create mode 100644 docs/src/man/man3/hal_export_functf.3.adoc create mode 100644 docs/src/man/man3/hal_get_lock.3.adoc create mode 100644 docs/src/man/man3/hal_port_t.3.adoc create mode 100644 docs/src/man/man3/hal_s32_t.3.adoc create mode 100644 docs/src/man/man3/hal_type_t.3.body create mode 100644 docs/src/man/man3/hal_u32_t.3.adoc create mode 100644 docs/src/man/man3/ireal_t.3.adoc create mode 100644 docs/src/man/man3/real_t.3.adoc create mode 100644 docs/src/man/man3/rtapi_module_param.3.body diff --git a/docs/man/.gitignore b/docs/man/.gitignore index 808a40eaf66..635053ec75a 100644 --- a/docs/man/.gitignore +++ b/docs/man/.gitignore @@ -120,7 +120,7 @@ man1/xyzab-tdr-gui.1 man1/xyzac-trt-gui.1 man1/xyzbc-trt-gui.1 -man3/EXPORT_FUNCTION.3 +man3/EXPORT_FUNCTION.3rtapi man3/hal_add_funct_to_thread.3 man3/hal_bit_t.3 man3/hal_bool.3 @@ -134,6 +134,9 @@ man3/hal_get_lock.3 man3/hal_init.3hal man3/hal_link.3 man3/hal_malloc.3hal +man3/MODULE_AUTHOR.3rtapi +man3/MODULE_DESCRIPTION.3rtapi +man3/MODULE_LICENSE.3rtapi man3/hal_param_alias.3hal man3/hal_param_bit_new.3 man3/hal_param_bit_newf.3 @@ -211,12 +214,12 @@ man3/rtapi_io.3rtapi man3/rtapi_is.3rtapi man3/rtapi_list.3rtapi man3/rtapi_module_param.3 -man3/RTAPI_MP_ARRAY_INT.3 -man3/RTAPI_MP_ARRAY_LONG.3 -man3/RTAPI_MP_ARRAY_STRING.3 -man3/RTAPI_MP_INT.3 -man3/RTAPI_MP_LONG.3 -man3/RTAPI_MP_STRING.3 +man3/RTAPI_MP_ARRAY_INT.3rtapi +man3/RTAPI_MP_ARRAY_LONG.3rtapi +man3/RTAPI_MP_ARRAY_STRING.3rtapi +man3/RTAPI_MP_INT.3rtapi +man3/RTAPI_MP_LONG.3rtapi +man3/RTAPI_MP_STRING.3rtapi man3/rtapi_mutex.3rtapi man3/rtapi_open_as_root.3rtapi man3/rtapi_outb.3 diff --git a/docs/src/man/man3/EXPORT_FUNCTION.3rtapi.adoc b/docs/src/man/man3/EXPORT_FUNCTION.3rtapi.adoc new file mode 100644 index 00000000000..844bf28f817 --- /dev/null +++ b/docs/src/man/man3/EXPORT_FUNCTION.3rtapi.adoc @@ -0,0 +1,9 @@ +:manvolnum: 3 + += EXPORT_FUNCTION(3rtapi) + +== NAME + +EXPORT_FUNCTION - Specifying module parameters + +include::rtapi_module_param.3.body[] \ No newline at end of file diff --git a/docs/src/man/man3/MODULE_AUTHOR.3rtapi.adoc b/docs/src/man/man3/MODULE_AUTHOR.3rtapi.adoc new file mode 100644 index 00000000000..87c34fe81a6 --- /dev/null +++ b/docs/src/man/man3/MODULE_AUTHOR.3rtapi.adoc @@ -0,0 +1,7 @@ += MODULE_AUTOR(3rtapi) + +== NAME + +MODULE_AUTHOR - Specifying module parameters + +include::rtapi_module_param.3.body[] \ No newline at end of file diff --git a/docs/src/man/man3/MODULE_DESCRIPTION.3rtapi.adoc b/docs/src/man/man3/MODULE_DESCRIPTION.3rtapi.adoc new file mode 100644 index 00000000000..5925fd7b4c9 --- /dev/null +++ b/docs/src/man/man3/MODULE_DESCRIPTION.3rtapi.adoc @@ -0,0 +1,7 @@ += MODULE_DESCRIPTION(3rtapi) + +== NAME + +MODULE_DESCRIPTION - Specifying module parameters + +include::rtapi_module_param.3.adoc[] \ No newline at end of file diff --git a/docs/src/man/man3/MODULE_LICENSE.3rtapi.adoc b/docs/src/man/man3/MODULE_LICENSE.3rtapi.adoc new file mode 100644 index 00000000000..300a72cbc82 --- /dev/null +++ b/docs/src/man/man3/MODULE_LICENSE.3rtapi.adoc @@ -0,0 +1,7 @@ += MODULE_LICENSE(3rtapi) + +== NAME + +MODULE_LICENSE - Specifying module parameters + +include::rtapi_module_param.3.adoc[] \ No newline at end of file diff --git a/docs/src/man/man3/RTAPI_MP_ARRAY_INT.3rtapi.adoc b/docs/src/man/man3/RTAPI_MP_ARRAY_INT.3rtapi.adoc new file mode 100644 index 00000000000..12e5403ce69 --- /dev/null +++ b/docs/src/man/man3/RTAPI_MP_ARRAY_INT.3rtapi.adoc @@ -0,0 +1,9 @@ +:manvolnum: 3 + += RTAPI_MP_ARRAY_INT(3rtapi) + +== NAME + +RTAPI_MP_ARRAY_INT - Specifying module parameters + +include::rtapi_module_param.3.body[] \ No newline at end of file diff --git a/docs/src/man/man3/RTAPI_MP_ARRAY_LONG.3rtapi.adoc b/docs/src/man/man3/RTAPI_MP_ARRAY_LONG.3rtapi.adoc new file mode 100644 index 00000000000..58f49c2823a --- /dev/null +++ b/docs/src/man/man3/RTAPI_MP_ARRAY_LONG.3rtapi.adoc @@ -0,0 +1,9 @@ +:manvolnum: 3 + += RTAPI_MP_ARRAY_LONG(3rtapi) + +== NAME + +RTAPI_MP_ARRAY_LONG - Specifying module parameters + +include::rtapi_module_param.3.body[] \ No newline at end of file diff --git a/docs/src/man/man3/RTAPI_MP_ARRAY_STRING.3rtapi.adoc b/docs/src/man/man3/RTAPI_MP_ARRAY_STRING.3rtapi.adoc new file mode 100644 index 00000000000..921e522921b --- /dev/null +++ b/docs/src/man/man3/RTAPI_MP_ARRAY_STRING.3rtapi.adoc @@ -0,0 +1,9 @@ +:manvolnum: 3 + += RTAPI_MP_ARRAY_STRING(3rtapi) + +== NAME + +RTAPI_MP_ARRAY_STRING - Specifying module parameters + +include::rtapi_module_param.3.body[] \ No newline at end of file diff --git a/docs/src/man/man3/RTAPI_MP_INT.3rtapi.adoc b/docs/src/man/man3/RTAPI_MP_INT.3rtapi.adoc new file mode 100644 index 00000000000..f27c438114f --- /dev/null +++ b/docs/src/man/man3/RTAPI_MP_INT.3rtapi.adoc @@ -0,0 +1,9 @@ +:manvolnum: 3 + += RTAPI_MP_INT(3rtapi) + +== NAME + +RTAPI_MP_INT - Specifying module parameters + +include::rtapi_module_param.3.body[] \ No newline at end of file diff --git a/docs/src/man/man3/RTAPI_MP_LONG.3rtapi.adoc b/docs/src/man/man3/RTAPI_MP_LONG.3rtapi.adoc new file mode 100644 index 00000000000..502fd6ec750 --- /dev/null +++ b/docs/src/man/man3/RTAPI_MP_LONG.3rtapi.adoc @@ -0,0 +1,9 @@ +:manvolnum: 3 + += RTAPI_MP_LONG(3rtapi) + +== NAME + +RTAPI_MP_LONG - Specifying module parameters + +include::rtapi_module_param.3.body[] \ No newline at end of file diff --git a/docs/src/man/man3/RTAPI_MP_STRING.3rtapi.adoc b/docs/src/man/man3/RTAPI_MP_STRING.3rtapi.adoc new file mode 100644 index 00000000000..e073d75eb22 --- /dev/null +++ b/docs/src/man/man3/RTAPI_MP_STRING.3rtapi.adoc @@ -0,0 +1,9 @@ +:manvolnum: 3 + += RTAPI_MP_STRING(3rtapi) + +== NAME + +RTAPI_MP_STRING - Specifying module parameters + +include::rtapi_module_param.3.body[] \ No newline at end of file diff --git a/docs/src/man/man3/hal_add_funct_to_thread.3.adoc b/docs/src/man/man3/hal_add_funct_to_thread.3.adoc index f4506c62b7b..c033e72e151 100644 --- a/docs/src/man/man3/hal_add_funct_to_thread.3.adoc +++ b/docs/src/man/man3/hal_add_funct_to_thread.3.adoc @@ -4,7 +4,7 @@ == NAME -hal_add_funct_to_thread, hal_del_funct_from_thread - cause a function to be executed at regular intervals +hal_add_funct_to_thread - cause a function to be executed at regular intervals == SYNTAX diff --git a/docs/src/man/man3/hal_bit_t.3.adoc b/docs/src/man/man3/hal_bit_t.3.adoc new file mode 100644 index 00000000000..7fb5f37afee --- /dev/null +++ b/docs/src/man/man3/hal_bit_t.3.adoc @@ -0,0 +1,9 @@ +:manvolnum: 3 + += hal_bit_t(3hal) + +== NAME + +hal_bit_t - typedefs for HAL datatypes + +include::hal_type_t.3.body[] diff --git a/docs/src/man/man3/hal_bool.3.adoc b/docs/src/man/man3/hal_bool.3.adoc new file mode 100644 index 00000000000..e7e96807fe2 --- /dev/null +++ b/docs/src/man/man3/hal_bool.3.adoc @@ -0,0 +1,9 @@ +:manvolnum: 3 + += hal_bool(3hal) + +== NAME + +hal_bool - typedefs for HAL datatypes + +include::hal_type_t.3.body[] \ No newline at end of file diff --git a/docs/src/man/man3/hal_del_funct_from_thread.3.adoc b/docs/src/man/man3/hal_del_funct_from_thread.3.adoc new file mode 100644 index 00000000000..164bc574348 --- /dev/null +++ b/docs/src/man/man3/hal_del_funct_from_thread.3.adoc @@ -0,0 +1,51 @@ +:manvolnum: 3 + += hal_del_funct_from_thread(3hal) + +== NAME + +hal_del_funct_from_thread - cause a function to be executed at regular intervals + +== SYNTAX + +int hal_add_funct_to_thread(const char *_funct_name_, const char +*_thread_name_, int position) + +int hal_del_funct_from_thread(const char *_funct_name_, const char +*_thread_name_) + +== ARGUMENTS + +funct_name:: + The name of the function. +thread_name:: + The name of the thread. +position:: + The desired location within the thread. This determines when the + function will run, in relation to other functions in the thread. A + positive number indicates the desired location as measured from the + beginning of the thread, and a negative is measured from the end. So + +1 means this function will become the first one to run, +5 means it + will be the fifth one to run, -2 means it will be next to last, and -1 + means it will be last. Zero is illegal. + +== DESCRIPTION + +*hal_add_funct_to_thread* adds a function exported by a realtime HAL +component to a realtime thread. This determines how often and in what +order functions are executed. + +*hal_del_funct_from_thread* removes a function from a thread. + +== RETURN VALUE + +Returns a HAL status code. + +== REALTIME CONSIDERATIONS + +Call only from realtime init code, not from other realtime or +non-realtime code. + +== SEE ALSO + +hal_thread_new(3hal), hal_export_funct(3hal) diff --git a/docs/src/man/man3/hal_export_funct.3.adoc b/docs/src/man/man3/hal_export_funct.3.adoc index 5cceee8ab01..4f1f33be2e9 100644 --- a/docs/src/man/man3/hal_export_funct.3.adoc +++ b/docs/src/man/man3/hal_export_funct.3.adoc @@ -4,7 +4,7 @@ == NAME -hal_export_funct, hal_export_functf - create a realtime function callable from a thread +hal_export_funct - create a realtime function callable from a thread == SYNTAX diff --git a/docs/src/man/man3/hal_export_functf.3.adoc b/docs/src/man/man3/hal_export_functf.3.adoc new file mode 100644 index 00000000000..9b03fcb994a --- /dev/null +++ b/docs/src/man/man3/hal_export_functf.3.adoc @@ -0,0 +1,27 @@ +:manvolnum: 3 + += hal_export_functf(3hal) + +== NAME + +hal_export_functf - create a realtime function callable from a thread + +== SYNTAX + +int hal_export_funct(const char *name, void (*funct) (void *, long), + void *arg, int uses_fp, int reentrant, int comp_id); + +== DESCRIPTION + +*hal_export_functf* is similar to hal_export_funct except that it also does +printf-style formatting to compute the function name. +If successful, it returns 0. +On failure it returns a negative error code. + +== RETURN VALUE + +Returns a HAL status code. + +== SEE ALSO + +hal_export_funct(3hal) diff --git a/docs/src/man/man3/hal_get_lock.3.adoc b/docs/src/man/man3/hal_get_lock.3.adoc new file mode 100644 index 00000000000..090ecc4c053 --- /dev/null +++ b/docs/src/man/man3/hal_get_lock.3.adoc @@ -0,0 +1,23 @@ +:manvolnum: 3 + += hal_get_lock(3hal) + +== NAME + +hal_get_lock - Get the HAL lock level + +== SYNTAX + +int hal_get_lock() + +== ARGUMENTS + +lock_type:: + The desired lock type, which may be a bitwise combination of: + *HAL_LOCK_LOAD*, *HAL_LOCK_CONFIG*, *HAL_LOCK_PARAMS*, or + *HAL_LOCK_PARAMS*. *HAL_LOCK_NONE* or 0 locks nothing, and + *HAL_LOCK_ALL locks everything.* + +== RETURN VALUE + +*hal_get_lock* returns the current HAL lock level or a HAL status code. diff --git a/docs/src/man/man3/hal_port_t.3.adoc b/docs/src/man/man3/hal_port_t.3.adoc new file mode 100644 index 00000000000..58c7f95c8d7 --- /dev/null +++ b/docs/src/man/man3/hal_port_t.3.adoc @@ -0,0 +1,9 @@ +:manvolnum: 3 + += hal_port_t(3hal) + +== NAME + +hal_port_t - typedefs for HAL datatypes + +include::hal_type_t.3.body[] \ No newline at end of file diff --git a/docs/src/man/man3/hal_s32_t.3.adoc b/docs/src/man/man3/hal_s32_t.3.adoc new file mode 100644 index 00000000000..b43b5622076 --- /dev/null +++ b/docs/src/man/man3/hal_s32_t.3.adoc @@ -0,0 +1,9 @@ +:manvolnum: 3 + += hal_s32_t(3hal) + +== NAME + +hal_s32_t - typedefs for HAL datatypes + +include::hal_type_t.3.body[] \ No newline at end of file diff --git a/docs/src/man/man3/hal_set_lock.3.adoc b/docs/src/man/man3/hal_set_lock.3.adoc index 3b41b8c0fcf..0d352c7b32d 100644 --- a/docs/src/man/man3/hal_set_lock.3.adoc +++ b/docs/src/man/man3/hal_set_lock.3.adoc @@ -4,14 +4,12 @@ == NAME -hal_set_lock, hal_get_lock - Set or get the HAL lock level +hal_set_lock - Set the HAL lock level == SYNTAX int hal_set_lock(unsigned char _lock_type_) -int hal_get_lock() - == ARGUMENTS lock_type:: @@ -22,5 +20,4 @@ lock_type:: == RETURN VALUE -*hal_set_lock* Returns a HAL status code. *hal_get_lock* returns the -current HAL lock level or a HAL status code. +*hal_set_lock* Returns a HAL status code. \ No newline at end of file diff --git a/docs/src/man/man3/hal_type_t.3.adoc b/docs/src/man/man3/hal_type_t.3.adoc index c3c72b37a09..02f89c14b9d 100644 --- a/docs/src/man/man3/hal_type_t.3.adoc +++ b/docs/src/man/man3/hal_type_t.3.adoc @@ -4,71 +4,6 @@ == NAME -hal_type_t, hal_bool, hal_bit_t, hal_s32_t, hal_u32_t, hal_port_t, hal_float_t, real_t, ireal_t - typedefs for HAL datatypes +hal_type_t - typedefs for HAL datatypes -== DESCRIPTION - -typedef ... *hal_bool;*:: - A type which may have a value of 0 or nonzero. -typedef ... *hal_bit_t;*:: - A volatile type which may have a value of 0 or nonzero. -typedef ... *hal_s32_t*;:: - A volatile type which may have a value from -2147483648 to 2147483647. -typedef ... *hal_u32_t*;:: - A volatile type which may have a value from 0 to 4294967295. -typedef ... *hal_port_t*;:: - A volatile handle to a port object. Used with hal_port* functions. -typedef ... *hal_float_t*;:: - A volatile floating-point type, which typically has the same precision - and range as the C type *double*. -typedef ... *real_t*;:: - A nonvolatile floating-point type with at least as much precision as - *hal_float_t*. -typedef ... *ireal_t*;:: - A nonvolatile unsigned integral type the same size as *hal_float_t*. -typedef enum *hal_type_t*;:: - + - *HAL_BIT*;; - Corresponds to the type *hal_bit_t*. - *HAL_FLOAT*;; - Corresponds to the type *hal_float_t*. - *HAL_S32*;; - Corresponds to the type *hal_s32_t*. - *HAL_U32*;; - Corresponds to the type *hal_u32_t*. - -== NOTES - -*hal_bit_t* is typically a typedef to an integer type whose range is -larger than just 0 and 1. When testing the value of a *hal_bit_t*, never -compare it to 1. Prefer one of the following: - -____ -* if(b) -* if(b != 0) -____ - -It is often useful to refer to a type that can represent all the values -as a HAL type, but without the volatile qualifier. The following types -correspond with the HAL types: - -____ -hal_bit_t:: - int -hal_s32_t:: - __s32 -hal_u32_t:: - __u32 -hal_float_t:: - hal_real_t -hal_port_t:: - int -____ - -Take care not to use the types *s32* and *u32*. These will compile in -kernel modules but not in userspace, and not for realtime components -when using uspace realtime. - -== SEE ALSO - -hal_pin_new(3hal), hal_param_new(3hal) +include::hal_type_t.3.body[] \ No newline at end of file diff --git a/docs/src/man/man3/hal_type_t.3.body b/docs/src/man/man3/hal_type_t.3.body new file mode 100644 index 00000000000..ba1b616e180 --- /dev/null +++ b/docs/src/man/man3/hal_type_t.3.body @@ -0,0 +1,67 @@ + +== DESCRIPTION + +typedef ... *hal_bool;*:: + A type which may have a value of 0 or nonzero. +typedef ... *hal_bit_t;*:: + A volatile type which may have a value of 0 or nonzero. +typedef ... *hal_s32_t*;:: + A volatile type which may have a value from -2147483648 to 2147483647. +typedef ... *hal_u32_t*;:: + A volatile type which may have a value from 0 to 4294967295. +typedef ... *hal_port_t*;:: + A volatile handle to a port object. Used with hal_port* functions. +typedef ... *hal_float_t*;:: + A volatile floating-point type, which typically has the same precision + and range as the C type *double*. +typedef ... *real_t*;:: + A nonvolatile floating-point type with at least as much precision as + *hal_float_t*. +typedef ... *ireal_t*;:: + A nonvolatile unsigned integral type the same size as *hal_float_t*. +typedef enum *hal_type_t*;:: + + + *HAL_BIT*;; + Corresponds to the type *hal_bit_t*. + *HAL_FLOAT*;; + Corresponds to the type *hal_float_t*. + *HAL_S32*;; + Corresponds to the type *hal_s32_t*. + *HAL_U32*;; + Corresponds to the type *hal_u32_t*. + +== NOTES + +*hal_bit_t* is typically a typedef to an integer type whose range is +larger than just 0 and 1. When testing the value of a *hal_bit_t*, never +compare it to 1. Prefer one of the following: + +____ +* if(b) +* if(b != 0) +____ + +It is often useful to refer to a type that can represent all the values +as a HAL type, but without the volatile qualifier. The following types +correspond with the HAL types: + +____ +hal_bit_t:: + int +hal_s32_t:: + __s32 +hal_u32_t:: + __u32 +hal_float_t:: + hal_real_t +hal_port_t:: + int +____ + +Take care not to use the types *s32* and *u32*. These will compile in +kernel modules but not in userspace, and not for realtime components +when using uspace realtime. + +== SEE ALSO + +hal_pin_new(3hal), hal_param_new(3hal) diff --git a/docs/src/man/man3/hal_u32_t.3.adoc b/docs/src/man/man3/hal_u32_t.3.adoc new file mode 100644 index 00000000000..90aa08835fa --- /dev/null +++ b/docs/src/man/man3/hal_u32_t.3.adoc @@ -0,0 +1,9 @@ +:manvolnum: 3 + += hal_u32_t(3hal) + +== NAME + +hal_u32_t - typedefs for HAL datatypes + +include::hal_type_t.3.body[] \ No newline at end of file diff --git a/docs/src/man/man3/ireal_t.3.adoc b/docs/src/man/man3/ireal_t.3.adoc new file mode 100644 index 00000000000..ca1159bc368 --- /dev/null +++ b/docs/src/man/man3/ireal_t.3.adoc @@ -0,0 +1,9 @@ +:manvolnum: 3 + += ireal_t(3hal) + +== NAME + +ireal_t - typedefs for HAL datatypes + +include::hal_type_t.3.body[] \ No newline at end of file diff --git a/docs/src/man/man3/real_t.3.adoc b/docs/src/man/man3/real_t.3.adoc new file mode 100644 index 00000000000..9522b880ca3 --- /dev/null +++ b/docs/src/man/man3/real_t.3.adoc @@ -0,0 +1,9 @@ +:manvolnum: 3 + += real_t(3hal) + +== NAME + +real_t - typedefs for HAL datatypes + +include::hal_type_t.3.body[] \ No newline at end of file diff --git a/docs/src/man/man3/rtapi_module_param.3.adoc b/docs/src/man/man3/rtapi_module_param.3.adoc index d6f30413fcf..c25e810eecb 100644 --- a/docs/src/man/man3/rtapi_module_param.3.adoc +++ b/docs/src/man/man3/rtapi_module_param.3.adoc @@ -4,79 +4,6 @@ == NAME -rtapi_module_param, EXPORT_FUNCTION, RTAPI_MP_INT, RTAPI_MP_LONG, -RTAPI_MP_STRING, RTAPI_MP_ARRAY_INT, RTAPI_MP_ARRAY_LONG, -RTAPI_MP_ARRAY_STRING, MODULE_LICENSE, MODULE_AUTHOR, -MODULE_DESCRIPTION - Specifying module parameters +rtapi_module_param - Specifying module parameters -== SYNTAX - -.... -RTAPI_MP_INT(_var_, _description_); -RTAPI_MP_LONG(_var_, _description_); -RTAPI_MP_STRING(_var_, _description_); -RTAPI_MP_ARRAY_INT(_var_, _num_, _description_); -RTAPI_MP_ARRAY_LONG(_var_, _num_, _description_); -RTAPI_MP_ARRAY_STRING(_var_, _num_, _description_); -MODULE_LICENSE(_license_); -MODULE_AUTHOR(_author_); -MODULE_DESCRIPTION(_description_); -EXPORT_FUNCTION(_function_); -.... - -== ARGUMENTS - -var:: - The variable where the parameter should be stored -description:: - A short description of the parameter or module -num:: - The maximum number of values for an array parameter -license:: - The license of the module, for instance "GPL" -author:: - The author of the module -function:: - The pointer to the function to be exported - -== DESCRIPTION - -These macros are portable ways to declare kernel module parameters. They -must be used in the global scope, and are not followed by a terminating -semicolon. They must be used after the associated variable or function -has been defined. - -== NOTES - -EXPORT_FUNCTION makes a symbol available for use by a subsequently -loaded component. It is unrelated to HAL functions, which are described -in hal_export_funct(3hal) - -== Interpretation of license strings - -*MODULE_LICENSE* follows the kernel's definition of license strings. -Notably, "GPL" indicates "GNU General Public License v2 _or later_". -(emphasis ours). - -"GPL":: - GNU General Public License v2 or later -"GPL v2":: - GNU General Public License v2 -"GPL and additional rights":: - GNU General Public License v2 rights and more -"Dual BSD/GPL":: - GNU General Public License v2 or BSD license choice -"Dual MIT/GPL":: - GNU General Public License v2 or MIT license choice -"Dual MPL/GPL":: - GNU General Public License v2 or Mozilla license choice -"Proprietary":: - Non-free products - -It is still good practice to include a license block which indicates the -author, copyright date, and disclaimer of warranty as recommended by the -GNU GPL. - -== REALTIME CONSIDERATIONS - -Not available in userspace code. +include::rtapi_module_param.3.body[] \ No newline at end of file diff --git a/docs/src/man/man3/rtapi_module_param.3.body b/docs/src/man/man3/rtapi_module_param.3.body new file mode 100644 index 00000000000..9d0b80acc4a --- /dev/null +++ b/docs/src/man/man3/rtapi_module_param.3.body @@ -0,0 +1,75 @@ +// Tis is the content of rtapi_module_param(3rtapi) without header to avoid +// problems with name mismatches as it is included in other man pages. + + +== SYNTAX + +.... +RTAPI_MP_INT(_var_, _description_); +RTAPI_MP_LONG(_var_, _description_); +RTAPI_MP_STRING(_var_, _description_); +RTAPI_MP_ARRAY_INT(_var_, _num_, _description_); +RTAPI_MP_ARRAY_LONG(_var_, _num_, _description_); +RTAPI_MP_ARRAY_STRING(_var_, _num_, _description_); +MODULE_LICENSE(_license_); +MODULE_AUTHOR(_author_); +MODULE_DESCRIPTION(_description_); +EXPORT_FUNCTION(_function_); +.... + +== ARGUMENTS + +var:: + The variable where the parameter should be stored +description:: + A short description of the parameter or module +num:: + The maximum number of values for an array parameter +license:: + The license of the module, for instance "GPL" +author:: + The author of the module +function:: + The pointer to the function to be exported + +== DESCRIPTION + +These macros are portable ways to declare kernel module parameters. They +must be used in the global scope, and are not followed by a terminating +semicolon. They must be used after the associated variable or function +has been defined. + +== NOTES + +EXPORT_FUNCTION makes a symbol available for use by a subsequently +loaded component. It is unrelated to HAL functions, which are described +in hal_export_funct(3hal) + +== Interpretation of license strings + +*MODULE_LICENSE* follows the kernel's definition of license strings. +Notably, "GPL" indicates "GNU General Public License v2 _or later_". +(emphasis ours). + +"GPL":: + GNU General Public License v2 or later +"GPL v2":: + GNU General Public License v2 +"GPL and additional rights":: + GNU General Public License v2 rights and more +"Dual BSD/GPL":: + GNU General Public License v2 or BSD license choice +"Dual MIT/GPL":: + GNU General Public License v2 or MIT license choice +"Dual MPL/GPL":: + GNU General Public License v2 or Mozilla license choice +"Proprietary":: + Non-free products + +It is still good practice to include a license block which indicates the +author, copyright date, and disclaimer of warranty as recommended by the +GNU GPL. + +== REALTIME CONSIDERATIONS + +Not available in userspace code.