From 107e5f5e4bccb89404aa98b434c4c72fa241ab49 Mon Sep 17 00:00:00 2001 From: Corey Minyard Date: Sat, 4 Jan 2025 12:05:56 -0600 Subject: [PATCH] man: Add man pages for newly added operations Signed-off-by: Corey Minyard --- man/Makefile.am | 2 +- man/gensio.5 | 12 ++++- man/gensio_atomics.3 | 105 ++++++++++++++++++++++++++++++++++++++++++ man/gensio_bswap.3 | 32 +++++++++++++ man/gensio_refcount.3 | 59 ++++++++++++++++++++++++ 5 files changed, 208 insertions(+), 2 deletions(-) create mode 100644 man/gensio_atomics.3 create mode 100644 man/gensio_bswap.3 create mode 100644 man/gensio_refcount.3 diff --git a/man/Makefile.am b/man/Makefile.am index 4bbd8f20..21d3e07b 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -7,7 +7,7 @@ man_MANS = gensio.5 gensio_event.3 str_to_gensio.3 gensio_set_callback.3 \ gensio_acc_control.3 gensio_acc_get_type.3 gensio_add_default.3 \ str_to_gensio_accepter.3 gensio_acc_accept_s.3 gensio_acc_startup.3 \ sergensio.5 gensio_to_sergensio.3 sergensio_baud.3 \ - sergensio_b_alloc.3 sergensio_event.3 gensio_mdns.3 + sergensio_b_alloc.3 sergensio_event.3 gensio_mdns.3 gensio_bswap.3 # Note that $(LN_SF) is set in configure.ac diff --git a/man/gensio.5 b/man/gensio.5 index 1d1621d2..546c324e 100644 --- a/man/gensio.5 +++ b/man/gensio.5 @@ -2668,7 +2668,17 @@ call after a fork in the new fork (not the old one). It will handle any cleanup required after the fork. Other systems may require other cleanups after a fork, so you should always call this after a fork. .SH "SEE ALSO" -gensiot(1), sctp(7), udp(7), tcp(7), unix(7) +gensiot(1), sctp(7), udp(7), tcp(7), unix(7), gensio_open(3), +gensio_close(3), gensio_control(3), gensio_set_sync(3), +gensio_write(3), gensio_acc_set_sync(3), gensio_acc_control(3), +gensio_os_funcs(3), str_to_gensio(3), str_to_gensio_accepter(3), +gensio_set_read_callback_enable(3), gensio_err(3), gensio_mdns(3), +gensio_get_type(3), gensio_acc_get_type(3), +gensio_acc_set_accept_callback_enable(3), gensio_event(3), +gensio_accepter_event(3), gensio_acc_shutdown(3), gensio_set_callback(3) +gensio_acc_set_callback(3), gensio_add_default(3), gensio_alloc_channel(3), +gensio_set_log_mask(3), gensio_acc_startup(3), gensio_acc_shutdown(3), +gensio_bswap(3), gensio_atomics(3), gensio_refcount(3) .SH "KNOWN PROBLEMS" None. .SH AUTHOR diff --git a/man/gensio_atomics.3 b/man/gensio_atomics.3 new file mode 100644 index 00000000..b4e837c4 --- /dev/null +++ b/man/gensio_atomics.3 @@ -0,0 +1,105 @@ +.TH gensio_atomics 3 "04 Jan 2025" +.SH NAME +gensio_atomic_set, gensio_atomic_set_mo, gensio_atomic_get, +gensio_atomic_get_mo, gensio_atomic_cas, +gensio_atomic_cas_mo, +gensio_atomic_add, gensio_atomic_add_mo, +gensio_atomic_sub, gensio_atomic_sub_mo, +gensio_atomic_add_if_nz, gensio_atomic_add_if_nz_mo +gensio_atomic_sub_if_nz, gensio_atomic_sub_if_nz_mo +gensio_atomic_inc_if_nz, gensio_atomic_inc_if_nz_mo +gensio_atomic_dec_if_nz, gensio_atomic_dec_if_nz_mo +\- Atomic operations. +.SH "SYNOPSIS" +.B #include +.br +typedef xxx gensio_atomic_uint; +.br +enum gensio_memory_order { +.br + gensio_mo_relaxed = xxx, +.br + gensio_mo_consume = xxx, +.br + gensio_mo_acquire = xxx, +.br + gensio_mo_release = xxx, +.br + gensio_mo_acq_rel = xxx, +.br + gensio_mo_seq_cst = xxx, +.br +}; +.br +.TP 20 +.B gensio_atomic_set(a, v) +.TP 20 +.B gensio_atomic_set_mo(a, v, mo) +.TP 20 +.B gensio_atomic_get(a) +.TP 20 +.B gensio_atomic_get_mo(a, mo) +.TP 20 +.B gensio_atomic_cas(a, old, new) +.TP 20 +.B gensio_atomic_cas_mo(a, old, new, succ_mo, fail_mo) +.TP 20 +.B gensio_atomic_add(a, v) +.TP 20 +.B gensio_atomic_add_mo(a, v, mo) +.TP 20 +.B gensio_atomic_sub(a, v) +.TP 20 +.B gensio_atomic_sub_mo(a, v, mo) +.TP 20 +.B gensio_atomic_add_if_nz(a, old, v) +.TP 20 +.B gensio_atomic_add_if_nz_mo(a, old, v, mo) +.TP 20 +.B gensio_atomic_sub_if_nz(a, old, v) +.TP 20 +.B gensio_atomic_sub_if_nz_mo(a, old, v, mo) +.TP 20 +.B gensio_atomic_inc_if_nz(a, old, v) +.TP 20 +.B gensio_atomic_inc_if_nz_mo(a, old, mo) +.TP 20 +.B gensio_atomic_dec_if_nz(a, old, v) +.TP 20 +.B gensio_atomic_dec_if_nz_mo(a, old, mo) +.SH "DESCRIPTION" +These perform atomic operations. See the C atomic operations standard +(https://en.cppreference.com/w/c/atomic) for what these do. Operations +ending in +.B _mo +Take a memory ordering value. Operations not ending in that use the +strongest memory ordering semantics. + +The operations ending in +.B _if_nz +will perform the operation if the value is not already zero. + +All operations with an +.B old +value return the previous value in old. For the operations ending in +.B _if_nz +the return value in old will be 0 if not successfull, non-zero if +successful. + + +.SH "CAVEATS" +Currently these are only implemented on processors that can do this +natively. A non-native implementation with locks could be done, +though. + +Currently only uint is implemented, though implementing other types +would be trivial. +.SH "RETURN VALUES" +gensio_atomic_get() and gensio_atomic_get_mo() return the current value. + +gensio_atomic_cas() and gensio_atomic_cas_mo() return true if successful, +false if not. + +All other functions/macros do not return values. +.SH "SEE ALSO" +gensio(5) diff --git a/man/gensio_bswap.3 b/man/gensio_bswap.3 new file mode 100644 index 00000000..0e2fc763 --- /dev/null +++ b/man/gensio_bswap.3 @@ -0,0 +1,32 @@ +.TH gensio_bswap 3 "04 Jan 2025" +.SH NAME +gensio_bswap_16, gensio_bswap_32, gensio_bswap_64, GENSIO_IS_BIG_ENDIAN, +GENSIO_IS_LITTLE_ENDIAN, gensio_bswap_16_from_be, gensio_bswap_32_from_be, +gensio_bswap_64_from_be, gensio_bswap_16_to_be, gensio_bswap_32_to_be, +gensio_bswap_64_to_be, gensio_bswap_16_from_le, gensio_bswap_32_from_le, +gensio_bswap_64_from_le, gensio_bswap_16_to_le, gensio_bswap_32_to_le, +gensio_bswap_64_to_le +\- Byte swapping routines. +.SH "SYNOPSIS" +.B #include +.TP 20 +.B uint[16|32|64]_t gensio_bswap_[16|32|64](v) +.TP 20 +.B uint[16|32|64]_t gensio_bswap_[16|32|64]_[from|to]_[be|le](v) +.SH "DESCRIPTION" +These routine perform normal byte swapping operations in 16, 32, and +64-bit values. The +.B gensio_bswap_[16|32|64]() +perform an unconditional byte swap. The +.B gensio_bswap_[16|32|64]_[from|to]_[be|le] +will byte swap from/to the given endianness depending on the host +platforms endianness. + +.B GENSIO_IS_BIG_ENDIAN +and +.B GENSIO_IS_LITTLE_ENDIAN +will be true or false depending on the host endian's endianness. +.SH "RETURN VALUES" +The integer, byte swapped, will be returned. +.SH "SEE ALSO" +gensio(5) diff --git a/man/gensio_refcount.3 b/man/gensio_refcount.3 new file mode 100644 index 00000000..814124fc --- /dev/null +++ b/man/gensio_refcount.3 @@ -0,0 +1,59 @@ +.TH gensio_refcount 3 "04 Jan 2025" +.SH NAME +gensio_refcount_init, gensio_refcount_cleanup, gensio_refcount_set, +gensio_refcount_get, gensio_refcount_inc, gensio_refcount_dec +gensio_refcount_inc_if_nz, gensio_refcount_dec_if_nz +\- Refcount operations. +.SH "SYNOPSIS" +.B #include +.br +typedef xxx gensio_refcount; +.br +.TP 20 +.B gensio_refcount_init(a, v) +.TP 20 +.B gensio_refcount_cleanup(a) +.TP 20 +.B gensio_refcount_set(a, v) +.TP 20 +.B gensio_refcount_get(a) +.TP 20 +.B gensio_refcount_inc(a) +.TP 20 +.B gensio_refcount_dec(a) +.TP 20 +.B gensio_refcount_inc_if_nz(a) +.TP 20 +.B gensio_refcount_dec_if_nz(a) +.SH "DESCRIPTION" +An atomic refcount. + +You could call +.B gensio_refcount_init() +to initialize the value. This may allocate locks and such, so you +should check the return value. Once done with the refcount, you +should call +.B gensio_refcount_cleanup(). + +These work like normal atomic refcounts. The operations ending in +.B if_nz +will only perform the operation if the value was not already zero. +.SH "CAVEATS" +Currently these are only implemented on processors that can do this +natively. A non-native implementation with locks could be done, +though. +.SH "RETURN VALUES" +.B gensio_refcount_get() +returns the current value. + +.B gensio_refcount_dec() +returns the new value. + +.B gensio_refcount_dec_if_nz +and +.B gensio_refcount_inc_if_nz +return true if the operation happens, false if not. + +All other functions/macros do not return values. +.SH "SEE ALSO" +gensio(5), gensio_atomics(3)