[Xenomai-help] Selecting the appropriate RTDM _rt/_nrt ioctl at run-time.

[Xenomai-help] Selecting the appropriate RTDM _rt/_nrt ioctl at run-time.

[Martin Shepherd]

I'm in the process of writing an RTDM device driver. Some of the ioctl
requests that it implements can only be executed from non-realtime
context, due to the need for them to call Linux kernel functions,
while other ioctl requests are context-agnostic, but are intended to
be used from realtime context.

At first glance the RTDM documentation appears to indicate that I
should implement the ioctl requests that require non-realtime context
in the ioctl_nrt() handler of the driver, and implement the remaining
context-agnostic requests in both the ioctl_nrt() and ioctl_rt()
handlers. However for this to work transparently, RTDM would have to
know which request codes were implemented by ioctl_nrt() and which by
ioctl_rt(), then automatically switch context, if needed, before
calling them.  I don't see anything implemented along these lines.

In principle I could tell application writers that they have to
explicitly switch to the secondary linux domain before calling
rt_dev_ioctl() for a request that requires this. However I don't see
any RTDM or Xenomai user-API call for switching contexts (other than
xnshadown_relax(), which is marked as for internal use only). I
imagine that one could do the equivalent by calling something like
sleep(0) to force a switch to the Linux domain. But this seems like a
kludge.

Am I missing something obvious?

Thanks,

Martin

Re: [Xenomai-help] Selecting the appropriate RTDM _rt/_nrt ioctl at run-time.

[Sebastian Smolorz]

Martin Shepherd wrote:
> I'm in the process of writing an RTDM device driver. Some of the ioctl
> requests that it implements can only be executed from non-realtime
> context, due to the need for them to call Linux kernel functions,
> while other ioctl requests are context-agnostic, but are intended to
> be used from realtime context.
>
> At first glance the RTDM documentation appears to indicate that I
> should implement the ioctl requests that require non-realtime context
> in the ioctl_nrt() handler of the driver, and implement the remaining
> context-agnostic requests in both the ioctl_nrt() and ioctl_rt()
> handlers. However for this to work transparently, RTDM would have to
> know which request codes were implemented by ioctl_nrt() and which by
> ioctl_rt(), then automatically switch context, if needed, before
> calling them.  I don't see anything implemented along these lines.
>
> In principle I could tell application writers that they have to
> explicitly switch to the secondary linux domain before calling
> rt_dev_ioctl() for a request that requires this.

Generally speaking, it is a bad habit to explicitely switch the context in 
applications.

> However I don't see
> any RTDM or Xenomai user-API call for switching contexts (other than
> xnshadown_relax(), which is marked as for internal use only). I
> imagine that one could do the equivalent by calling something like
> sleep(0) to force a switch to the Linux domain. But this seems like a
> kludge.
>
> Am I missing something obvious?

Could the function rtdm_in_rt_context() be useful for you?

-- 
Sebastian

Re: [Xenomai-help] Selecting the appropriate RTDM _rt/_nrt ioctl at run-time.

[Jan Kiszka]

Martin Shepherd wrote:
> I'm in the process of writing an RTDM device driver. Some of the ioctl
> requests that it implements can only be executed from non-realtime
> context, due to the need for them to call Linux kernel functions,
> while other ioctl requests are context-agnostic, but are intended to
> be used from realtime context.
> 
> At first glance the RTDM documentation appears to indicate that I
> should implement the ioctl requests that require non-realtime context
> in the ioctl_nrt() handler of the driver, and implement the remaining
> context-agnostic requests in both the ioctl_nrt() and ioctl_rt()
> handlers. However for this to work transparently, RTDM would have to
> know which request codes were implemented by ioctl_nrt() and which by
> ioctl_rt(), then automatically switch context, if needed, before
> calling them.  I don't see anything implemented along these lines.
> 
> In principle I could tell application writers that they have to
> explicitly switch to the secondary linux domain before calling
> rt_dev_ioctl() for a request that requires this. However I don't see
> any RTDM or Xenomai user-API call for switching contexts (other than
> xnshadown_relax(), which is marked as for internal use only). I
> imagine that one could do the equivalent by calling something like
> sleep(0) to force a switch to the Linux domain. But this seems like a
> kludge.
> 
> Am I missing something obvious?

Maybe you want to study ksrc/drivers/serial16550A.c a bit. It comes with
some (IOCTL) use cases that should be similar to yours.

Jan

-- 
Siemens AG, Corporate Technology, CT SE 2
Corporate Competence Center Embedded Linux

Re: [Xenomai-help] Selecting the appropriate RTDM _rt/_nrt ioctl at run-time.

[Martin Shepherd]

