Module: xenomai-3
Branch: next
Commit: c2f62c5334f2312c14340a76be1bbbdadb60bc10
URL:
http://git.xenomai.org/?p=xenomai-3.git;a=commit;h=c2f62c5334f2312c14340a76be1bbbdadb60bc10
Author: Philippe Gerum <r...@xenomai.org>
Date: Thu Jun 12 17:32:22 2014 +0200
doc: prebuild
---
doc/asciidoc/MIGRATION.adoc | 168 ++++++++++++++++++++++++++++--
doc/asciidoc/README.APPLICATIONS.adoc | 7 ++
doc/asciidoc/README.INSTALL.adoc | 11 +-
doc/asciidoc/TROUBLESHOOTING.COBALT.adoc | 15 ++-
4 files changed, 184 insertions(+), 17 deletions(-)
diff --git a/doc/asciidoc/MIGRATION.adoc b/doc/asciidoc/MIGRATION.adoc
index 5aaf7fb..03470f7 100644
--- a/doc/asciidoc/MIGRATION.adoc
+++ b/doc/asciidoc/MIGRATION.adoc
@@ -104,14 +104,14 @@ filesystem. The hierarchy of the Xenomai registry is
organized as
follows:
----------------------------------------------------------------------------
- /mount-point /* registry fs root, defaults to /var/run/xenomai*/
- [/user] /* user name, missing if "anon" session */
- /session /* shared session name or "anon" */
- /pid /* application (main) pid */
- /skin /* API name: alchemy/vxworks/psos/... */
- /family /* object class (task, semaphore, ...) */
- { exported objects... }
- /system /* session-wide information */
+/mount-point /* registry fs root, defaults to /var/run/xenomai */
+ [/user] /* user name, missing if "anon" session */
+ /session /* shared session name or "anon" */
+ /pid /* application (main) pid */
+ /skin /* API name: alchemy/vxworks/psos/... */
+ /family /* object class (task, semaphore, ...) */
+ { exported objects... }
+ /system /* session-wide information */
----------------------------------------------------------------------------
Each leaf entry under a session hierarchy is normally viewable, for
@@ -883,6 +883,47 @@ static int foo_mmap(struct rtdm_fd *fd, struct
vm_area_struct *vma)
}
------------------------------------------------------------
+- the rtdm_nrtsig API has changed, the rtdm_nrtsig_init() function no
+ longer returns errors, it has the void return type. The rtdm_nrtsig_t
+ type has changed from an integer to a structure. In consequence, the
+ nrtsig handler first argument is now a pointer to the rtdm_nrtsig_t
+ structure.
+
+.Rationale
+************************************************************************
+Recent versions of the I-pipe patch support an ipipe_post_work_root()
+service, which has the advantage over the VIRQ support, that it does not
+require allocating one different VIRQ for each handler. As a consequence
+drivers may use as many rtdm_nrtsig_t structures as they like, there is
+no chance of running out of VIRQs.
+************************************************************************
+
+ The new relevant prototypes are therefore:
+
+-------------------------------------------------------------------------
+typedef void (*rtdm_nrtsig_handler_t)(rtdm_nrtsig_t *nrt_sig, void *arg);
+
+void rtdm_nrtsig_init(rtdm_nrtsig_t *nrt_sig,
+ rtdm_nrtsig_handler_t handler, void *arg);
+-------------------------------------------------------------------------
+
+- a new rtdm_schedule_nrt_work() was added to allow scheduling a Linux
+ work queue from primary mode.
+
+.Rationale
+************************************************************************
+Scheduling a Linux workqueue maybe a convenient way for adriver to recover
+for an error which requires synchronization with Linux. Typically, recovering
+from a PCI error may involve accessing the PCI config space, which requires
+access to a Linux spinlock so can not be done from primary mode.
+************************************************************************
+
+ The prototype of this new service is:
+
+------------------------------------------------------
+void rtdm_schedule_nrt_work(struct work_struct *work);
+------------------------------------------------------
+
==== Adaptive syscalls ====
+ioctl()+, +read()+, +write()+, +recvmsg()+ and +sendmsg()+ have
@@ -971,6 +1012,24 @@ This directory is aliased to /sys/class/rtdm.
* reading +type+ returns the device type (_named_ or _protocol_).
+=== Inter-Driver API ===
+
+The legacy (and redundant) rt_dev_*() API for calling the I/O services
+exposed by a RTDM driver from another driver was dropped, in favour of
+a direct use of the existing rtdm_*() API in kernel space. For
+instance, calls to +rt_dev_open()+ should be converted to
++rtdm_open()+, +rt_dev_socket()+ to +rtdm_socket()+ and so on.
+
+.Rationale
+******************************************************************
+Having two APIs for exactly the same purpose is uselessly confusing,
+particularly for kernel programming. Since the user-space version of
+the rt_dev_*() API was also dropped in favor of the regular POSIX I/O
+calls exposed by +libcobalt+, the choice was made to retain the most
+straightforward naming for the RTDM-to-RTDM API, keeping the +rtdm_+
+prefix.
+******************************************************************
+
== Analogy interface changes ==
=== Files renamed ===
@@ -1003,6 +1062,99 @@ analogy/ioctl.h -> all files merged into rtdm/analogy.h
As a consequence of these changes, the former include/analogy/ file
tree has been entirely removed.
+== RTnet changes ==
+
+RTnet is integrated into Xenomai 3, but some of its behaviour and
+interfaces were changed in an attempt to simplify it.
+
+- a network driver kernel module can not be unloaded as long as the
+ network interface it implements is up
+
+- the RTnet drivers API changed, to make it simpler, and closer to
+ the mainline API
+
+ * module refcounting is now automatically done by the stack, no
+ call is necessary to RTNET_SET_MODULE_OWNER, RTNET_MOD_INC_USE_COUNT,
+ RTNET_MOD_DEC_USE_COUNT
+
+ * per-driver skb receive pools were removed from drivers, they are
+ now handled by the RTnet stack. In consequence, drivers now need
+ to pass an additional argument to the rt_alloc_etherdev() service:
+ the number of buffers in the pool. The new prototype is:
+
+------------------------------------------------------------------------------------
+struct rtnet_device *rt_alloc_etherdev(unsigned sizeof_priv, unsigned
rx_pool_size);
+------------------------------------------------------------------------------------
+
+ Any explicit call to rtskb_pool_init() can be removed. In
+ addition, drivers should now use the rtnetdev_alloc_rtskb() to
+ allocate buffers from the network device receive pool; much like
+ its counterpart netdev_alloc_skb(), it takes as first argument a
+ pointer to a network device structure. It prototype is:
+
+--------------------------------------------------------------------------------
+struct rtskb *rtnetdev_alloc_rtskb(struct rtnet_device *dev, unsigned int
size);
+--------------------------------------------------------------------------------
+
+ * for driver which wish to explicitly handle skb pools, the
+ signature of rtskb_pool_init has changed: it takes an additional
+ pointer to a structure containing callbacks called when the first
+ buffer is allocated and when the last buffer is returned, so that
+ the rtskb_pool() can implicitly lock a parent structure. The new
+ prototype is:
+
+-----------------------------------------------------------------------
+struct rtskb_pool_lock_ops {
+ int (*trylock)(void *cookie);
+ void (*unlock)(void *cookie);
+};
+
+unsigned int rtskb_pool_init(struct rtskb_pool *pool,
+ unsigned int initial_size,
+ const struct rtskb_pool_lock_ops *lock_ops,
+ void *lock_cookie);
+-----------------------------------------------------------------------
+
+ * for the typical case where an skb pool locks the containing
+ module, the function rtskb_module_pool_init() was added which has
+ the same interface as the old rtskb_poll_init() function. Its
+ prototype is:
+
+-----------------------------------------------------------------------
+unsigned int rtskb_module_pool_init(struct rtskb_pool *pool,
+ unsigned int initial_size);
+-----------------------------------------------------------------------
+
+
+ * in order to ease the port of recent drivers, the following
+ services were added, which work much like their Linux counterpart:
+ rtnetdev_priv(), rtdev_emerg(), rtdev_alert(), rtdev_crit(),
+ rtdev_err(), rtdev_warn(), rtdev_notice(), rtdev_info(),
+ rtdev_dbg(), rtdev_vdbg(), RTDEV_TX_OK, RTDEV_TX_BUSY,
+ rtskb_checksum_none_assert(), rtskb_tx_timestamp(). Their
+ declarations are equivalent to:
+
+-----------------------------------------------------------------------
+#define RTDEV_TX_OK 0
+#define RTDEV_TX_BUSY 1
+
+void *rtndev_priv(struct rtnet_device *dev);
+
+void rtdev_emerg(struct rntet_device *dev, const char *format, ...);
+void rtdev_alert(struct rntet_device *dev, const char *format, ...);
+void rtdev_crit(struct rntet_device *dev, const char *format, ...);
+void rtdev_err(struct rntet_device *dev, const char *format, ...);
+void rtdev_warn(struct rntet_device *dev, const char *format, ...);
+void rtdev_notice(struct rntet_device *dev, const char *format, ...);
+void rtdev_info(struct rntet_device *dev, const char *format, ...);
+void rtdev_dbg(struct rntet_device *dev, const char *format, ...);
+void rtdev_vdbg(struct rntet_device *dev, const char *format, ...);
+
+void rtskb_checksum_non_assert(struct rtskb *skb);
+void rtskb_tx_timestamp(struct rtskb *skb);
+-----------------------------------------------------------------------
+
+
== POSIX interface changes ==
As mentioned earlier, the former *POSIX skin* is known as the *Cobalt
diff --git a/doc/asciidoc/README.APPLICATIONS.adoc
b/doc/asciidoc/README.APPLICATIONS.adoc
index 920b458..5bdffea 100644
--- a/doc/asciidoc/README.APPLICATIONS.adoc
+++ b/doc/asciidoc/README.APPLICATIONS.adoc
@@ -75,6 +75,13 @@ link:installing-xenomai-3-x[configuration switch]).
instead of +/var/run/xenomai+ by default (see the
+--enable-registry+ switch from the configuration options).
+*--shared-registry*::
+
+ Exports the registry of the process to other users. If access
+ is possible, also depends on permissions of the registry path.
+ By default, the registry is only accessible for the user that
+ started the Xenomai process.
+
*--no-registry*::
This switch disables registry support at runtime. No real-time
diff --git a/doc/asciidoc/README.INSTALL.adoc b/doc/asciidoc/README.INSTALL.adoc
index 4538396..60d6b8d 100644
--- a/doc/asciidoc/README.INSTALL.adoc
+++ b/doc/asciidoc/README.INSTALL.adoc
@@ -400,7 +400,7 @@ Generic configuration options (both cores)
allows multiple processes to share real-time objects
(e.g. tasks, semaphores).
-*--enable-registry*::
+*--enable-registry[=/registry-root-path]*::
Xenomai APIs can export their internal state through a
pseudo-filesystem, which files may be read to obtain
@@ -421,7 +421,7 @@ Generic configuration options (both cores)
properties of a VxWorks task could be done as follows:
--------------------------------------------------------------------
- $ cat /var/run/xenomai/anon/12656/vxworks/tasks/windTask
+ $ cat /var/run/xenomai/anon.12656/vxworks/tasks/windTask
name = windTask
errno = 0
status = ready
@@ -430,8 +430,11 @@ Generic configuration options (both cores)
--------------------------------------------------------------------
[normal]
- You may override the default root of the registry hierarchy by
- using the `--registry-root` runtime option (see below).
+ You may override the default root of the registry hierarchy
+ either statically at build time by passing the desired root
+ path to the --enable-registry configuration switch, or
+ dynamically by using the `--registry-root` runtime option
+ passed to the application.
[NOTE]
When running over _Xenomai/cobalt_, the `/proc/xenomai` interface is
diff --git a/doc/asciidoc/TROUBLESHOOTING.COBALT.adoc
b/doc/asciidoc/TROUBLESHOOTING.COBALT.adoc
index 5e16faa..543b8aa 100644
--- a/doc/asciidoc/TROUBLESHOOTING.COBALT.adoc
+++ b/doc/asciidoc/TROUBLESHOOTING.COBALT.adoc
@@ -544,8 +544,13 @@ add the following line to the +Device+ section:
==== pthread_create: Resource temporarily unavailable
-The switchtest test creates many kernel threads, this means that the
-options +CONFIG_XENO_OPT_SYS_HEAPSZ+ and
-+CONFIG_XENO_OPT_SYS_STACKPOOLSZ+, in your kernel configuration,
-should be configured to large enough values. Try increasing them,
-rebuilding the kernel.
+The switchtest test creates many kernel threads, an operation which
+consumes memory taken from internal pools managed by the Xenomai
+real-time core.
+
+Xenomai 2.x and 3.x series require +CONFIG_XENO_OPT_SYS_HEAPSZ+ to be
+large enough in the kernel configuration settings, to cope with the
+allocation requests.
+
+Xenomai 2.x may also require to increase the
++CONFIG_XENO_OPT_SYS_STACKPOOLSZ+ setting.
_______________________________________________
Xenomai-git mailing list
Xenomai-git@xenomai.org
http://www.xenomai.org/mailman/listinfo/xenomai-git
