rtems_timer_fire_when() returns wrong status code when wall_time argument is NULL

[Frank Kuehndel]

The RTEMS Classic API Guide (​https://docs.rtems.org/branches/master/c-user/timer/directives.html#rtems-timer-fire-when) elaborates for rtems_timer_fire_when():

RTEMS_INVALID_ADDRESS

The wall_time parameter was NULL.

RTEMS_INVALID_CLOCK

The time of day was invalid.

Yet, calling rtems_timer_fire_when() with wall_time = NULL and all other parameters valid results in RTEMS_INVALID_CLOCK. Have a look into cpukit/rtems/src/timercreate.c function _Timer_Fire_when() to see the cause for this behavior.

I attach two patches:

• sptimer_err01.patch -- extends an existing test to reproduce this issue
• timercreate.patch -- fixes the issue

There are at least two ways to handle this bug and I do not want to decide which way to choose:

1. Change the documentation
2. Change the code

For the records:

RTEMS_VERSION    = 6.0.0
remote origin    = git://git.rtems.org/rtems.git
commit HEAD      = 2c5199bb049efe8e29cd12461dc57bd6e30388e8  (HEAD -> master, origin/master, origin/HEAD)
config.ini       =
    [arm/realview_pbx_a9_qemu]
    RTEMS_DEBUG = True
    RTEMS_NETWORKING = True
    RTEMS_POSIX_API = True
    RTEMS_SMP = True
    BUILD_TESTS = True
NEWLIB_VERSION   = 3.2.0
SOURCE_BUILDER   = Set Builder, 6 (5e449fb5c2cb)
GCC_VERSION      = arm-rtems6-gcc (GCC) 10.2.1 20210309 (RTEMS 6, RSB 5e449fb5c2cb6812a238f9f9764fd339cbbf05c2, Newlib d10d0d9)
BINUTILS_VERSION = GNU ld (GNU Binutils) 2.36.1.20210309

[Frank Kuehndel]

Extends existing test to reproduce the issue.

[Frank Kuehndel]

Patch which fixes the issue.

[Frank Kühndel <frank.kuehndel@…>]

In 3af2dc7/rtems:

_TOD_Validate(): Fix incorrect return code

This patch fixes bug #4403. Directives

• rtems_timer_fire_when()
• rtems_timer_server_fire_when()
• rtems_task_wake_when()

are documented to return RTEMS_INVALID_ADDRESS when their time-of-day
argument is NULL. But actually they return RTEMS_INVALID_CLOCK. To fix
the issue this patch changes _TOD_Validate() to return a
status code instead of just true/false.

Close #4403