On Thu, 7 May 2009, Jan Kiszka wrote:
> Maybe you want to study ksrc/drivers/serial16550A.c a bit. It comes with
> some (IOCTL) use cases that should be similar to yours.

Yes I'd noticed that there was an ioctl request in that code that
returned -ENOSYS when that request couldn't be serviced in the current
context, but I didn't realize that this was doing anything other than
pushing the problem back on the application, by making the
application's call to rt_dev_ioctl() fail with a -ENOSYS error.

However today I went through the code that implements the syscall
interfacing between RTDM and Xenomai, and I discovered that RTDM uses
the __xn_exec_adaptive system-call flag to tell Xenomai to restart
RTDM system calls that return -ENOSYS. So I now realize that in your
serial driver, returning -ENOSYS wasn't pushing the problem back on
the user, as I thought, but rather remedying the situation by
requesting that Xenomai call the ioctl() again from the opposite
context. This really needs to be documented, not only for those people
who like myself need to know how to use -ENOSYS in this way, but also
to prevent people from innocently returning -ENOSYS for some other
error condition, and then wondering why on earth Xenomai calls the
failed handler twice.

Just to check that I haven't misunderstood anything, am I correct in
saying that if my ioctl() returns -ENOSYS, then Xenomai will re-run
the ioctl() from the opposite realtime or non-realtime context?

Assuming that the above is true, the following is a patch to update
the doxygen documentation embedded in rtdm_driver.h, to document the
special meaning of returning -ENOSYS. This patch was performed against
a newly cloned copy of xenomai-head.

diff -Naur xenomai-head/include/rtdm/rtdm_driver.h xenomai-head-edited/include/rtdm/rtdm_driver.h
--- xenomai-head/include/rtdm/rtdm_driver.h	2009-05-07 15:57:59.000000000 -0700
+++ xenomai-head-edited/include/rtdm/rtdm_driver.h	2009-05-07 15:30:20.000000000 -0700
@@ -159,7 +159,9 @@
   * NULL if kernel mode call
   * @param[in] oflag Open flags as passed by the user
   *
- * @return 0 on success, otherwise negative error code
+ * @return 0 on success. On failure return either -ENOSYS, to request that
+ * this handler be called again from the opposite realtime/non-realtime
+ * context, or another negative error code.
   *
   * @see @c open() in IEEE Std 1003.1,
   * http://www.opengroup.org/onlinepubs/009695399 */
@@ -174,7 +176,9 @@
   * NULL if kernel mode call
   * @param[in] protocol Protocol number as passed by the user
   *
- * @return 0 on success, otherwise negative error code
+ * @return 0 on success. On failure return either -ENOSYS, to request that
+ * this handler be called again from the opposite realtime/non-realtime
+ * context, or another negative error code.
   *
   * @see @c socket() in IEEE Std 1003.1,
   * http://www.opengroup.org/onlinepubs/009695399 */
@@ -188,7 +192,9 @@
   * @param[in] user_info Opaque pointer to information about user mode caller,
   * NULL if kernel mode call
   *
- * @return 0 on success, otherwise negative error code
+ * @return 0 on success. On failure return either -ENOSYS, to request that
+ * this handler be called again from the opposite realtime/non-realtime
+ * context, or another negative error code.
   *
   * @see @c close() in IEEE Std 1003.1,
   * http://www.opengroup.org/onlinepubs/009695399 */
@@ -204,7 +210,9 @@
   * @param[in] request Request number as passed by the user
   * @param[in,out] arg Request argument as passed by the user
   *
- * @return Positiv value on success, otherwise negative error code
+ * @return A positive value or 0 on success. On failure return either
+ * -ENOSYS, to request that the function be called again from the opposite
+ * realtime/non-realtime context, or another negative error code.
   *
   * @see @c ioctl() in IEEE Std 1003.1,
   * http://www.opengroup.org/onlinepubs/009695399 */
@@ -221,7 +229,9 @@
   * @param[in] fd_index Opaque value, to be passed to rtdm_event_select_bind or
   * rtdm_sem_select_bind unmodfied
   *
