Skip to content

Conversation

chucklever
Copy link
Member

Re-work existing Doxygen comments to conform to user space Doxygen special commands, then add a GitHub action that can build a gh-pages web site using the man pages, config examples, and doxygen output.

Note that there are some restrictions on what the oracle/ organization permits in action workflows. I have tested the new workflow in my own repository, but it might be that the new action does not work immediately due to these restrictions. We won't be able to tell until I merge the new action into the main branch.

chucklever and others added 16 commits October 2, 2025 16:59
Currently, QUIC support is disabled in tlshd unless the kernel's
uapi/linux/quic.h file is present on the system. Since that work
is not yet upstream, pretty much no build environment has this
file.

Including this header now enables the oracle/ktls-utils testing
workflows for the code in quic.c, and also enables development for
tlshd code near the quic.c code -- ie, at least now building fails
immediately if you've done something incompatible with what's in
quic.c.

This copy of quic.h can be updated periodically or removed entirely
when the kernel version of this file becomes reliably available.

I pulled the file from:

https://lore.kernel.org/netdev/[email protected]/T/#m377dc3b337c5bcfef79dc64400fec3a5e41cdbe0

Signed-off-by: Chuck Lever <[email protected]>
…setup

Align the QUIC session setup error handling with the TLS 1.3 code paths:

- tlshd_tls13_client_x509_handshake()
- tlshd_tls13_client_psk_handshake()
- tlshd_tls13_server_x509_handshake()
- tlshd_tls13_server_psk_handshake()

The QUIC session setup functions:

- tlshd_quic_client_set_x509_session()
- tlshd_quic_client_set_psk_session()
- tlshd_quic_server_set_x509_session()
- tlshd_quic_server_set_psk_session()

will no longer return an error directly. Instead, if a GnuTLS API call
fails, session_status is left as EIO after logging the Gnutls errors.

Signed-off-by: Xin Long <[email protected]>
Signed-off-by: Chuck Lever <[email protected]>
Align QUIC handshake error handling with the TLS 1.3 path in
tlshd_start_tls_handshake(). In tlshd_quic_start_handshake(), any error
returned from the GnuTLS API is now logged and mapped to conn->errcode =
EACCES (session_status).

Note: unlike TLS 1.3, the QUIC handshake manages its own packet send/recv.
Timeouts are handled separately, with conn->errcode set to ETIMEDOUT
by quic_timer_handler().

Signed-off-by: Xin Long <[email protected]>
Signed-off-by: Chuck Lever <[email protected]>
I started the ktls-utils project using the Linux kernel flavor of
Doxygen commenting which user-space Doxygen does not recognize by
default.

Convert existing comments in client.c to what a normal user space
Doxygen run expects to see. This will enable deployment of an
automatically-generated documentation web site.

Signed-off-by: Chuck Lever <[email protected]>
I started the ktls-utils project using the Linux kernel flavor of
Doxygen commenting which user-space Doxygen does not recognize by
default.

Convert existing comments in config.c to what a normal user space
Doxygen run expects to see. This will enable deployment of an
automatically-generated documentation web site.

Signed-off-by: Chuck Lever <[email protected]>
I started the ktls-utils project using the Linux kernel flavor of
Doxygen commenting which user-space Doxygen does not recognize by
default.

Convert existing comments in handshake.c to what a normal user space
Doxygen run expects to see. This will enable deployment of an
automatically-generated documentation web site.

Signed-off-by: Chuck Lever <[email protected]>
I started the ktls-utils project using the Linux kernel flavor of
Doxygen commenting which user-space Doxygen does not recognize by
default.

Convert existing comments in keyring.c to what a normal user space
Doxygen run expects to see. This will enable deployment of an
automatically-generated documentation web site.

Signed-off-by: Chuck Lever <[email protected]>
I started the ktls-utils project using the Linux kernel flavor of
Doxygen commenting which user-space Doxygen does not recognize by
default.

Convert existing comments in ktls.c to what a normal user space
Doxygen run expects to see. This will enable deployment of an
automatically-generated documentation web site.

Signed-off-by: Chuck Lever <[email protected]>
I started the ktls-utils project using the Linux kernel flavor of
Doxygen commenting which user-space Doxygen does not recognize by
default.

Convert existing comments in log.c to what a normal user space
Doxygen run expects to see. This will enable deployment of an
automatically-generated documentation web site.
I started the ktls-utils project using the Linux kernel flavor of
Doxygen commenting which user-space Doxygen does not recognize by
default.

Convert existing comments in main.c to what a normal user space
Doxygen run expects to see. This will enable deployment of an
automatically-generated documentation web site.

Signed-off-by: Chuck Lever <[email protected]>
I started the ktls-utils project using the Linux kernel flavor of
Doxygen commenting which user-space Doxygen does not recognize by
default.

Convert existing comments in netlink.c to what a normal user space
Doxygen run expects to see. This will enable deployment of an
automatically-generated documentation web site.

Signed-off-by: Chuck Lever <[email protected]>
I started the ktls-utils project using the Linux kernel flavor of
Doxygen commenting which user-space Doxygen does not recognize by
default.

Convert existing comments in quic.c to what a normal user space
Doxygen run expects to see. This will enable deployment of an
automatically-generated documentation web site.

Signed-off-by: Chuck Lever <[email protected]>
I started the ktls-utils project using the Linux kernel flavor of
Doxygen commenting which user-space Doxygen does not recognize by
default.

Convert existing comments in server.c to what a normal user space
Doxygen run expects to see. This will enable deployment of an
automatically-generated documentation web site.

Signed-off-by: Chuck Lever <[email protected]>
I started the ktls-utils project using the Linux kernel flavor of
Doxygen commenting which user-space Doxygen does not recognize by
default.

Convert existing comments in tlshd.h to what a normal user space
Doxygen run expects to see. This will enable deployment of an
automatically-generated documentation web site.

Signed-off-by: Chuck Lever <[email protected]>
Make use of the nice documenting comments I've added over the
years to build some developer documentation.

The generated pages are not installed (but could be if there is
demand).

Signed-off-by: Chuck Lever <[email protected]>
Add a GitHub Action that compiles the Doxygen comments and the man
pages in the tlshd source code and builds a .io web site. This is a
small step towards improving the published upstream documentation
for ktls-utils.

Signed-off-by: Chuck Lever <[email protected]>
@chucklever chucklever merged commit b7f81df into main Oct 3, 2025
12 of 13 checks passed
@chucklever chucklever deleted the gen-docs branch October 3, 2025 16:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants