| Message ID | 20210801135146.14849-1-pali@kernel.org |
|---|---|
| State | New |
| Headers | show |
| Series | [v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port | expand |
+ linux-serial + Greg Greg, could I ask you for reviewing this documentation manpage patch? On Sunday 01 August 2021 15:51:45 Pali Rohár wrote: > Signed-off-by: Pali Rohár <pali@kernel.org> > > --- > Changes in v3: > * Check support for custom baudrate only based on BOTHER macro > * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available > > Changes in v2: > * Use \e for backslash > * Use exit(EXIT_*) instead of return num > * Sort includes > * Add comment about possible fallback > --- > > Hello Alejandro! > > I found out that this stuff is more complicated as I originally thought. > And seems that additional documentation on this topic is needed... > > For setting custom baudrate it is needed to set BOTHER flag in c_cflag > field and baudrate value itself in c_ospeed and c_ispeed fields. > > So when BOTHER flag is not provided by <asm/termbits.h> then setting custom > baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and > only some predefined Bnnn baudrate values are supported). This applies when > compiling application with older version of header files (prior support for > custom baudrate was introduced into header files). > > First caveat: BOTHER constant is different for different architectures. > So it is not possible to provide fallback #ifndef..#define BOTHER. > > And now the biggest issue: Some architectures have these c_ospeed and > c_ispeed fields in struct termios and some in struct termios2. > > TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use > struct termios2. > > Some architectures (e.g. amd64) provide both struct termios and struct > termios2, but c_ospeed and c_ispeed are only in struct termios2. > > Some other architectures (e.g. alpha) provide both struct termios and struct > termios2 and both have c_ospeed and c_ispeed fields. > > And some other architectures (e.g. powerpc) provide only struct termios > (no struct termios2) and it has c_ospeed and c_ispeed fields. > > So basically to support all architectures it is needed to use > struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed > to use struct termios with TCGETS/TCSETS (case for e.g. powerpc). > > I updated v3 patch to handle this logic. > --- > man2/ioctl_tty.2 | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 73 insertions(+) > > diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2 > index 3020f9984872..d83cbd17225b 100644 > --- a/man2/ioctl_tty.2 > +++ b/man2/ioctl_tty.2 > @@ -764,6 +764,79 @@ main(void) > close(fd); > } > .EE > +.PP > +Get or set arbitrary baudrate on the serial port. > +.PP > +.EX > +#include <asm/termbits.h> > +#include <fcntl.h> > +#include <stdio.h> > +#include <stdlib.h> > +#include <sys/ioctl.h> > +#include <sys/types.h> > +#include <unistd.h> > + > +int > +main(int argc, char *argv[]) > +{ > +#ifndef BOTHER > + fprintf(stderr, "BOTHER is unsupported\en"); > + /* Program may fallback to TCGETS/TCSETS with Bnnn constants */ > + exit(EXIT_FAILURE); > +#else > +#ifdef TCGETS2 > + struct termios2 tio; > +#else > + struct termios tio; > +#endif > + int fd, rc; > + > + if (argc != 2 && argc != 3) { > + fprintf(stderr, "Usage: %s device [new_baudrate]\en", argv[0]); > + exit(EXIT_FAILURE); > + } > + > + fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY); > + if (fd < 0) { > + perror("open"); > + exit(EXIT_FAILURE); > + } > + > +#ifdef TCGETS2 > + rc = ioctl(fd, TCGETS2, &tio); > +#else > + rc = ioctl(fd, TCGETS, &tio); > +#endif > + if (rc) { > + perror("TCGETS"); > + close(fd); > + exit(EXIT_FAILURE); > + } > + > + printf("%u\en", tio.c_ospeed); > + > + if (argc == 3) { > + tio.c_cflag &= ~CBAUD; > + tio.c_cflag |= BOTHER; > + tio.c_ospeed = tio.c_ispeed = atoi(argv[2]); > + > +#ifdef TCSETS2 > + rc = ioctl(fd, TCSETS2, &tio); > +#else > + rc = ioctl(fd, TCSETS, &tio); > +#endif > + if (rc) { > + perror("TCSETS"); > + close(fd); > + exit(EXIT_FAILURE); > + } > + } > + > + close(fd); > + exit(EXIT_SUCCESS); > +#endif > +} > +.EE > .SH SEE ALSO > .BR ldattach (1), > .BR ioctl (2), > -- > 2.20.1 >
On Thu, Aug 05, 2021 at 12:08:08AM +0200, Pali Rohár wrote: > + linux-serial > + Greg > > Greg, could I ask you for reviewing this documentation manpage patch? If it is submitted in a format I can review, sure (i.e. not top-post...) But I will dig down below to say one thing... > > On Sunday 01 August 2021 15:51:45 Pali Rohár wrote: > > Signed-off-by: Pali Rohár <pali@kernel.org> > > > > --- > > Changes in v3: > > * Check support for custom baudrate only based on BOTHER macro > > * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available > > > > Changes in v2: > > * Use \e for backslash > > * Use exit(EXIT_*) instead of return num > > * Sort includes > > * Add comment about possible fallback > > --- > > > > Hello Alejandro! > > > > I found out that this stuff is more complicated as I originally thought. > > And seems that additional documentation on this topic is needed... > > > > For setting custom baudrate it is needed to set BOTHER flag in c_cflag > > field and baudrate value itself in c_ospeed and c_ispeed fields. > > > > So when BOTHER flag is not provided by <asm/termbits.h> then setting custom > > baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and > > only some predefined Bnnn baudrate values are supported). This applies when > > compiling application with older version of header files (prior support for > > custom baudrate was introduced into header files). > > > > First caveat: BOTHER constant is different for different architectures. > > So it is not possible to provide fallback #ifndef..#define BOTHER. > > > > And now the biggest issue: Some architectures have these c_ospeed and > > c_ispeed fields in struct termios and some in struct termios2. > > > > TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use > > struct termios2. > > > > Some architectures (e.g. amd64) provide both struct termios and struct > > termios2, but c_ospeed and c_ispeed are only in struct termios2. > > > > Some other architectures (e.g. alpha) provide both struct termios and struct > > termios2 and both have c_ospeed and c_ispeed fields. > > > > And some other architectures (e.g. powerpc) provide only struct termios > > (no struct termios2) and it has c_ospeed and c_ispeed fields. > > > > So basically to support all architectures it is needed to use > > struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed > > to use struct termios with TCGETS/TCSETS (case for e.g. powerpc). > > > > I updated v3 patch to handle this logic. > > --- > > man2/ioctl_tty.2 | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ > > 1 file changed, 73 insertions(+) > > > > diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2 > > index 3020f9984872..d83cbd17225b 100644 > > --- a/man2/ioctl_tty.2 > > +++ b/man2/ioctl_tty.2 > > @@ -764,6 +764,79 @@ main(void) > > close(fd); > > } > > .EE > > +.PP > > +Get or set arbitrary baudrate on the serial port. > > +.PP > > +.EX > > +#include <asm/termbits.h> > > +#include <fcntl.h> > > +#include <stdio.h> > > +#include <stdlib.h> > > +#include <sys/ioctl.h> > > +#include <sys/types.h> > > +#include <unistd.h> > > + > > +int > > +main(int argc, char *argv[]) > > +{ > > +#ifndef BOTHER > > + fprintf(stderr, "BOTHER is unsupported\en"); > > + /* Program may fallback to TCGETS/TCSETS with Bnnn constants */ > > + exit(EXIT_FAILURE); So this is a BOTHER test only? What is the goal of this program? Don't throw a bunch of #ifdef in here for no good reason. These options should all be present on all normal kernels, why wouldn't they be? thanks, greg k-h
On Thursday 05 August 2021 07:52:03 Greg Kroah-Hartman wrote: > On Thu, Aug 05, 2021 at 12:08:08AM +0200, Pali Rohár wrote: > > + linux-serial > > + Greg > > > > Greg, could I ask you for reviewing this documentation manpage patch? > > If it is submitted in a format I can review, sure (i.e. not top-post...) > > But I will dig down below to say one thing... > > > > > On Sunday 01 August 2021 15:51:45 Pali Rohár wrote: > > > Signed-off-by: Pali Rohár <pali@kernel.org> > > > > > > --- > > > Changes in v3: > > > * Check support for custom baudrate only based on BOTHER macro > > > * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available > > > > > > Changes in v2: > > > * Use \e for backslash > > > * Use exit(EXIT_*) instead of return num > > > * Sort includes > > > * Add comment about possible fallback > > > --- > > > > > > Hello Alejandro! > > > > > > I found out that this stuff is more complicated as I originally thought. > > > And seems that additional documentation on this topic is needed... > > > > > > For setting custom baudrate it is needed to set BOTHER flag in c_cflag > > > field and baudrate value itself in c_ospeed and c_ispeed fields. > > > > > > So when BOTHER flag is not provided by <asm/termbits.h> then setting custom > > > baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and > > > only some predefined Bnnn baudrate values are supported). This applies when > > > compiling application with older version of header files (prior support for > > > custom baudrate was introduced into header files). > > > > > > First caveat: BOTHER constant is different for different architectures. > > > So it is not possible to provide fallback #ifndef..#define BOTHER. > > > > > > And now the biggest issue: Some architectures have these c_ospeed and > > > c_ispeed fields in struct termios and some in struct termios2. > > > > > > TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use > > > struct termios2. > > > > > > Some architectures (e.g. amd64) provide both struct termios and struct > > > termios2, but c_ospeed and c_ispeed are only in struct termios2. > > > > > > Some other architectures (e.g. alpha) provide both struct termios and struct > > > termios2 and both have c_ospeed and c_ispeed fields. > > > > > > And some other architectures (e.g. powerpc) provide only struct termios > > > (no struct termios2) and it has c_ospeed and c_ispeed fields. > > > > > > So basically to support all architectures it is needed to use > > > struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed > > > to use struct termios with TCGETS/TCSETS (case for e.g. powerpc). > > > > > > I updated v3 patch to handle this logic. > > > --- > > > man2/ioctl_tty.2 | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ > > > 1 file changed, 73 insertions(+) > > > > > > diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2 > > > index 3020f9984872..d83cbd17225b 100644 > > > --- a/man2/ioctl_tty.2 > > > +++ b/man2/ioctl_tty.2 > > > @@ -764,6 +764,79 @@ main(void) > > > close(fd); > > > } > > > .EE > > > +.PP > > > +Get or set arbitrary baudrate on the serial port. > > > +.PP > > > +.EX > > > +#include <asm/termbits.h> > > > +#include <fcntl.h> > > > +#include <stdio.h> > > > +#include <stdlib.h> > > > +#include <sys/ioctl.h> > > > +#include <sys/types.h> > > > +#include <unistd.h> > > > + > > > +int > > > +main(int argc, char *argv[]) > > > +{ > > > +#ifndef BOTHER > > > + fprintf(stderr, "BOTHER is unsupported\en"); > > > + /* Program may fallback to TCGETS/TCSETS with Bnnn constants */ > > > + exit(EXIT_FAILURE); > > So this is a BOTHER test only? Yes. > What is the goal of this program? Don't throw a bunch of #ifdef in here > for no good reason. These options should all be present on all normal > kernels, why wouldn't they be? I wanted to provide complete example which compiles fine on all Linux systems, even with older include header files. I do not know right now in which kernel version was introduced BOTHER support for all architectures. If BOHTER is not supported then it is possible to still use Bnnn constants to get / set baudrate. Just it is needed to write long code for converting number to suitable Bnnn constant. Do you think that this BOTHER check is not useful in this case? > thanks, > > greg k-h
On Thu, Aug 05, 2021 at 10:22:43AM +0200, Pali Rohár wrote: > On Thursday 05 August 2021 07:52:03 Greg Kroah-Hartman wrote: > > On Thu, Aug 05, 2021 at 12:08:08AM +0200, Pali Rohár wrote: > > > + linux-serial > > > + Greg > > > > > > Greg, could I ask you for reviewing this documentation manpage patch? > > > > If it is submitted in a format I can review, sure (i.e. not top-post...) > > > > But I will dig down below to say one thing... > > > > > > > > On Sunday 01 August 2021 15:51:45 Pali Rohár wrote: > > > > Signed-off-by: Pali Rohár <pali@kernel.org> > > > > > > > > --- > > > > Changes in v3: > > > > * Check support for custom baudrate only based on BOTHER macro > > > > * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available > > > > > > > > Changes in v2: > > > > * Use \e for backslash > > > > * Use exit(EXIT_*) instead of return num > > > > * Sort includes > > > > * Add comment about possible fallback > > > > --- > > > > > > > > Hello Alejandro! > > > > > > > > I found out that this stuff is more complicated as I originally thought. > > > > And seems that additional documentation on this topic is needed... > > > > > > > > For setting custom baudrate it is needed to set BOTHER flag in c_cflag > > > > field and baudrate value itself in c_ospeed and c_ispeed fields. > > > > > > > > So when BOTHER flag is not provided by <asm/termbits.h> then setting custom > > > > baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and > > > > only some predefined Bnnn baudrate values are supported). This applies when > > > > compiling application with older version of header files (prior support for > > > > custom baudrate was introduced into header files). > > > > > > > > First caveat: BOTHER constant is different for different architectures. > > > > So it is not possible to provide fallback #ifndef..#define BOTHER. > > > > > > > > And now the biggest issue: Some architectures have these c_ospeed and > > > > c_ispeed fields in struct termios and some in struct termios2. > > > > > > > > TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use > > > > struct termios2. > > > > > > > > Some architectures (e.g. amd64) provide both struct termios and struct > > > > termios2, but c_ospeed and c_ispeed are only in struct termios2. > > > > > > > > Some other architectures (e.g. alpha) provide both struct termios and struct > > > > termios2 and both have c_ospeed and c_ispeed fields. > > > > > > > > And some other architectures (e.g. powerpc) provide only struct termios > > > > (no struct termios2) and it has c_ospeed and c_ispeed fields. > > > > > > > > So basically to support all architectures it is needed to use > > > > struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed > > > > to use struct termios with TCGETS/TCSETS (case for e.g. powerpc). > > > > > > > > I updated v3 patch to handle this logic. > > > > --- > > > > man2/ioctl_tty.2 | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ > > > > 1 file changed, 73 insertions(+) > > > > > > > > diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2 > > > > index 3020f9984872..d83cbd17225b 100644 > > > > --- a/man2/ioctl_tty.2 > > > > +++ b/man2/ioctl_tty.2 > > > > @@ -764,6 +764,79 @@ main(void) > > > > close(fd); > > > > } > > > > .EE > > > > +.PP > > > > +Get or set arbitrary baudrate on the serial port. > > > > +.PP > > > > +.EX > > > > +#include <asm/termbits.h> > > > > +#include <fcntl.h> > > > > +#include <stdio.h> > > > > +#include <stdlib.h> > > > > +#include <sys/ioctl.h> > > > > +#include <sys/types.h> > > > > +#include <unistd.h> > > > > + > > > > +int > > > > +main(int argc, char *argv[]) > > > > +{ > > > > +#ifndef BOTHER > > > > + fprintf(stderr, "BOTHER is unsupported\en"); > > > > + /* Program may fallback to TCGETS/TCSETS with Bnnn constants */ > > > > + exit(EXIT_FAILURE); > > > > So this is a BOTHER test only? > > Yes. > > > What is the goal of this program? Don't throw a bunch of #ifdef in here > > for no good reason. These options should all be present on all normal > > kernels, why wouldn't they be? > > I wanted to provide complete example which compiles fine on all Linux > systems, even with older include header files. I do not know right now > in which kernel version was introduced BOTHER support for all > architectures. We have all of the kernel source in a tool that would allow you to to determine this quite easily :) > If BOHTER is not supported then it is possible to still use Bnnn > constants to get / set baudrate. Just it is needed to write long code > for converting number to suitable Bnnn constant. > > Do you think that this BOTHER check is not useful in this case? I think you should provide an example of how to use BOTHER, yes, as it is hard to find good examples out there as they keep floating around. Here's one that I point people to a lot: https://github.com/GrantEdwards/Linux-arbitrary-baud Make the example code easy to follow. Also, you forgot a license for this code, that is required if you want people to use it... thanks, greg k-h
On Thursday 05 August 2021 10:30:15 Greg Kroah-Hartman wrote: > On Thu, Aug 05, 2021 at 10:22:43AM +0200, Pali Rohár wrote: > > On Thursday 05 August 2021 07:52:03 Greg Kroah-Hartman wrote: > > > On Thu, Aug 05, 2021 at 12:08:08AM +0200, Pali Rohár wrote: > > > > + linux-serial > > > > + Greg > > > > > > > > Greg, could I ask you for reviewing this documentation manpage patch? > > > > > > If it is submitted in a format I can review, sure (i.e. not top-post...) > > > > > > But I will dig down below to say one thing... > > > > > > > > > > > On Sunday 01 August 2021 15:51:45 Pali Rohár wrote: > > > > > Signed-off-by: Pali Rohár <pali@kernel.org> > > > > > > > > > > --- > > > > > Changes in v3: > > > > > * Check support for custom baudrate only based on BOTHER macro > > > > > * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available > > > > > > > > > > Changes in v2: > > > > > * Use \e for backslash > > > > > * Use exit(EXIT_*) instead of return num > > > > > * Sort includes > > > > > * Add comment about possible fallback > > > > > --- > > > > > > > > > > Hello Alejandro! > > > > > > > > > > I found out that this stuff is more complicated as I originally thought. > > > > > And seems that additional documentation on this topic is needed... > > > > > > > > > > For setting custom baudrate it is needed to set BOTHER flag in c_cflag > > > > > field and baudrate value itself in c_ospeed and c_ispeed fields. > > > > > > > > > > So when BOTHER flag is not provided by <asm/termbits.h> then setting custom > > > > > baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and > > > > > only some predefined Bnnn baudrate values are supported). This applies when > > > > > compiling application with older version of header files (prior support for > > > > > custom baudrate was introduced into header files). > > > > > > > > > > First caveat: BOTHER constant is different for different architectures. > > > > > So it is not possible to provide fallback #ifndef..#define BOTHER. > > > > > > > > > > And now the biggest issue: Some architectures have these c_ospeed and > > > > > c_ispeed fields in struct termios and some in struct termios2. > > > > > > > > > > TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use > > > > > struct termios2. > > > > > > > > > > Some architectures (e.g. amd64) provide both struct termios and struct > > > > > termios2, but c_ospeed and c_ispeed are only in struct termios2. > > > > > > > > > > Some other architectures (e.g. alpha) provide both struct termios and struct > > > > > termios2 and both have c_ospeed and c_ispeed fields. > > > > > > > > > > And some other architectures (e.g. powerpc) provide only struct termios > > > > > (no struct termios2) and it has c_ospeed and c_ispeed fields. > > > > > > > > > > So basically to support all architectures it is needed to use > > > > > struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed > > > > > to use struct termios with TCGETS/TCSETS (case for e.g. powerpc). > > > > > > > > > > I updated v3 patch to handle this logic. > > > > > --- > > > > > man2/ioctl_tty.2 | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ > > > > > 1 file changed, 73 insertions(+) > > > > > > > > > > diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2 > > > > > index 3020f9984872..d83cbd17225b 100644 > > > > > --- a/man2/ioctl_tty.2 > > > > > +++ b/man2/ioctl_tty.2 > > > > > @@ -764,6 +764,79 @@ main(void) > > > > > close(fd); > > > > > } > > > > > .EE > > > > > +.PP > > > > > +Get or set arbitrary baudrate on the serial port. > > > > > +.PP > > > > > +.EX > > > > > +#include <asm/termbits.h> > > > > > +#include <fcntl.h> > > > > > +#include <stdio.h> > > > > > +#include <stdlib.h> > > > > > +#include <sys/ioctl.h> > > > > > +#include <sys/types.h> > > > > > +#include <unistd.h> > > > > > + > > > > > +int > > > > > +main(int argc, char *argv[]) > > > > > +{ > > > > > +#ifndef BOTHER > > > > > + fprintf(stderr, "BOTHER is unsupported\en"); > > > > > + /* Program may fallback to TCGETS/TCSETS with Bnnn constants */ > > > > > + exit(EXIT_FAILURE); > > > > > > So this is a BOTHER test only? > > > > Yes. > > > > > What is the goal of this program? Don't throw a bunch of #ifdef in here > > > for no good reason. These options should all be present on all normal > > > kernels, why wouldn't they be? > > > > I wanted to provide complete example which compiles fine on all Linux > > systems, even with older include header files. I do not know right now > > in which kernel version was introduced BOTHER support for all > > architectures. > > We have all of the kernel source in a tool that would allow you to to > determine this quite easily :) > > > If BOHTER is not supported then it is possible to still use Bnnn > > constants to get / set baudrate. Just it is needed to write long code > > for converting number to suitable Bnnn constant. > > > > Do you think that this BOTHER check is not useful in this case? > > I think you should provide an example of how to use BOTHER, yes, as it > is hard to find good examples out there as they keep floating around. Exactly, and this is one of the reason why I sent this my patch for ioctl_tty.2. > Here's one that I point people to a lot: > https://github.com/GrantEdwards/Linux-arbitrary-baud I'm looking at this example at it has lot of problems: * Does not compile on powerpc (see explanation above). * Does not include <sys/ioctl.h> and instead provide open-coded declaration of ioctl: int ioctl(int d, int request, ...); * Does not handle case when TCGETS/TCSETS contains t.c_ospeed In my opinion include header files should be used instead of writing own declaration of functions. > Make the example code easy to follow. > > Also, you forgot a license for this code, that is required if you want > people to use it... Hm... I do not see any license in other manpage examples. Does not apply for it global license defined in ioctl_tty.2 file? Alejandro: How do you handle licences in other examples? > thanks, > > greg k-h
On Thu, Aug 05, 2021 at 10:44:10AM +0200, Pali Rohár wrote: > On Thursday 05 August 2021 10:30:15 Greg Kroah-Hartman wrote: > > On Thu, Aug 05, 2021 at 10:22:43AM +0200, Pali Rohár wrote: > > > On Thursday 05 August 2021 07:52:03 Greg Kroah-Hartman wrote: > > > > On Thu, Aug 05, 2021 at 12:08:08AM +0200, Pali Rohár wrote: > > > > > + linux-serial > > > > > + Greg > > > > > > > > > > Greg, could I ask you for reviewing this documentation manpage patch? > > > > > > > > If it is submitted in a format I can review, sure (i.e. not top-post...) > > > > > > > > But I will dig down below to say one thing... > > > > > > > > > > > > > > On Sunday 01 August 2021 15:51:45 Pali Rohár wrote: > > > > > > Signed-off-by: Pali Rohár <pali@kernel.org> > > > > > > > > > > > > --- > > > > > > Changes in v3: > > > > > > * Check support for custom baudrate only based on BOTHER macro > > > > > > * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available > > > > > > > > > > > > Changes in v2: > > > > > > * Use \e for backslash > > > > > > * Use exit(EXIT_*) instead of return num > > > > > > * Sort includes > > > > > > * Add comment about possible fallback > > > > > > --- > > > > > > > > > > > > Hello Alejandro! > > > > > > > > > > > > I found out that this stuff is more complicated as I originally thought. > > > > > > And seems that additional documentation on this topic is needed... > > > > > > > > > > > > For setting custom baudrate it is needed to set BOTHER flag in c_cflag > > > > > > field and baudrate value itself in c_ospeed and c_ispeed fields. > > > > > > > > > > > > So when BOTHER flag is not provided by <asm/termbits.h> then setting custom > > > > > > baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and > > > > > > only some predefined Bnnn baudrate values are supported). This applies when > > > > > > compiling application with older version of header files (prior support for > > > > > > custom baudrate was introduced into header files). > > > > > > > > > > > > First caveat: BOTHER constant is different for different architectures. > > > > > > So it is not possible to provide fallback #ifndef..#define BOTHER. > > > > > > > > > > > > And now the biggest issue: Some architectures have these c_ospeed and > > > > > > c_ispeed fields in struct termios and some in struct termios2. > > > > > > > > > > > > TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use > > > > > > struct termios2. > > > > > > > > > > > > Some architectures (e.g. amd64) provide both struct termios and struct > > > > > > termios2, but c_ospeed and c_ispeed are only in struct termios2. > > > > > > > > > > > > Some other architectures (e.g. alpha) provide both struct termios and struct > > > > > > termios2 and both have c_ospeed and c_ispeed fields. > > > > > > > > > > > > And some other architectures (e.g. powerpc) provide only struct termios > > > > > > (no struct termios2) and it has c_ospeed and c_ispeed fields. > > > > > > > > > > > > So basically to support all architectures it is needed to use > > > > > > struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed > > > > > > to use struct termios with TCGETS/TCSETS (case for e.g. powerpc). > > > > > > > > > > > > I updated v3 patch to handle this logic. > > > > > > --- > > > > > > man2/ioctl_tty.2 | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ > > > > > > 1 file changed, 73 insertions(+) > > > > > > > > > > > > diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2 > > > > > > index 3020f9984872..d83cbd17225b 100644 > > > > > > --- a/man2/ioctl_tty.2 > > > > > > +++ b/man2/ioctl_tty.2 > > > > > > @@ -764,6 +764,79 @@ main(void) > > > > > > close(fd); > > > > > > } > > > > > > .EE > > > > > > +.PP > > > > > > +Get or set arbitrary baudrate on the serial port. > > > > > > +.PP > > > > > > +.EX > > > > > > +#include <asm/termbits.h> > > > > > > +#include <fcntl.h> > > > > > > +#include <stdio.h> > > > > > > +#include <stdlib.h> > > > > > > +#include <sys/ioctl.h> > > > > > > +#include <sys/types.h> > > > > > > +#include <unistd.h> > > > > > > + > > > > > > +int > > > > > > +main(int argc, char *argv[]) > > > > > > +{ > > > > > > +#ifndef BOTHER > > > > > > + fprintf(stderr, "BOTHER is unsupported\en"); > > > > > > + /* Program may fallback to TCGETS/TCSETS with Bnnn constants */ > > > > > > + exit(EXIT_FAILURE); > > > > > > > > So this is a BOTHER test only? > > > > > > Yes. > > > > > > > What is the goal of this program? Don't throw a bunch of #ifdef in here > > > > for no good reason. These options should all be present on all normal > > > > kernels, why wouldn't they be? > > > > > > I wanted to provide complete example which compiles fine on all Linux > > > systems, even with older include header files. I do not know right now > > > in which kernel version was introduced BOTHER support for all > > > architectures. > > > > We have all of the kernel source in a tool that would allow you to to > > determine this quite easily :) > > > > > If BOHTER is not supported then it is possible to still use Bnnn > > > constants to get / set baudrate. Just it is needed to write long code > > > for converting number to suitable Bnnn constant. > > > > > > Do you think that this BOTHER check is not useful in this case? > > > > I think you should provide an example of how to use BOTHER, yes, as it > > is hard to find good examples out there as they keep floating around. > > Exactly, and this is one of the reason why I sent this my patch for > ioctl_tty.2. > > > Here's one that I point people to a lot: > > https://github.com/GrantEdwards/Linux-arbitrary-baud > > I'm looking at this example at it has lot of problems: > > * Does not compile on powerpc (see explanation above). > * Does not include <sys/ioctl.h> and instead provide open-coded > declaration of ioctl: int ioctl(int d, int request, ...); > * Does not handle case when TCGETS/TCSETS contains t.c_ospeed Great, then fix all of that :) > In my opinion include header files should be used instead of writing own > declaration of functions. I agree. > > Make the example code easy to follow. > > > > Also, you forgot a license for this code, that is required if you want > > people to use it... > > Hm... I do not see any license in other manpage examples. Does not apply > for it global license defined in ioctl_tty.2 file? That does not mean you do not need it. thanks, greg k-h
On Thursday 05 August 2021 10:50:31 Greg Kroah-Hartman wrote: > On Thu, Aug 05, 2021 at 10:44:10AM +0200, Pali Rohár wrote: > > On Thursday 05 August 2021 10:30:15 Greg Kroah-Hartman wrote: > > > On Thu, Aug 05, 2021 at 10:22:43AM +0200, Pali Rohár wrote: > > > > On Thursday 05 August 2021 07:52:03 Greg Kroah-Hartman wrote: > > > > > On Thu, Aug 05, 2021 at 12:08:08AM +0200, Pali Rohár wrote: > > > > > > + linux-serial > > > > > > + Greg > > > > > > > > > > > > Greg, could I ask you for reviewing this documentation manpage patch? > > > > > > > > > > If it is submitted in a format I can review, sure (i.e. not top-post...) > > > > > > > > > > But I will dig down below to say one thing... > > > > > > > > > > > > > > > > > On Sunday 01 August 2021 15:51:45 Pali Rohár wrote: > > > > > > > Signed-off-by: Pali Rohár <pali@kernel.org> > > > > > > > > > > > > > > --- > > > > > > > Changes in v3: > > > > > > > * Check support for custom baudrate only based on BOTHER macro > > > > > > > * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available > > > > > > > > > > > > > > Changes in v2: > > > > > > > * Use \e for backslash > > > > > > > * Use exit(EXIT_*) instead of return num > > > > > > > * Sort includes > > > > > > > * Add comment about possible fallback > > > > > > > --- > > > > > > > > > > > > > > Hello Alejandro! > > > > > > > > > > > > > > I found out that this stuff is more complicated as I originally thought. > > > > > > > And seems that additional documentation on this topic is needed... > > > > > > > > > > > > > > For setting custom baudrate it is needed to set BOTHER flag in c_cflag > > > > > > > field and baudrate value itself in c_ospeed and c_ispeed fields. > > > > > > > > > > > > > > So when BOTHER flag is not provided by <asm/termbits.h> then setting custom > > > > > > > baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and > > > > > > > only some predefined Bnnn baudrate values are supported). This applies when > > > > > > > compiling application with older version of header files (prior support for > > > > > > > custom baudrate was introduced into header files). > > > > > > > > > > > > > > First caveat: BOTHER constant is different for different architectures. > > > > > > > So it is not possible to provide fallback #ifndef..#define BOTHER. > > > > > > > > > > > > > > And now the biggest issue: Some architectures have these c_ospeed and > > > > > > > c_ispeed fields in struct termios and some in struct termios2. > > > > > > > > > > > > > > TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use > > > > > > > struct termios2. > > > > > > > > > > > > > > Some architectures (e.g. amd64) provide both struct termios and struct > > > > > > > termios2, but c_ospeed and c_ispeed are only in struct termios2. > > > > > > > > > > > > > > Some other architectures (e.g. alpha) provide both struct termios and struct > > > > > > > termios2 and both have c_ospeed and c_ispeed fields. > > > > > > > > > > > > > > And some other architectures (e.g. powerpc) provide only struct termios > > > > > > > (no struct termios2) and it has c_ospeed and c_ispeed fields. > > > > > > > > > > > > > > So basically to support all architectures it is needed to use > > > > > > > struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed > > > > > > > to use struct termios with TCGETS/TCSETS (case for e.g. powerpc). > > > > > > > > > > > > > > I updated v3 patch to handle this logic. > > > > > > > --- > > > > > > > man2/ioctl_tty.2 | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ > > > > > > > 1 file changed, 73 insertions(+) > > > > > > > > > > > > > > diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2 > > > > > > > index 3020f9984872..d83cbd17225b 100644 > > > > > > > --- a/man2/ioctl_tty.2 > > > > > > > +++ b/man2/ioctl_tty.2 > > > > > > > @@ -764,6 +764,79 @@ main(void) > > > > > > > close(fd); > > > > > > > } > > > > > > > .EE > > > > > > > +.PP > > > > > > > +Get or set arbitrary baudrate on the serial port. > > > > > > > +.PP > > > > > > > +.EX > > > > > > > +#include <asm/termbits.h> > > > > > > > +#include <fcntl.h> > > > > > > > +#include <stdio.h> > > > > > > > +#include <stdlib.h> > > > > > > > +#include <sys/ioctl.h> > > > > > > > +#include <sys/types.h> > > > > > > > +#include <unistd.h> > > > > > > > + > > > > > > > +int > > > > > > > +main(int argc, char *argv[]) > > > > > > > +{ > > > > > > > +#ifndef BOTHER > > > > > > > + fprintf(stderr, "BOTHER is unsupported\en"); > > > > > > > + /* Program may fallback to TCGETS/TCSETS with Bnnn constants */ > > > > > > > + exit(EXIT_FAILURE); > > > > > > > > > > So this is a BOTHER test only? > > > > > > > > Yes. > > > > > > > > > What is the goal of this program? Don't throw a bunch of #ifdef in here > > > > > for no good reason. These options should all be present on all normal > > > > > kernels, why wouldn't they be? > > > > > > > > I wanted to provide complete example which compiles fine on all Linux > > > > systems, even with older include header files. I do not know right now > > > > in which kernel version was introduced BOTHER support for all > > > > architectures. > > > > > > We have all of the kernel source in a tool that would allow you to to > > > determine this quite easily :) > > > > > > > If BOHTER is not supported then it is possible to still use Bnnn > > > > constants to get / set baudrate. Just it is needed to write long code > > > > for converting number to suitable Bnnn constant. > > > > > > > > Do you think that this BOTHER check is not useful in this case? > > > > > > I think you should provide an example of how to use BOTHER, yes, as it > > > is hard to find good examples out there as they keep floating around. > > > > Exactly, and this is one of the reason why I sent this my patch for > > ioctl_tty.2. > > > > > Here's one that I point people to a lot: > > > https://github.com/GrantEdwards/Linux-arbitrary-baud > > > > I'm looking at this example at it has lot of problems: > > > > * Does not compile on powerpc (see explanation above). > > * Does not include <sys/ioctl.h> and instead provide open-coded > > declaration of ioctl: int ioctl(int d, int request, ...); > > * Does not handle case when TCGETS/TCSETS contains t.c_ospeed > > Great, then fix all of that :) It should have been already in this my patch which provides this example. That is why I asked for review from other people :-) > > In my opinion include header files should be used instead of writing own > > declaration of functions. > > I agree. > > > > Make the example code easy to follow. > > > > > > Also, you forgot a license for this code, that is required if you want > > > people to use it... > > > > Hm... I do not see any license in other manpage examples. Does not apply > > for it global license defined in ioctl_tty.2 file? > > That does not mean you do not need it. I will wait for Alejandro's reaction on this topic as I think he wants to have all manpages consistent and with the same style, headers, etc...
Hi Pali, On 8/5/21 11:51 AM, Pali Rohár wrote: >>>> Also, you forgot a license for this code, that is required if you want >>>> people to use it... >>> >>> Hm... I do not see any license in other manpage examples. Does not apply >>> for it global license defined in ioctl_tty.2 file? >> >> That does not mean you do not need it. I don't know what is the status of the current code examples in terms of licensing. I thought I had seen an SPDX license identifier in one of them some time ago, but now I can't find it. Technically, the pages have a license at the top of each file, which isn't printed on the rendered output (the license text doesn't require so) (see that text below). If you want a different license for your example (let's say you want it BSD for example), I guess you could add an SPDX line at the top of the example for simplicity. But if your code example adheres to the same license as the rest of the page, I guess you don't need to do anything in your patch. But I'm not sure at all; maybe Michael can tell you more about it. > > I will wait for Alejandro's reaction on this topic as I think he wants > to have all manpages consistent and with the same style, headers, etc... > Thanks! Alex --- $ head -n 26 man7/system_data_types.7 .\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com> .\" and Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com> .\" .\" %%%LICENSE_START(VERBATIM) .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" %%%LICENSE_END .\" .\"
On Thu, Aug 05, 2021 at 05:28:49PM +0200, Alejandro Colomar (man-pages) wrote: > Hi Pali, > > On 8/5/21 11:51 AM, Pali Rohár wrote: > > > > > Also, you forgot a license for this code, that is required if you want > > > > > people to use it... > > > > > > > > Hm... I do not see any license in other manpage examples. Does not apply > > > > for it global license defined in ioctl_tty.2 file? > > > > > > That does not mean you do not need it. > > I don't know what is the status of the current code examples in terms of > licensing. > > I thought I had seen an SPDX license identifier in one of them some time > ago, but now I can't find it. > > Technically, the pages have a license at the top of each file, which isn't > printed on the rendered output (the license text doesn't require so) (see > that text below). > > If you want a different license for your example (let's say you want it BSD > for example), I guess you could add an SPDX line at the top of the example > for simplicity. > > But if your code example adheres to the same license as the rest of the > page, I guess you don't need to do anything in your patch. What is the license of a man page? What is the license of this page? And if it is not shown in the code segment itself, that's going to be a mess, please make it explicit, otherwise no one can ever use any of the code examples for anything. thanks, greg k-h
Hi Greg, On 8/5/21 6:14 PM, Greg Kroah-Hartman wrote: > On Thu, Aug 05, 2021 at 05:28:49PM +0200, Alejandro Colomar (man-pages) wrote: >> Hi Pali, >> >> On 8/5/21 11:51 AM, Pali Rohár wrote: >>>>>> Also, you forgot a license for this code, that is required if you want >>>>>> people to use it... >>>>> >>>>> Hm... I do not see any license in other manpage examples. Does not apply >>>>> for it global license defined in ioctl_tty.2 file? >>>> >>>> That does not mean you do not need it. >> >> I don't know what is the status of the current code examples in terms of >> licensing. >> >> I thought I had seen an SPDX license identifier in one of them some time >> ago, but now I can't find it. >> >> Technically, the pages have a license at the top of each file, which isn't >> printed on the rendered output (the license text doesn't require so) (see >> that text below). >> >> If you want a different license for your example (let's say you want it BSD >> for example), I guess you could add an SPDX line at the top of the example >> for simplicity. >> >> But if your code example adheres to the same license as the rest of the >> page, I guess you don't need to do anything in your patch. > > What is the license of a man page? Typically, the one I showed in my last email (the "Verbatim" license"). See <https://www.kernel.org/doc/man-pages/licenses.html>. > > What is the license of this page? .../linux/man-pages$ head -n8 man2/ioctl_tty.2 .\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de> .\" and Andries Brouwer <aeb@cwi.nl>. .\" .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) .\" Distributed under GPL .\" %%%LICENSE_END .\" .TH IOCTL_TTY 2 2021-03-22 "Linux" "Linux Programmer's Manual" I'm don't know what GPL_NOVERSION_ONLINE is at all. CC += Walter, Andries > > And if it is not shown in the code segment itself, that's going to be a > mess, please make it explicit, otherwise no one can ever use any of the > code examples for anything. I'm not against that. At However, there's an explicit mention (without any rationale at all, or I couldn't find it) in man-pages(7) that the Linux man-pages project doesn't use the COPYRIGHT section: [ DESCRIPTION This page describes the conventions that should be employed when writing man pages for the Linux man‐pages project, which documents the user‐space API provided by the Linux kernel and the GNU C library. The project thus provides most of the pages in Section 2, many of the pages that ap‐ pear in Sections 3, 4, and 7, and a few of the pages that appear in Sections 1, 5, and 8 of the man pages on a Linux system. The conventions described on this page may also be useful for authors writing man pages for other projects. [...] Sections within a manual page The list below shows conventional or suggested sections. Most manual pages should include at least the highlighted sections. Arrange a new manual page so that sections are placed in the order shown in the list. [...] COPYRIGHT [Not used in man‐pages] ] [[man-pages(7)]] Maybe Michael can provide a rationale for this. Still, if the code is going to have a different license than the rest of the page, it could perfectly have an SPDX comment in the first line of the example program. Thanks, Alex
On Thu, Aug 05, 2021 at 06:45:57PM +0200, Alejandro Colomar (man-pages) wrote: > Hi Greg, > > On 8/5/21 6:14 PM, Greg Kroah-Hartman wrote: > > On Thu, Aug 05, 2021 at 05:28:49PM +0200, Alejandro Colomar (man-pages) wrote: > > > Hi Pali, > > > > > > On 8/5/21 11:51 AM, Pali Rohár wrote: > > > > > > > Also, you forgot a license for this code, that is required if you want > > > > > > > people to use it... > > > > > > > > > > > > Hm... I do not see any license in other manpage examples. Does not apply > > > > > > for it global license defined in ioctl_tty.2 file? > > > > > > > > > > That does not mean you do not need it. > > > > > > I don't know what is the status of the current code examples in terms of > > > licensing. > > > > > > I thought I had seen an SPDX license identifier in one of them some time > > > ago, but now I can't find it. > > > > > > Technically, the pages have a license at the top of each file, which isn't > > > printed on the rendered output (the license text doesn't require so) (see > > > that text below). > > > > > > If you want a different license for your example (let's say you want it BSD > > > for example), I guess you could add an SPDX line at the top of the example > > > for simplicity. > > > > > > But if your code example adheres to the same license as the rest of the > > > page, I guess you don't need to do anything in your patch. > > > > What is the license of a man page? > > Typically, the one I showed in my last email (the "Verbatim" license"). > See <https://www.kernel.org/doc/man-pages/licenses.html>. > > > > > What is the license of this page? > > .../linux/man-pages$ head -n8 man2/ioctl_tty.2 > .\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de> > .\" and Andries Brouwer <aeb@cwi.nl>. > .\" > .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) > .\" Distributed under GPL What version of GPL? > .\" %%%LICENSE_END > .\" > .TH IOCTL_TTY 2 2021-03-22 "Linux" "Linux Programmer's Manual" > > I'm don't know what GPL_NOVERSION_ONLINE is at all. I would recommend adding proper SPDX markings to all of these files. Even better, work to make the whole repo REUSE compliant which means that there is no ambuiguity here. But, the above license does not show up on the code in the original example here, and that needs to be present if anyone wants this to be used. > Still, if the code is going to have a different license than the rest of the > page, it could perfectly have an SPDX comment in the first line of the > example program. Even if it is different, it should still be present as no one can see the license of a man page "easily" when reading the documentation through normal tools. thanks, greg k-h
Hi Greg, Pali, Hi GregOn 8/5/21 7:54 PM, Greg Kroah-Hartman wrote: >>> What is the license of this page? >> >> .../linux/man-pages$ head -n8 man2/ioctl_tty.2 >> .\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de> >> .\" and Andries Brouwer <aeb@cwi.nl>. >> .\" >> .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) >> .\" Distributed under GPL > > What version of GPL? I don't know :/ Maybe v1... > >> .\" %%%LICENSE_END >> .\" >> .TH IOCTL_TTY 2 2021-03-22 "Linux" "Linux Programmer's Manual" >> >> I'm don't know what GPL_NOVERSION_ONLINE is at all. > > I would recommend adding proper SPDX markings to all of these files. > Even better, work to make the whole repo REUSE compliant which means > that there is no ambuiguity here. > Agree. If Michael has no problems with that, I'll add it to my TODO list. > But, the above license does not show up on the code in the original > example here, and that needs to be present if anyone wants this to be > used. Yup. > >> Still, if the code is going to have a different license than the rest of the >> page, it could perfectly have an SPDX comment in the first line of the >> example program. > > Even if it is different, it should still be present as no one can see > the license of a man page "easily" when reading the documentation > through normal tools. Yup. > > thanks, > > greg k-h > Pali, If you want to specify a specific license for your code, add 2 SPDX lines according to REUSE <https://reuse.software/>. If not, I'll assume that you don't care, and when I fix the pages to show the license (which in this case I'm not sure which one will be, maybe GPLv1) your code will use that same license. I'll take care of any necessary adjustments such as providing the license text in the repository; you don't need to do that. Cheers, Alex
On Friday 06 August 2021 09:22:59 Alejandro Colomar (man-pages) wrote: > Hi Greg, Pali, > > Hi GregOn 8/5/21 7:54 PM, Greg Kroah-Hartman wrote: > > > > What is the license of this page? > > > > > > .../linux/man-pages$ head -n8 man2/ioctl_tty.2 > > > .\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de> > > > .\" and Andries Brouwer <aeb@cwi.nl>. > > > .\" > > > .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) > > > .\" Distributed under GPL > > > > What version of GPL? > > I don't know :/ > Maybe v1... > > > > > > .\" %%%LICENSE_END > > > .\" > > > .TH IOCTL_TTY 2 2021-03-22 "Linux" "Linux Programmer's Manual" > > > > > > I'm don't know what GPL_NOVERSION_ONLINE is at all. > > > > I would recommend adding proper SPDX markings to all of these files. > > Even better, work to make the whole repo REUSE compliant which means > > that there is no ambuiguity here. > > > > Agree. If Michael has no problems with that, I'll add it to my TODO list. > > > But, the above license does not show up on the code in the original > > example here, and that needs to be present if anyone wants this to be > > used. > > Yup. > > > > > > Still, if the code is going to have a different license than the rest of the > > > page, it could perfectly have an SPDX comment in the first line of the > > > example program. > > > > Even if it is different, it should still be present as no one can see > > the license of a man page "easily" when reading the documentation > > through normal tools. > > Yup. > > > > > thanks, > > > > greg k-h > > > > Pali, > > If you want to specify a specific license for your code, add 2 SPDX lines > according to REUSE <https://reuse.software/>. If not, I'll assume that you > don't care, and when I fix the pages to show the license (which in this case > I'm not sure which one will be, maybe GPLv1) your code will use that same > license. I'll take care of any necessary adjustments such as providing the > license text in the repository; you don't need to do that. Just do not complicate it and use same license as for other manpages or examples. > > Cheers, > > Alex > > > -- > Alejandro Colomar > Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ > http://www.alejandro-colomar.es/
Hi Pali, On 8/1/21 3:51 PM, Pali Rohár wrote: > Signed-off-by: Pali Rohár <pali@kernel.org> > > --- > Changes in v3: > * Check support for custom baudrate only based on BOTHER macro > * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available > > Changes in v2: > * Use \e for backslash > * Use exit(EXIT_*) instead of return num > * Sort includes > * Add comment about possible fallback > --- > > Hello Alejandro! > > I found out that this stuff is more complicated as I originally thought. > And seems that additional documentation on this topic is needed... > > For setting custom baudrate it is needed to set BOTHER flag in c_cflag > field and baudrate value itself in c_ospeed and c_ispeed fields. > > So when BOTHER flag is not provided by <asm/termbits.h> then setting custom > baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and > only some predefined Bnnn baudrate values are supported). This applies when > compiling application with older version of header files (prior support for > custom baudrate was introduced into header files). > > First caveat: BOTHER constant is different for different architectures. > So it is not possible to provide fallback #ifndef..#define BOTHER. > > And now the biggest issue: Some architectures have these c_ospeed and > c_ispeed fields in struct termios and some in struct termios2. > > TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use > struct termios2. > > Some architectures (e.g. amd64) provide both struct termios and struct > termios2, but c_ospeed and c_ispeed are only in struct termios2. > > Some other architectures (e.g. alpha) provide both struct termios and struct > termios2 and both have c_ospeed and c_ispeed fields. > > And some other architectures (e.g. powerpc) provide only struct termios > (no struct termios2) and it has c_ospeed and c_ispeed fields. > > So basically to support all architectures it is needed to use > struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed > to use struct termios with TCGETS/TCSETS (case for e.g. powerpc). When you send v4, please include the above text (or something similar) to the commit message. Thanks, Alex > > I updated v3 patch to handle this logic. > ---
On Sunday 08 August 2021 10:35:24 Alejandro Colomar (man-pages) wrote: > Hi Pali, > > On 8/1/21 3:51 PM, Pali Rohár wrote: > > Signed-off-by: Pali Rohár <pali@kernel.org> > > > > --- > > Changes in v3: > > * Check support for custom baudrate only based on BOTHER macro > > * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available > > > > Changes in v2: > > * Use \e for backslash > > * Use exit(EXIT_*) instead of return num > > * Sort includes > > * Add comment about possible fallback > > --- > > > > Hello Alejandro! > > > > I found out that this stuff is more complicated as I originally thought. > > And seems that additional documentation on this topic is needed... > > > > For setting custom baudrate it is needed to set BOTHER flag in c_cflag > > field and baudrate value itself in c_ospeed and c_ispeed fields. > > > > So when BOTHER flag is not provided by <asm/termbits.h> then setting custom > > baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and > > only some predefined Bnnn baudrate values are supported). This applies when > > compiling application with older version of header files (prior support for > > custom baudrate was introduced into header files). > > > > First caveat: BOTHER constant is different for different architectures. > > So it is not possible to provide fallback #ifndef..#define BOTHER. > > > > And now the biggest issue: Some architectures have these c_ospeed and > > c_ispeed fields in struct termios and some in struct termios2. > > > > TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use > > struct termios2. > > > > Some architectures (e.g. amd64) provide both struct termios and struct > > termios2, but c_ospeed and c_ispeed are only in struct termios2. > > > > Some other architectures (e.g. alpha) provide both struct termios and struct > > termios2 and both have c_ospeed and c_ispeed fields. > > > > And some other architectures (e.g. powerpc) provide only struct termios > > (no struct termios2) and it has c_ospeed and c_ispeed fields. > > > > So basically to support all architectures it is needed to use > > struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed > > to use struct termios with TCGETS/TCSETS (case for e.g. powerpc). > > When you send v4, please include the above text (or something similar) to > the commit message. Hello Alejandro! Sure I will put description into commit message. Moreover this kind of information should be properly documented into ioctl_tty.2 manpage itself. But I really do not know in which part. Into ioctl (and which?)? Or separate paragraph? As it basically describe some field of struct termios and struct termios2, which are undocumented too. Do you have some idea or picture how such thing should be properly documented in man-pages project? > Thanks, > > Alex > > > > > I updated v3 patch to handle this logic. > > --- > > > -- > Alejandro Colomar > Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ > http://www.alejandro-colomar.es/
Hi Pali, On 8/8/21 11:05 PM, Pali Rohár wrote: >> When you send v4, please include the above text (or something similar) to >> the commit message. > > Hello Alejandro! Sure I will put description into commit message. > > Moreover this kind of information should be properly documented into > ioctl_tty.2 manpage itself. But I really do not know in which part. Into > ioctl (and which?)? Or separate paragraph? As it basically describe some > field of struct termios and struct termios2, which are undocumented too. > > Do you have some idea or picture how such thing should be properly > documented in man-pages project? Being documentation for a type, I think the best place for that is system_data_types(7) <https://man7.org/linux/man-pages/man7/system_data_types.7.html>. Do you feel like writing that? See the thread we started the other day: <https://lore.kernel.org/linux-man/5e9e1f1a-1e08-59f5-6579-a02c0738b9a4@gmail.com/T/#u> You can also get some inspiration from other pages that also define types, like stat(2), and sigevent(7). Thanks, Alex
diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2 index 3020f9984872..d83cbd17225b 100644 --- a/man2/ioctl_tty.2 +++ b/man2/ioctl_tty.2 @@ -764,6 +764,79 @@ main(void) close(fd); } .EE +.PP +Get or set arbitrary baudrate on the serial port. +.PP +.EX +#include <asm/termbits.h> +#include <fcntl.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/ioctl.h> +#include <sys/types.h> +#include <unistd.h> + +int +main(int argc, char *argv[]) +{ +#ifndef BOTHER + fprintf(stderr, "BOTHER is unsupported\en"); + /* Program may fallback to TCGETS/TCSETS with Bnnn constants */ + exit(EXIT_FAILURE); +#else +#ifdef TCGETS2 + struct termios2 tio; +#else + struct termios tio; +#endif + int fd, rc; + + if (argc != 2 && argc != 3) { + fprintf(stderr, "Usage: %s device [new_baudrate]\en", argv[0]); + exit(EXIT_FAILURE); + } + + fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY); + if (fd < 0) { + perror("open"); + exit(EXIT_FAILURE); + } + +#ifdef TCGETS2 + rc = ioctl(fd, TCGETS2, &tio); +#else + rc = ioctl(fd, TCGETS, &tio); +#endif + if (rc) { + perror("TCGETS"); + close(fd); + exit(EXIT_FAILURE); + } + + printf("%u\en", tio.c_ospeed); + + if (argc == 3) { + tio.c_cflag &= ~CBAUD; + tio.c_cflag |= BOTHER; + tio.c_ospeed = tio.c_ispeed = atoi(argv[2]); + +#ifdef TCSETS2 + rc = ioctl(fd, TCSETS2, &tio); +#else + rc = ioctl(fd, TCSETS, &tio); +#endif + if (rc) { + perror("TCSETS"); + close(fd); + exit(EXIT_FAILURE); + } + } + + close(fd); + exit(EXIT_SUCCESS); +#endif +} +.EE .SH SEE ALSO .BR ldattach (1), .BR ioctl (2),
Signed-off-by: Pali Rohár <pali@kernel.org> --- Changes in v3: * Check support for custom baudrate only based on BOTHER macro * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available Changes in v2: * Use \e for backslash * Use exit(EXIT_*) instead of return num * Sort includes * Add comment about possible fallback --- Hello Alejandro! I found out that this stuff is more complicated as I originally thought. And seems that additional documentation on this topic is needed... For setting custom baudrate it is needed to set BOTHER flag in c_cflag field and baudrate value itself in c_ospeed and c_ispeed fields. So when BOTHER flag is not provided by <asm/termbits.h> then setting custom baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and only some predefined Bnnn baudrate values are supported). This applies when compiling application with older version of header files (prior support for custom baudrate was introduced into header files). First caveat: BOTHER constant is different for different architectures. So it is not possible to provide fallback #ifndef..#define BOTHER. And now the biggest issue: Some architectures have these c_ospeed and c_ispeed fields in struct termios and some in struct termios2. TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use struct termios2. Some architectures (e.g. amd64) provide both struct termios and struct termios2, but c_ospeed and c_ispeed are only in struct termios2. Some other architectures (e.g. alpha) provide both struct termios and struct termios2 and both have c_ospeed and c_ispeed fields. And some other architectures (e.g. powerpc) provide only struct termios (no struct termios2) and it has c_ospeed and c_ispeed fields. So basically to support all architectures it is needed to use struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed to use struct termios with TCGETS/TCSETS (case for e.g. powerpc). I updated v3 patch to handle this logic. --- man2/ioctl_tty.2 | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+)