[RTEMS Project] #4403: rtems_timer_fire_when() returns wrong status code when wall_time argument is NULL

[RTEMS trac]

#4403: rtems_timer_fire_when() returns wrong status code when wall_time argument
is NULL
-------------------------+-------------------------------------------------
  Reporter:  Frank       |      Owner:  Sebastian Huber
  Kuehndel               |
      Type:  defect      |     Status:  assigned
  Priority:  normal      |  Milestone:  6.1
 Component:  rtems       |    Version:  6
  Severity:  trivial     |   Keywords:  rtems_timer_fire_when,
                         |  RTEMS_INVALID_CLOCK, wall_time
Blocked By:              |   Blocking:
-------------------------+-------------------------------------------------
 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
 }}}

--
Ticket URL: <http://devel.rtems.org/ticket/4403>
RTEMS Project <http://www.rtems.org/>
RTEMS Project