Merge branch 'rework_doc_again' into 'devel-1.6'

Annotate API restrictions with tags.

See merge request etherlab.org/ethercat!130

Doxyfile.in

@@ -193,7 +193,8 @@ TAB_SIZE               = 4
 # will result in a user-defined paragraph with heading "Side Effects:".
 # You can put \n's in the value part of an alias to insert newlines.
 
-ALIASES                =
+ALIASES                = \
+                         "apiusage{1}=@par API Usage^^@ref apiusage \"\1\""
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding

master/api_usage_notes.md

@@ -0,0 +1,51 @@
+Notes regaring API Usage                {#apiusage}
+========================
+
+There are some restrictions on the
+[Application Interface](@ref ApplicationInterface) with respect to the state of
+the master instance and the calling context, which are explained in the
+following.
+
+## Rules of Thumb
+
+All configuration (`ecrt_slave_config_*()`) has to be done in Linux process
+context. They can be blocking, so take care when holding locks. After
+ecrt_master_activate() ing the master, your application must not alter the
+slave configuration. Instead, update process data using ecrt_domain_queue()
+and ecrt_domain_process() or use the asynchronous interface like
+ecrt_sdo_request_read(). Don't forget to ecrt_master_receive() and
+ecrt_master_send(). These functions can be called from non-process context
+too, like Xenomai/RTAI applications or custom kernel modules.
+
+## Master Phase
+
+The first distinction of cases is whether ecrt_master_activate() has been
+called or not. Before ecrt_master_activate() (or after
+ecrt_master_deactivate()), the master is in idle phase. Sending and receiving
+EtherCAT frames will be done by the master itself, the application (e. g. you)
+can store slave configurations for later use. After ecrt_master_activate(),
+the master switches into operation mode. The application is now in charge of
+steering the communication. Process data can be exchanged under real time
+constraints.  Altering the slave configuration is not possible anymore.
+
+| Tag           | Description                                                                           |
+|---------------|---------------------------------------------------------------------------------------|
+| `master_op`   | Master must be in operation phase, so after `ecrt_master_activate()` has been called. |
+| `master_idle` | Master must be in idle phase, so before `ecrt_master_activate()` has been called.     |
+| `master_any`  | Master can be in idle or operation phase.                                             |
+
+## Allowed Context
+
+The second distinction of cases is the calling context, which means how the
+application is run. Most of the functions of the
+[Application Interface](@ref ApplicationInterface) have to acquire locks or
+allocate memory, so they are potentially sleeping. They are tagged as
+`blocking`. Sleeping is not allowed in all contexts, for instance when using
+Xenomai/RTAI or a kernel timer. Only a very limited set of functions can be
+called from any context, marked as `rt_safe`. They do not allocate memory and
+will not block.
+
+| Tag        | Description                                                                                   |
+|------------|-----------------------------------------------------------------------------------------------|
+| `rt_safe`  | Realtime context (RT userspace, atomic/softirq context in kernel, Xenomai/RTAI RT task) safe. |
+| `blocking` | Linux process context only (userspace or kernel), might block.                                |