Module: xenomai-forge
Branch: next
Commit: 9382094f1a19135ffa2d3f3b9650fc482edc42e3
URL:    
http://git.xenomai.org/?p=xenomai-forge.git;a=commit;h=9382094f1a19135ffa2d3f3b9650fc482edc42e3

Author: Philippe Gerum <r...@xenomai.org>
Date:   Fri Jan  3 12:40:59 2014 +0100

doc: more preliminary 2.x -> 3.x migration info

---

 doc/asciidoc/MIGRATION.adoc |  135 ++++++++++++++++++++++++++++++++++---------
 1 file changed, 109 insertions(+), 26 deletions(-)

diff --git a/doc/asciidoc/MIGRATION.adoc b/doc/asciidoc/MIGRATION.adoc
index fa89a8f..775784f 100644
--- a/doc/asciidoc/MIGRATION.adoc
+++ b/doc/asciidoc/MIGRATION.adoc
@@ -254,7 +254,7 @@ using the Cobalt core.
   Rationale: handling real-time interrupt events from user-space can
   be done safely only if some top-half code exists for acknowledging
   the issuing device request from kernel space. This should be done
-  via a RTDM driver, exposing a read(2) or ioctl(2) interface, for
+  via a RTDM driver, exposing a +read(2)+ or +ioctl(2)+ interface, for
   waiting for interrupt events from applications running in
   user-space.
 
@@ -276,6 +276,17 @@ using the Cobalt core.
   strong hint for keeping the top-half interrupt handling code in
   kernel space.
 
+[TIP]
+[[userirqtip]]
+  For receiving interrupt notifications within your application, you
+  should create a small RTDM driver handling the corresponding IRQ
+  (see +rtdm_irq_request()+). The IRQ handler should wake a thread up
+  in your application by posting some event (see +rtdm_sem_up()+,
+  +rtdm_sem_timeddown()+). The application should sleep on this event
+  by calling into the RTDM driver, either via a +read(2)+ or
+  +ioctl(2)+ request, handled by a dedicated operation handler (see
+  +rtdm_dev_register()+).
+
 .Scheduling
 
 - Calling +pthread_setschedparam()+ may cause a secondary mode switch
@@ -305,8 +316,8 @@ using the Cobalt core.
 
 [normal]
   Conversely, a thread which calls +pthread_setschedparam()+ does know
-  unambiguously whether the current calling context is safe for such
-  request.
+  unambiguously whether the current calling context is safe for the
+  incurred migration.
 
 - A new SCHED_WEAK class is available to POSIX threads, which may be
   optionally turned on using the +CONFIG_XENO_OPT_SCHED_WEAK+ kernel
@@ -511,17 +522,17 @@ Applications may override the default priority
 normalization/denormalization handlers, by implementing the following
 routines.
 
-[normal]
-Over Cobalt, the POSIX scale is extended to 257 levels, which allows
-to map pSOS over the POSIX scale 1:1, leaving
-normalization/denormalization handlers as no-ops by default.
-
 ------------------------------------------------------------
 int psos_task_normalize_priority(unsigned long psos_prio);
 
 unsigned long psos_task_denormalize_priority(int core_prio);
 ------------------------------------------------------------
 
+[normal]
+Over Cobalt, the POSIX scale is extended to 257 levels, which allows
+to map pSOS over the POSIX scale 1:1, leaving
+normalization/denormalization handlers as no-ops by default.
+
 == VxWorks interface changes ==
 
 .Task management
@@ -531,8 +542,8 @@ result of a call to +taskTcb()+ or +taskGetInfo()+.
 
 [normal]
 As a consequence of this change, any reference to a user-visible TCB
-should be refreshed by calling +taskTcb()+ anew, prior to reading the
-+status+ field.
+should be refreshed by calling +taskTcb()+ anew, each time reading the
++status+ field is required.
 
 .Scheduling
 
@@ -553,16 +564,21 @@ int wind_task_denormalize_priority(int core_prio);
 
 == Former Native interface changes (now Alchemy) ==
 
+.General
+
+- The API calls supporting a wait operation may return the -EIDRM
+error code only when the target object was deleted while
+pending. Otherwise, passing a deleted object identifier to an API call
+will result in -EINVAL being returned.
+
 .Interrupt management
 
 - The +RT_INTR+ API is gone. Please see the <<irqhandling,rationale>>
   for not handling low-level interrupt service code from user-space.
 
-[normal]
-  Synchronizing application code on interrupt receipt can still be
-  done using the described method, based on issuing read(2) or
-  ioctl(2) calls to a dedicated RTDM driver. This driver would be in
-  charge of dealing with the low-level IRQ handling.
+[TIP]
+It is still possible to have the application wait for interrupt
+receipts, as explained <<userirqtip,here>>.
 
 .I/O regions
 