- * @return 0 on success, otherwise negative error code
+ * @return 0 on success. On failure return either -ENOSYS, to request that
+ * this handler be called again from the opposite realtime/non-realtime
+ * context, or another negative error code.
   */
  typedef int (*rtdm_select_bind_handler_t)(struct rtdm_dev_context *context,
  					  rtdm_selector_t *selector,
@@ -237,7 +247,9 @@
   * @param[out] buf Input buffer as passed by the user
   * @param[in] nbyte Number of bytes the user requests to read
   *
- * @return On success, the number of bytes read, otherwise negative error code
+ * @return On success, the number of bytes read. On failure return either
+ * -ENOSYS, to request that this handler be called again from the opposite
+ * realtime/non-realtime context, or another negative error code.
   *
   * @see @c read() in IEEE Std 1003.1,
   * http://www.opengroup.org/onlinepubs/009695399 */
@@ -254,8 +266,9 @@
   * @param[in] buf Output buffer as passed by the user
   * @param[in] nbyte Number of bytes the user requests to write
   *
- * @return On success, the number of bytes written, otherwise negative error
- * code
+ * @return On success, the number of bytes written. On failure return
+ * either -ENOSYS, to request that this handler be called again from the
+ * opposite realtime/non-realtime context, or another negative error code.
   *
   * @see @c write() in IEEE Std 1003.1,
   * http://www.opengroup.org/onlinepubs/009695399 */
@@ -273,8 +286,9 @@
   * mirrored to safe kernel memory in case of user mode call
   * @param[in] flags Message flags as passed by the user
   *
- * @return On success, the number of bytes received, otherwise negative error
- * code
+ * @return On success, the number of bytes received. On failure return
+ * either -ENOSYS, to request that this handler be called again from the
+ * opposite realtime/non-realtime context, or another negative error code.
   *
   * @see @c recvmsg() in IEEE Std 1003.1,
   * http://www.opengroup.org/onlinepubs/009695399 */
@@ -292,8 +306,9 @@
   * mirrored to safe kernel memory in case of user mode call
   * @param[in] flags Message flags as passed by the user
   *
- * @return On success, the number of bytes transmitted, otherwise negative
- * error code
+ * @return On success, the number of bytes transmitted. On failure return
+ * either -ENOSYS, to request that this handler be called again from the
+ * opposite realtime/non-realtime context, or another negative error code.
   *
   * @see @c sendmsg() in IEEE Std 1003.1,
   * http://www.opengroup.org/onlinepubs/009695399 */

Re: [Xenomai-help] Selecting the appropriate RTDM _rt/_nrt ioctl at run-time.

[Jan Kiszka]

[-- Attachment #1: Type: text/plain, Size: 7370 bytes --]

Martin Shepherd wrote:
> On Thu, 7 May 2009, Jan Kiszka wrote:
>> Maybe you want to study ksrc/drivers/serial16550A.c a bit. It comes with
>> some (IOCTL) use cases that should be similar to yours.
> 
> Yes I'd noticed that there was an ioctl request in that code that
> returned -ENOSYS when that request couldn't be serviced in the current
> context, but I didn't realize that this was doing anything other than
> pushing the problem back on the application, by making the
> application's call to rt_dev_ioctl() fail with a -ENOSYS error.
> 
> However today I went through the code that implements the syscall
> interfacing between RTDM and Xenomai, and I discovered that RTDM uses
> the __xn_exec_adaptive system-call flag to tell Xenomai to restart
> RTDM system calls that return -ENOSYS. So I now realize that in your
> serial driver, returning -ENOSYS wasn't pushing the problem back on
> the user, as I thought, but rather remedying the situation by
> requesting that Xenomai call the ioctl() again from the opposite
> context. This really needs to be documented, not only for those people
> who like myself need to know how to use -ENOSYS in this way, but also
> to prevent people from innocently returning -ENOSYS for some other
> error condition, and then wondering why on earth Xenomai calls the
> failed handler twice.
> 
> Just to check that I haven't misunderstood anything, am I correct in
> saying that if my ioctl() returns -ENOSYS, then Xenomai will re-run
> the ioctl() from the opposite realtime or non-realtime context?

Yes, that is the idea. BTW, the same effect is achieved by leaving a
callback pointer NULL.

> 
> Assuming that the above is true, the following is a patch to update
> the doxygen documentation embedded in rtdm_driver.h, to document the
> special meaning of returning -ENOSYS. This patch was performed against
> a newly cloned copy of xenomai-head.
> 
> diff -Naur xenomai-head/include/rtdm/rtdm_driver.h xenomai-head-edited/include/rtdm/rtdm_driver.h
> --- xenomai-head/include/rtdm/rtdm_driver.h	2009-05-07 15:57:59.000000000 -0700
> +++ xenomai-head-edited/include/rtdm/rtdm_driver.h	2009-05-07 15:30:20.000000000 -0700
> @@ -159,7 +159,9 @@
>    * NULL if kernel mode call
>    * @param[in] oflag Open flags as passed by the user
>    *
> - * @return 0 on success, otherwise negative error code
> + * @return 0 on success. On failure return either -ENOSYS, to request that
> + * this handler be called again from the opposite realtime/non-realtime
> + * context, or another negative error code.
>    *
>    * @see @c open() in IEEE Std 1003.1,
>    * http://www.opengroup.org/onlinepubs/009695399 */
> @@ -174,7 +176,9 @@
>    * NULL if kernel mode call
>    * @param[in] protocol Protocol number as passed by the user
>    *
> - * @return 0 on success, otherwise negative error code
> + * @return 0 on success. On failure return either -ENOSYS, to request that
> + * this handler be called again from the opposite realtime/non-realtime
> + * context, or another negative error code.
>    *
>    * @see @c socket() in IEEE Std 1003.1,
>    * http://www.opengroup.org/onlinepubs/009695399 */
> @@ -188,7 +192,9 @@
>    * @param[in] user_info Opaque pointer to information about user mode caller,
>    * NULL if kernel mode call
>    *
> - * @return 0 on success, otherwise negative error code
> + * @return 0 on success. On failure return either -ENOSYS, to request that
> + * this handler be called again from the opposite realtime/non-realtime
> + * context, or another negative error code.
>    *
>    * @see @c close() in IEEE Std 1003.1,
>    * http://www.opengroup.org/onlinepubs/009695399 */
> @@ -204,7 +210,9 @@
>    * @param[in] request Request number as passed by the user
>    * @param[in,out] arg Request argument as passed by the user
>    *
> - * @return Positiv value on success, otherwise negative error code
> + * @return A positive value or 0 on success. On failure return either
> + * -ENOSYS, to request that the function be called again from the opposite
> + * realtime/non-realtime context, or another negative error code.
>    *
>    * @see @c ioctl() in IEEE Std 1003.1,
>    * http://www.opengroup.org/onlinepubs/009695399 */
> @@ -221,7 +229,9 @@
>    * @param[in] fd_index Opaque value, to be passed to rtdm_event_select_bind or
>    * rtdm_sem_select_bind unmodfied
>    *
> - * @return 0 on success, otherwise negative error code
> + * @return 0 on success. On failure return either -ENOSYS, to request that
> + * this handler be called again from the opposite realtime/non-realtime
> + * context, or another negative error code.
>    */
>   typedef int (*rtdm_select_bind_handler_t)(struct rtdm_dev_context *context,
>   					  rtdm_selector_t *selector,
> @@ -237,7 +247,9 @@
>    * @param[out] buf Input buffer as passed by the user
>    * @param[in] nbyte Number of bytes the user requests to read
>    *
> - * @return On success, the number of bytes read, otherwise negative error code
> + * @return On success, the number of bytes read. On failure return either
> + * -ENOSYS, to request that this handler be called again from the opposite
> + * realtime/non-realtime context, or another negative error code.
>    *
>    * @see @c read() in IEEE Std 1003.1,
>    * http://www.opengroup.org/onlinepubs/009695399 */
> @@ -254,8 +266,9 @@
>    * @param[in] buf Output buffer as passed by the user
>    * @param[in] nbyte Number of bytes the user requests to write
>    *
> - * @return On success, the number of bytes written, otherwise negative error
> - * code
> + * @return On success, the number of bytes written. On failure return
> + * either -ENOSYS, to request that this handler be called again from the
> + * opposite realtime/non-realtime context, or another negative error code.
>    *
>    * @see @c write() in IEEE Std 1003.1,
>    * http://www.opengroup.org/onlinepubs/009695399 */
> @@ -273,8 +286,9 @@
>    * mirrored to safe kernel memory in case of user mode call
>    * @param[in] flags Message flags as passed by the user
>    *
> - * @return On success, the number of bytes received, otherwise negative error
> - * code
> + * @return On success, the number of bytes received. On failure return
> + * either -ENOSYS, to request that this handler be called again from the
> + * opposite realtime/non-realtime context, or another negative error code.
>    *
>    * @see @c recvmsg() in IEEE Std 1003.1,
>    * http://www.opengroup.org/onlinepubs/009695399 */
> @@ -292,8 +306,9 @@
>    * mirrored to safe kernel memory in case of user mode call
>    * @param[in] flags Message flags as passed by the user
>    *
> - * @return On success, the number of bytes transmitted, otherwise negative
> - * error code
> + * @return On success, the number of bytes transmitted. On failure return
> + * either -ENOSYS, to request that this handler be called again from the
> + * opposite realtime/non-realtime context, or another negative error code.
>    *
>    * @see @c sendmsg() in IEEE Std 1003.1,
>    * http://www.opengroup.org/onlinepubs/009695399 */

I thought it was documented, somewhere. But I do not find it anymore,
and documenting this mechanism here makes a lot of sense. So:

Acked-by: Jan Kiszka <jan.kiszka@domain.hid>


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 257 bytes --]