On 18.04.24 04:02, Chris Johns wrote:
On 17/4/2024 11:06 pm, Sebastian Huber wrote:Make the kernel I/O output character device processing configurable through an option set parameter. Add RTEMS_NO_OUTPUT and RTEMS_FLUSH options. The goal of this API change is to enable flushing the kernel output device in the system termination process before a reset is issued. A use case for using RTEMS_NO_WAIT is the polled processing of an input and output stream from and to the I/O device.Thanks for providing this overview. I am still confused about the differences in terms of why you would need the RTEMS_NO_WAIT. Do you have a specific application where this is required? It might help me understand the need for the change? Examples are need to reset in a specific period, a test mode you are running in a system, etc?
The RTEMS_NO_WAIT can be used to process an input stream using getchark() and then send responses using a non-blocking output char variant. This helps to have enough processing time and allows an overlapping send/receive.
Is this change for RTEMS 7?
Yes, this would be good.
In the context of the change: 1. RTEMS_FLUSH etc are too generic.
I added them to <rtems/rtems/options.h>, so they could be reused in other directives. A bit less generic names could be:
* RTEMS_IO_FLUSH * RTEMS_IO_DRAIN * RTEMS_IO_NO_OUTPUTThis would be in the IO namespace similar to RTEMS_EVENT_ANY and RTEMS_EVENT_ALL.
2. The language used needs some work, maybe fewer "while"s. For example: While the #RTEMS_NO_WAIT option is set in the option_set parameter, while the #RTEMS_NO_OUTPUT option is cleared in the option_set parameter, while the device can immediately accept a character for output, the character in out shall be hand over to the device for output. This is difficult to read and when it is probability easier to read the code it is of questionable value. I appreciate it is not always easy to write but I feel clarity would be a good to have here.
This is the documentation of a function pointer type, so there is no direct code. With three flags, you have to specify for eight variants what should happen. The wording is in EARS. It should be easy to translate this into code for a particular device.
https://docs.rtems.org/branches/master/eng/req/req-for-req.html#syntax
Another example: While no character is available in the device, a polled character input functions shall return minus one. It could be written as: A polled character input function shall return a character if the device has successfully received one else the function returns minus one.
I would prefer the EARS variant. This function type should define requirements for the associated implementations.
I think receive and transmit is better than for example "be hand over to the device for output", maybe "shall be transmitted by the device".
The name of this function type is BSP_output_char_function_type and not BSP_transmit_char_function_type, so I used "output" here and not "transmit". Also, the character may not get immediately transmitted if FIFOs are involved (thus the need for the flush). Maybe my understanding of transmitted is wrong, but for me transmitting has something to do with signals on a medium.
3. Flush needs to be worded in terms of successfully transmitted by the device to avoid the case of data being written to the device is held in FIFOs awaiting transmission and reset is asserted. Maybe FLUSH is the wrong term because it is so overloaded in what it means? An alternative could be RTEMS_BSP_IO_TRANSMISSION_COMPLETE? And following on you could have RTEMS_BSP_IO_NO_TRANSMISSION? The key point is "transmission" relates to the external data pin of the interface.
The no-output option is used to just flush the device without transmitting a new character. For the flush, we could add something like this:
Flushing the device should ensure that all characters handed over to the device for output are visible to external consumers. For example, the device output FIFO and transmit shift registers should be empty.
Chris--- cpukit/include/rtems/bspIo.h | 50 ++++++++++++++++++++++++++-- cpukit/include/rtems/rtems/options.h | 20 ++++++++++- 2 files changed, 67 insertions(+), 3 deletions(-) diff --git a/cpukit/include/rtems/bspIo.h b/cpukit/include/rtems/bspIo.h index 31580cd800..09a3c47243 100644 --- a/cpukit/include/rtems/bspIo.h +++ b/cpukit/include/rtems/bspIo.h @@ -10,7 +10,7 @@ *//*- * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG + * Copyright (C) 2020, 2024 embedded brains GmbH & Co. KG * Copyright (C) 2015 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -58,6 +58,8 @@ #define _RTEMS_BSPIO_H#include <stdarg.h>+#include <rtems/rtems/options.h> +#include <rtems/rtems/status.h> #include <rtems/score/basedefs.h>#ifdef __cplusplus@@ -89,8 +91,42 @@ extern "C" { * @ingroup RTEMSAPIKernelCharIO * * @brief Polled character output functions shall have this type. + * + * @param out is the character to output. + * + * @param option_set is the option set. + * + * While the #RTEMS_NO_WAIT option is set in the option_set parameter, while + * the device cannot immediately accept a character for output, the character + * in out shall not be hand over to the device for output, optionally the + * device output shall be flushed, and ::RTEMS_UNSATISFIED shall be returned. + * + * While the #RTEMS_NO_OUTPUT option is set in the option_set parameter, the + * character in the out parameter shall not be handed over to the device for + * output. + * + * While the #RTEMS_NO_WAIT option is cleared in the option_set parameter, + * while the #RTEMS_NO_OUTPUT option is cleared in the option_set parameter, + * the character in the out parameter shall be hand over to the device for + * output. + * + * While the #RTEMS_NO_WAIT option is set in the option_set parameter, while + * the #RTEMS_NO_OUTPUT option is cleared in the option_set parameter, while + * the device can immediately accept a character for output, the character in + * out shall be hand over to the device for output. + * + * While the #RTEMS_FLUSH option is set in the option_set parameter, the device + * output shall be flushed before the function returns. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_UNSATISFIED The device is was not ready to output a + * character. */ -typedef void ( *BSP_output_char_function_type )( char ); +typedef rtems_status_code ( *BSP_output_char_function_type )( + char out, + rtems_option option_set +);/* Generated from spec:/rtems/io/if/bsp-output-char */ @@ -333,6 +369,16 @@ int rtems_printk_printer( void *unused, const char *fmt, va_list ap );* @ingroup RTEMSAPIKernelCharIO * * @brief Polled character input functions shall have this type. + * + * While a character is available in the device, a polled character input + * function shall return the least recently received character as an unsigned + * character. While no character is available in the device, a polled + * character input functions shall return minus one. + * + * @retval -1 There was no input character available in the device. + * + * @return Returns the least recently received character available in the + * device as an unsigned character. */ typedef int (* BSP_polling_getchar_function_type )( void );diff --git a/cpukit/include/rtems/rtems/options.h b/cpukit/include/rtems/rtems/options.hindex 44a8d6ccb8..3522fc4fcd 100644 --- a/cpukit/include/rtems/rtems/options.h +++ b/cpukit/include/rtems/rtems/options.h @@ -9,7 +9,7 @@ *//*- * Copyright (C) 2020 embedded brains GmbH & Co. KG + * Copyright (C) 2020, 2024 embedded brains GmbH & Co. KG * Copyright (C) 1989, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -103,6 +103,24 @@ extern "C" { */ #define RTEMS_EVENT_ANY 0x00000002+/* Generated from spec:/rtems/option/if/flush */+ +/** + * @ingroup RTEMSAPIClassicOptions + * + * @brief This option constant indicates that something shall be flushed. + */ +#define RTEMS_FLUSH 0x00000008 + +/* Generated from spec:/rtems/option/if/no-output */ + +/** + * @ingroup RTEMSAPIClassicOptions + * + * @brief This option constant indicates that the nothing shall be output. + */ +#define RTEMS_NO_OUTPUT 0x00000004 + /* Generated from spec:/rtems/option/if/no-wait *//**
-- embedded brains GmbH & Co. KG Herr Sebastian HUBER Dornierstr. 4 82178 Puchheim Germany email: sebastian.hu...@embedded-brains.de phone: +49-89-18 94 741 - 16 fax: +49-89-18 94 741 - 08 Registergericht: Amtsgericht München Registernummer: HRB 157899 Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler Unsere Datenschutzerklärung finden Sie hier: https://embedded-brains.de/datenschutzerklaerung/ _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