@@ -575,6 +591,16 @@ int wind_task_denormalize_priority(int core_prio);
 per-process setting, which can be tuned by passing the
 +--alchemy-clock-resolution+ switch on the command line.
 
+[TIP]
+Tick-based timing can be obtained by setting the resolution of the
+Alchemy clock for the application, here to one millisecond (the
+argument expresses a count nanoseconds per tick).  As a result of
+this, all timeout and date values passed to Alchemy API calls will be
+interpreted as counts of milliseconds.
+----------------------------------------------------------
+# xenomai-application --alchemy-clock-resolution=1000000
+----------------------------------------------------------
+
 [normal]
 By default, the Alchemy API sets the clock resolution for the new
 process to one nanosecond (i.e. tickless, highest resolution).
@@ -591,15 +617,35 @@ the initial delay.
 [normal]
 Rationale: a periodic task has to call +rt_task_wait_period()+ from
 within its work loop for sleeping until the next release point is
-reached. Therefore, there is no point in waiting for the initial
-release point from a different location.
+reached. Therefore, in most cases, there is no point in waiting for
+the initial release point from a different location.
+
+[TIP]
+In the unusual case where you do need to have the target task wait for
+the initial release point outside of its periodic work loop, you can
+issue a call to +rt_task_wait_period()+ separately, exclusively for
+this purpose, i.e.
+---------------------------------------------------------------
+              /* wait for the initial release point. */
+              ret = rt_task_wait_period(&overruns);
+             /* ...more preparation work... */
+             for (;;) {
+                      /* wait for the next release point. */
+                      ret = rt_task_wait_period(&overruns);
+                      /* ...do periodic work... */
+             }
+---------------------------------------------------------------
 
 [normal]
 +rt_task_set_periodic()+ still switches to primary as previously over
-Cobalt. However, it won't return -EWOULDBLOCK anymore.
+Cobalt. However, it does not return -EWOULDBLOCK anymore.
+
+- TM_ONESHOT was dropped, because the operation mode of the hardware
+  timer has no meaning for the application. The core Xenomai system
+  always operates the available timer chip in oneshot mode anyway.
 
-- TM_ONESHOT was dropped when reporting a tick duration, a tickless
-  clock has a period of one nanosecond.
+[TIP]
+A tickless clock has a period of one nanosecond.
 
 .Mutexes
 
@@ -649,10 +695,10 @@ Rationale: This behavior can be achieved by not calling
 
 - The RT_TASK_INFO structure returned by +rt_task_inquire()+ has
   changed:
-   * field +relpoint+ and +cprio+ have been removed, since the
+   * fields +relpoint+ and +cprio+ have been removed, since the
      corresponding information is too short-lived to be valuable to
-     the caller. The task's current priority is available from the
-     +prio+ field.
+     the caller. The task's base priority is still available from
+     the +prio+ field.
    * other fields which represent runtime statistics are now avail
      from a core-specific +stat+ field sub-structure.
 
@@ -679,9 +725,46 @@ the real-time core applying implicit dynamic boosts.
 
 .Message queues
 
-- +rt_queue_create()+
-   * Q_SHARED is implicitly assumed for all queues, even if
-     unspecified.
+- +rt_queue_create()+ mode bits updated:
+   * Q_SHARED is implicit for all queues, defined as nop.
    * Q_DMA has become meaningless, and therefore was dropped. A driver
      should be implemented for delivering chunks of DMA-suitable
      memory.
+
+.Heaps
+
+- +rt_heap_create()+ mode bits updated:
+   * H_MAPPABLE has become meaningless.
+   * H_SHARED is deprecated, but still wraps to H_SINGLE.
+   * H_NONCACHED and H_DMA became meaningless.
+
+[TIP]
+If you need to allocate a chunk of DMA-suitable memory, then you
+should create a RTDM driver for this purpose.
+
+- +rt_heap_alloc_until()+ is a new call for waiting for a memory
+  chunk, specifying an absolute timeout date.
+
+- +rt_heap_inquire()+ with the removal of H_DMA, phys_addr makes no
+   sense anymore, removed.
+
+.Alarms
+
+- +rt_alarm_wait()+ has been removed.
+
+[normal]
+Rationale: An alarm handler can be specified to +rt_alarm_create()+
+instead.
+
+- The RT_ALARM_INFO structure returned by +rt_alarm_inquire()+ has
+  changed:
+   * field +expiration+ has been removed, since the corresponding
+     information is too short-lived to be valuable to the caller.
+
+.Message pipes
+
+- Writing to a message pipe is allowed from all contexts, including
+  from alarm handlers.
+
+- +rt_pipe_read_until()+ is a new call for waiting for input from a
+  pipe, specifying an absolute timeout date.


_______________________________________________
Xenomai-git mailing list
Xenomai-git@xenomai.org
http://www.xenomai.org/mailman/listinfo/xenomai-git

Reply via email to