[Xenomai-help] doc patch: RT_TASK_INFO

[Xenomai-help] doc patch: RT_TASK_INFO

[Nathaniel J Villaume]

Hi, 
I got the already documented code to show up in the documentation
with the attached patch: (not brilliant documentation update,
sorry :) )

Index: xeno_doc_update/include/native/task.h
===================================================================
--- xeno_doc_update/include/native/task.h	(revision 1231)
+++ xeno_doc_update/include/native/task.h	(working copy)
@@ -66,18 +66,19 @@
 
 struct rt_queue_msg;
 struct rt_task;
-
+/*! @brief This structure provides information about tasks. 
+ @see rt_task_inquire()  */
 typedef struct rt_task_info {
 
-    int bprio;			/* !< Base priority. */
+    int bprio;			//!< Base priority. 
 
-    int cprio;			/* !< Current priority. */
+    int cprio;			//!< Current priority.
 
-    unsigned status;		/* !< Status. */
+    unsigned status;		//!< Status. 
 

[Xenomai-help] patch: native/task.h

[Nathaniel J Villaume]

Hi, 

I include two more patches here:
1) info_mcb_changed_native_task.h.diff: 
   only changed documentation level of RT_TASK_INFO and RT_TASK_MCB
2) all_changed_native_task.h.diff: 
   changed the file to show all the documented bits (including
RT_TASK

The reasoon is that maybe the internals of RT_TASK don't need to
be exposed. 

HTH,
-Nate

[Xenomai-help] patch: info_mcb_changed_native_task.h.diff

[Nathaniel J Villaume]

sorry, have to send one at a time....

[Xenomai-help] patch: all_changed_native_task.h.diff

[Nathaniel J Villaume]

[-- Attachment #1: Type: text/plain, Size: 33 bytes --]

last file in mentioned patches



[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: all_changed_native_task.h.diff --]
[-- Type: text/x-patch; name="all_changed_native_task.h.diff", Size: 2717 bytes --]

--- native/task.h	2006-06-13 13:25:33.000000000 -0700
+++ xeno_doc_update/include/native/task.h	2006-06-13 13:46:18.000000000 -0700
@@ -67,61 +66,66 @@
 
 struct rt_queue_msg;
 struct rt_task;
-
+/*! @brief This structure provides information about tasks. 
+ @see rt_task_inquire()  */
 typedef struct rt_task_info {
 
-    int bprio;			/* !< Base priority. */
+    int bprio;			//!< Base priority. 
 
-    int cprio;			/* !< Current priority. */
+    int cprio;			//!< Current priority.
 
-    unsigned status;		/* !< Status. */
+    unsigned status;		//!< Status. 
 
-    RTIME relpoint;		/* !< Next periodic release point. */
+    RTIME relpoint;		//!< Periodic release point. 
 
-    char name[XNOBJECT_NAME_LEN]; /* !< Symbolic name. */
+    char name[XNOBJECT_NAME_LEN]; //!< Symbolic name.
 
 } RT_TASK_INFO;
 
 #define RT_MCB_FSTORE_LIMIT  64
-
+/*! @brief Task Message Control Block 
+ @see rt_task_send() 
+ */
 typedef struct rt_task_mcb {
 
-    int flowid;			/* !< Flow identifier. */
+    int flowid;			//!< Flow identifier.
 
-    int opcode;			/* !< Operation code. */
+    int opcode;			//!< Operation code. 
 
-    caddr_t data;		/* !< Address of message. */
+    caddr_t data;		//!< Address of message. 
 
-    size_t size;		/* !< Size of message. */
+    size_t size;		//!< Size of message. 
 
 } RT_TASK_MCB;
 
 #if defined(__KERNEL__) || defined(__XENO_SIM__)
 
 #define XENO_TASK_MAGIC 0x55550101
-
+/*! @brief Structure that holds lots (all) the information about tasks.
+  */
 typedef struct rt_task {
 
-    unsigned magic;   /* !< Magic code - must be first */
+    unsigned magic;   //!< Magic code - must be first */
 
     xnholder_t link;
 
 #define link2rtask(laddr) \
 ((RT_TASK *)(((char *)laddr) - (int)(&((RT_TASK *)0)->link)))
 
-    xnthread_t thread_base;
+    xntimer_t timer;
 
-    char rname[XNOBJECT_NAME_LEN]; /* !< Name in registry. Not the same as
-                                      thread name for anonymous threads. */
+    xnthread_t thread_base;
+    /*!< Name in registry. Not the same as thread name for anonymous threads. */
+    char rname[XNOBJECT_NAME_LEN]; 
     int suspend_depth;
 
     int overrun;
 
-    xnsynch_t safesynch; /* !< Safe synchronization object. */
+    xnsynch_t safesynch; //!< Safe synchronization object.
 
-    u_long safelock;	 /* !< Safe lock count. */
+    u_long safelock;	 //!< Safe lock count.
 
-    u_long cstamp;	/* !< Creation stamp. */
+    u_long cstamp;	//!< Creation stamp. 
 
     xnarch_cpumask_t affinity;
 
@@ -152,7 +156,7 @@
     xnsynch_t mrecv,
 	      msendq;
 
-    int flowgen;		/* !< Flow id. generator. */
+    int flowgen;		//!< Flow id. generator.
 #endif /* CONFIG_XENO_OPT_NATIVE_MPS */
 
 } RT_TASK;

Re: [Xenomai-help] doc patch: RT_TASK_INFO

[Jan Kiszka]

[-- Attachment #1: Type: text/plain, Size: 393 bytes --]

Nathaniel J Villaume wrote:
> Hi, 
> I got the already documented code to show up in the documentation
> with the attached patch: (not brilliant documentation update,
> sorry :) )

Highly welcome, but could we do it like this "/*!< Comment */" e.g.? No
C++ comments in C code.

Thanks!
Jan


PS: And one patch per subsystem or so is enough. Please not one per
structure... :)


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 250 bytes --]

Re: [Xenomai-help] doc patch: RT_TASK_INFO

[Nathaniel Villaume]

The patches were to help you out! I thought that maybe you wouldn't want 
RT_TASK documented -- users don't really need to konw about magic number 
and flowgen, do they?  But yeah, sorry for the spamming.

As for the comment style, the C style comments don't show up using this 
inline method: /*!< */   -- that was part of the original problem.  One 
solution is to use the @typedef command. The only drawback here is the 
minor replication. For example:

/*! @typedef RT_TASK
    @brief Contains important data
  @param  magic  Magic uniquely identifies the task's wizardry ancestry
  @param  prio   task priority
*/
typedef struct {
  int magic;  // Must come first!   (comments don't HAVE to go here)
  uint prio;  // task priority
  /* etc */
} RT_TASK;

What I need to know from you:
1) Do you care about this duplication of struct member-names (harder to 
keep docs synchronized with code)?
2) Do you want RT_TASK member documentation to show up in 
doxygen-generated pages?  (this lets me know what to change)

-Nate

[Xenomai-help] RT_TASK_INFO status

[Nathaniel Villaume]

In RT_TASK_INFO, can someone tell me what is the set of all possible 
values for status?
I'd like to include that in the documentation.

Thanks,
Nate

Re: [Xenomai-help] doc patch: RT_TASK_INFO

[Jan Kiszka]

[-- Attachment #1: Type: text/plain, Size: 1841 bytes --]

Nathaniel Villaume wrote:
> The patches were to help you out! I thought that maybe you wouldn't want
> RT_TASK documented -- users don't really need to konw about magic number
> and flowgen, do they?  But yeah, sorry for the spamming.

Yes, I absolutely agree with you that RT_TASK and other internal
structures should not pop up in doxygen (but, of course, still have its
comments for the developers)!

> 
> As for the comment style, the C style comments don't show up using this
> inline method: /*!< */   -- that was part of the original problem.  One

Mm, not convinced yet: the original code looked like this: /* !< Text */
(note the space). I think there must be a C-conforming way to document
fields.

> solution is to use the @typedef command. The only drawback here is the
> minor replication. For example:
> 
> /*! @typedef RT_TASK
>    @brief Contains important data
>  @param  magic  Magic uniquely identifies the task's wizardry ancestry
>  @param  prio   task priority
> */
> typedef struct {
>  int magic;  // Must come first!   (comments don't HAVE to go here)
>  uint prio;  // task priority
>  /* etc */
> } RT_TASK;

No, not really beautiful. Another way is this (see also RTDM skin):

typedef struct {
	/** Some field */
	int some_field;
} my_struct;

The problem with doxygen is that you never really know what went wrong,
at least not within the first hours of experimenting with the code... :(

> 
> What I need to know from you:
> 1) Do you care about this duplication of struct member-names (harder to
> keep docs synchronized with code)?

I would personally prefer to avoid this.

> 2) Do you want RT_TASK member documentation to show up in
> doxygen-generated pages?  (this lets me know what to change)

See above. But I'm not the only one around here.

Jan


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 250 bytes --]

[Xenomai-help] Re: RT_TASK_INFO status

[Jan Kiszka]

[-- Attachment #1: Type: text/plain, Size: 584 bytes --]

Nathaniel Villaume wrote:
> In RT_TASK_INFO, can someone tell me what is the set of all possible
> values for status?
> I'd like to include that in the documentation.

They are defined in include/native/task.h [1], but they widely redirect
to defines in include/nucleus/thread.h [2]. Maybe you could add comments
to the native/task.h defines and include them in doxygen.

Thanks again for your effort!
Jan

[1]http://www.rts.uni-hannover.de/xenomai/lxr/source/include/native/task.h#L37
[2]http://www.rts.uni-hannover.de/xenomai/lxr/source/include/nucleus/thread.h#L25


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 250 bytes --]

[Xenomai-help] Re: RT_TASK_INFO status

[Nathaniel Villaume]

[-- Attachment #1: Type: text/plain, Size: 2312 bytes --]

Jan,
Ok, so I played around with your request some.

 My goal here is to produce documentation, but not at the expense of 
source-code readability and maintainability.  It's not hard to document 
defines, but it CAN make the source look uglier.
Witness nucleus/thread.h:

/*! @def XNSUSP */
#define XNSUSP 0x00000001 /*!< @brief Suspended */

/*! @define XNSUSP */
#define XNSUSP 0x00000002 /*!< Sleep-wait for a resource. */

In the first case, @brief is used to get the comment up into the brief 
listing (duh). If this is not done, then a detailed section is created 
with the comment, which is a little kludgier on the output end, but 
still completely usable.

Second order of business: refering to this new documentation. In 
include/native/task.h I made a group native_task_status that encompasses 
all the define documentation. This makes it easy to refer to from within 
the RT_TASK_INFO::status documentation (and anywhere else)

Third: I removed the duplication as you requested. This is not without 
consequence.  Please note the difference between RT_TASK_INFO and 
RT_TASK_MCB (which remainded the same).  To keep the brief member 
documentation, I had to use the /**  comment */ syntax. This is 
inconsistent with other usage, but... this gives the results we want.

Please see the patch and let me know what you think for this initial set.
Again, the decisions to be made are:
1.) Do we document the defines at all?
1a) If so, do we include brief in the define documentation (or not)?
1b) Do we group the defines (or not) for easy reference? (they show up 
under modules/native/Task Status)

My default action is to continue with the style/grouping as in the patch.

-Nate

Jan Kiszka wrote:

>Nathaniel Villaume wrote:
>  
>
>>In RT_TASK_INFO, can someone tell me what is the set of all possible
>>values for status?
>>I'd like to include that in the documentation.
>>    
>>
>
>They are defined in include/native/task.h [1], but they widely redirect
>to defines in include/nucleus/thread.h [2]. Maybe you could add comments
>to the native/task.h defines and include them in doxygen.
>
>Thanks again for your effort!
>Jan
>
>[1]http://www.rts.uni-hannover.de/xenomai/lxr/source/include/native/task.h#L37
>[2]http://www.rts.uni-hannover.de/xenomai/lxr/source/include/nucleus/thread.h#L25
>
>  
>

[-- Attachment #2: task_defines.diff --]
[-- Type: text/plain, Size: 3624 bytes --]

Index: include/native/task.h
===================================================================
--- include/native/task.h	(revision 1383)
+++ include/native/task.h	(working copy)
@@ -34,8 +34,20 @@
 #define T_CPU(cpu) (1 << (24 + (cpu & 7))) /* Up to 8 cpus [0-7] */
 #define T_CPUMASK  0xff000000
 
-/* Status/mode flags. */
-#define T_BLOCKED  XNPEND
+/*! 
+  \ingroup native
+  @defgroup native_task_status Task Status 
+  @brief Defines used to specify task state and/or mode 
+  */
+/*! @addtogroup native_task_status 
+  @{
+  */
+
+/*! @def T_BLOCKED  
+  Task is blocked. See define #XNPEND*/
+#define T_BLOCKED  XNPEND 
+/*! @def T_DELAYED  
+  Task is delayed. See define #XNDELAY*/
 #define T_DELAYED  XNDELAY
 #define T_READY    XNREADY
 #define T_DORMANT  XNDORMANT
@@ -49,6 +61,7 @@
 #define T_RPIOFF   XNRPIOFF
 #define T_PRIMARY  0x00000200	/* Recycle internal bits status which */
 #define T_JOINABLE 0x00000400	/* won't be passed to the nucleus.  */
+/*! @} */ /* Ends addtogroup native_task_status */
 
 /* Task hook types. */
 #define T_HOOK_START  XNHOOK_THREAD_START
@@ -68,31 +81,50 @@
 struct rt_queue_msg;
 struct rt_task;
 
+/*! @brief Structure containing task-information useful to users.
+ *
+ *  @see rt_task_inquire()
+  */
 typedef struct rt_task_info {
+    
+    /** Base priority. */
+    int bprio;  
 
-    int bprio;			/* !< Base priority. */
+    /** Current priority. Can change through Priority Inheritance.*/
+    int cprio;
+    
+    /** Task's status.
+     * Status may be any of the defines in task.h
+     *  @see native_task_status shows possible values.
+     */
+    unsigned status; 
+    
+    /** Time of next release.*/
+    RTIME relpoint; 
+    
+    /** Symbolic name assigned in creation */
+    char name[XNOBJECT_NAME_LEN];  
 
-    int cprio;			/* !< Current priority. */
-
-    unsigned status;		/* !< Status. */
-
-    RTIME relpoint;		/* !< Next periodic release point. */
-
-    char name[XNOBJECT_NAME_LEN]; /* !< Symbolic name. */
-
 } RT_TASK_INFO;
 
 #define RT_MCB_FSTORE_LIMIT  64
+/*! @typedef RT_TASK_MCB
+  @brief Structure used in passing messages between tasks.
 
+  @param  flowid  Flow identifier.
+  @param  opcode  Operation code.
+  @param  data    Message address.
+  @param  size    Message size (bytes).
+*/
 typedef struct rt_task_mcb {
 
-    int flowid;			/* !< Flow identifier. */
+    int flowid;
 
-    int opcode;			/* !< Operation code. */
+    int opcode;
 
-    caddr_t data;		/* !< Address of message. */
+    caddr_t data;
 
-    size_t size;		/* !< Size of message. */
+    size_t size;
 
 } RT_TASK_MCB;
 
Index: include/nucleus/thread.h
===================================================================
--- include/nucleus/thread.h	(revision 1383)
+++ include/nucleus/thread.h	(working copy)
@@ -1,4 +1,4 @@
-/*
+/*! @file nucleus/thread.h
  * Copyright (C) 2001,2002,2003 Philippe Gerum <rpm@xenomai.org>.
  *
  * Xenomai is free software; you can redistribute it and/or modify
@@ -23,9 +23,13 @@
 #include <nucleus/timer.h>
 
 /* Status flags */
-#define XNSUSP    0x00000001	/* Suspended */
-#define XNPEND    0x00000002	/* Sleep-wait for a resource */
-#define XNDELAY   0x00000004	/* Delayed */
+
+/*! @def XNSUSP */
+#define XNSUSP    0x00000001	/*!< @brief Suspended */
+/*! @def XNPEND */
+#define XNPEND    0x00000002	/*!< Sleep-wait for a resource */
+/*! @def XNPEND */
+#define XNDELAY   0x00000004	/*!< Delayed */
 #define XNREADY   0x00000008	/* Linked to the ready queue */
 #define XNDORMANT 0x00000010	/* Not started yet or killed */
 #define XNZOMBIE  0x00000020	/* Zombie thread in deletion process */

[Xenomai-help] Re: RT_TASK_INFO status

[Jan Kiszka]

[-- Attachment #1: Type: text/plain, Size: 7583 bytes --]

Nathaniel Villaume wrote:
> Jan,
> Ok, so I played around with your request some.
> 
> My goal here is to produce documentation, but not at the expense of
> source-code readability and maintainability.  It's not hard to document
> defines, but it CAN make the source look uglier.
> Witness nucleus/thread.h:
> 
> /*! @def XNSUSP */
> #define XNSUSP 0x00000001 /*!< @brief Suspended */
> 
> /*! @define XNSUSP */
> #define XNSUSP 0x00000002 /*!< Sleep-wait for a resource. */
> 
> In the first case, @brief is used to get the comment up into the brief
> listing (duh). If this is not done, then a detailed section is created
> with the comment, which is a little kludgier on the output end, but
> still completely usable.

But why are there those @def/@defines? Are those defines already
assigned to some group?

> 
> Second order of business: refering to this new documentation. In
> include/native/task.h I made a group native_task_status that encompasses
> all the define documentation. This makes it easy to refer to from within
> the RT_TASK_INFO::status documentation (and anywhere else)

Sounds good.

> 
> Third: I removed the duplication as you requested. This is not without
> consequence.  Please note the difference between RT_TASK_INFO and
> RT_TASK_MCB (which remainded the same).  To keep the brief member
> documentation, I had to use the /**  comment */ syntax. This is
> inconsistent with other usage, but... this gives the results we want.

Yeah, I noticed this as well. Is this somewhere documented in the
doxygen manual? Anyway, I prefer the output format of "/**" or "/**<"
for such small structures like we have here.

> 
> Please see the patch and let me know what you think for this initial set.
> Again, the decisions to be made are:
> 1.) Do we document the defines at all?

Via doxygen: those the user needs to know about and they are not already
documented inside some function argument description.

> 1a) If so, do we include brief in the define documentation (or not)?
> 1b) Do we group the defines (or not) for easy reference? (they show up
> under modules/native/Task Status)

I would say: group them, maybe @brief the groups, but do not add
individual @brief to each define.

> 
> My default action is to continue with the style/grouping as in the patch.

Ack from me. Anyone else any different preferences or additional
suggestions?

> 
> -Nate
> 
> Jan Kiszka wrote:
> 
>> Nathaniel Villaume wrote:
>>  
>>
>>> In RT_TASK_INFO, can someone tell me what is the set of all possible
>>> values for status?
>>> I'd like to include that in the documentation.
>>>   
>>
>> They are defined in include/native/task.h [1], but they widely redirect
>> to defines in include/nucleus/thread.h [2]. Maybe you could add comments
>> to the native/task.h defines and include them in doxygen.
>>
>> Thanks again for your effort!
>> Jan
>>
>> [1]http://www.rts.uni-hannover.de/xenomai/lxr/source/include/native/task.h#L37
>>
>> [2]http://www.rts.uni-hannover.de/xenomai/lxr/source/include/nucleus/thread.h#L25
>>
>>
>>  
>>
> 
> ------------------------------------------------------------------------
> 
> Index: include/native/task.h
> ===================================================================
> --- include/native/task.h	(revision 1383)
> +++ include/native/task.h	(working copy)
> @@ -34,8 +34,20 @@
>  #define T_CPU(cpu) (1 << (24 + (cpu & 7))) /* Up to 8 cpus [0-7] */
>  #define T_CPUMASK  0xff000000
>  
> -/* Status/mode flags. */
> -#define T_BLOCKED  XNPEND
> +/*! 
> +  \ingroup native
> +  @defgroup native_task_status Task Status 
> +  @brief Defines used to specify task state and/or mode 
> +  */
> +/*! @addtogroup native_task_status 
> +  @{
> +  */
> +
> +/*! @def T_BLOCKED  
> +  Task is blocked. See define #XNPEND*/

I wouldn't refer to the nucleus layer here (XN...). The native API
should explain itself independently.

> +#define T_BLOCKED  XNPEND 
> +/*! @def T_DELAYED  
> +  Task is delayed. See define #XNDELAY*/
>  #define T_DELAYED  XNDELAY
>  #define T_READY    XNREADY
>  #define T_DORMANT  XNDORMANT
> @@ -49,6 +61,7 @@
>  #define T_RPIOFF   XNRPIOFF
>  #define T_PRIMARY  0x00000200	/* Recycle internal bits status which */
>  #define T_JOINABLE 0x00000400	/* won't be passed to the nucleus.  */
> +/*! @} */ /* Ends addtogroup native_task_status */
>  
>  /* Task hook types. */
>  #define T_HOOK_START  XNHOOK_THREAD_START
> @@ -68,31 +81,50 @@
>  struct rt_queue_msg;
>  struct rt_task;
>  
> +/*! @brief Structure containing task-information useful to users.
> + *
> + *  @see rt_task_inquire()
> +  */
>  typedef struct rt_task_info {
> +    
> +    /** Base priority. */
> +    int bprio;  
>  
> -    int bprio;			/* !< Base priority. */
> +    /** Current priority. Can change through Priority Inheritance.*/
> +    int cprio;
> +    
> +    /** Task's status.
> +     * Status may be any of the defines in task.h
> +     *  @see native_task_status shows possible values.
> +     */
> +    unsigned status; 
> +    
> +    /** Time of next release.*/
> +    RTIME relpoint; 
> +    
> +    /** Symbolic name assigned in creation */
> +    char name[XNOBJECT_NAME_LEN];  
>  
> -    int cprio;			/* !< Current priority. */
> -
> -    unsigned status;		/* !< Status. */
> -
> -    RTIME relpoint;		/* !< Next periodic release point. */
> -
> -    char name[XNOBJECT_NAME_LEN]; /* !< Symbolic name. */
> -
>  } RT_TASK_INFO;

That looks good to me. Note that "/**<" works fine for me as well (in
case there are only short comments...).

>  
>  #define RT_MCB_FSTORE_LIMIT  64
> +/*! @typedef RT_TASK_MCB
> +  @brief Structure used in passing messages between tasks.
>  
> +  @param  flowid  Flow identifier.
> +  @param  opcode  Operation code.
> +  @param  data    Message address.
> +  @param  size    Message size (bytes).
> +*/
>  typedef struct rt_task_mcb {
>  
> -    int flowid;			/* !< Flow identifier. */
> +    int flowid;
>  
> -    int opcode;			/* !< Operation code. */
> +    int opcode;
>  
> -    caddr_t data;		/* !< Address of message. */
> +    caddr_t data;
>  
> -    size_t size;		/* !< Size of message. */
> +    size_t size;
>  
>  } RT_TASK_MCB;

Just to underline previous statement: no go (IMHO).

>  
> Index: include/nucleus/thread.h
> ===================================================================
> --- include/nucleus/thread.h	(revision 1383)
> +++ include/nucleus/thread.h	(working copy)
> @@ -1,4 +1,4 @@
> -/*
> +/*! @file nucleus/thread.h
>   * Copyright (C) 2001,2002,2003 Philippe Gerum <rpm@xenomai.org>.
>   *
>   * Xenomai is free software; you can redistribute it and/or modify
> @@ -23,9 +23,13 @@
>  #include <nucleus/timer.h>
>  
>  /* Status flags */
> -#define XNSUSP    0x00000001	/* Suspended */
> -#define XNPEND    0x00000002	/* Sleep-wait for a resource */
> -#define XNDELAY   0x00000004	/* Delayed */
> +
> +/*! @def XNSUSP */
> +#define XNSUSP    0x00000001	/*!< @brief Suspended */
> +/*! @def XNPEND */
> +#define XNPEND    0x00000002	/*!< Sleep-wait for a resource */
> +/*! @def XNPEND */
> +#define XNDELAY   0x00000004	/*!< Delayed */
>  #define XNREADY   0x00000008	/* Linked to the ready queue */
>  #define XNDORMANT 0x00000010	/* Not started yet or killed */
>  #define XNZOMBIE  0x00000020	/* Zombie thread in deletion process */

Also a repetition: would be nice if we could avoid the @def.

Thanks,
Jan


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 250 bytes --]

Re: [Xenomai-help] Re: RT_TASK_INFO status

[Philippe Gerum]

Hi Nate,

On Thu, 2006-07-27 at 15:45 -0700, Nathaniel Villaume wrote:
> Jan,
> Ok, so I played around with your request some.
> 
>  My goal here is to produce documentation, but not at the expense of 
> source-code readability and maintainability.  It's not hard to document 
> defines, but it CAN make the source look uglier.
> Witness nucleus/thread.h:
> 
> /*! @def XNSUSP */
> #define XNSUSP 0x00000001 /*!< @brief Suspended */
> 
> /*! @define XNSUSP */
> #define XNSUSP 0x00000002 /*!< Sleep-wait for a resource. */
> 
> In the first case, @brief is used to get the comment up into the brief 
> listing (duh). If this is not done, then a detailed section is created 
> with the comment, which is a little kludgier on the output end, but 
> still completely usable.
> 
> Second order of business: refering to this new documentation. In 
> include/native/task.h I made a group native_task_status that encompasses 
> all the define documentation. This makes it easy to refer to from within 
> the RT_TASK_INFO::status documentation (and anywhere else)
> 
> Third: I removed the duplication as you requested. This is not without 
> consequence.  Please note the difference between RT_TASK_INFO and 
> RT_TASK_MCB (which remainded the same).  To keep the brief member 
> documentation, I had to use the /**  comment */ syntax. This is 
> inconsistent with other usage, but... this gives the results we want.
> 
> Please see the patch and let me know what you think for this initial set.

Regarding the inline vs out-of-line typedef documentation, I would also
go for inlining it, to help preventing discrepancies between comments
and implementation, provided that we keep such doc reasonably terse
(IOW, making sure that those typedefs still look like C language).

> Again, the decisions to be made are:
> 1.) Do we document the defines at all?
> 1a) If so, do we include brief in the define documentation (or not)?

The bottom line is that defines are assigned their meaning by the
routines which accept or return them as values, which in turn means that
a back link to those routines is likely the best documentation we could
bring to the reader. In any case, the routines would document the flags
they manipulate.

> 1b) Do we group the defines (or not) for easy reference? (they show up 
> under modules/native/Task Status)

It wouldn't hurt, even if I'm not sure that people would search for
information starting from the set of available flags; I guess that they
would rather seek a feature, therefore they would first look for a
routine providing the needed functionality, which ends up manipulating
the flags. This said, the way we document the nucleus for people
implementing skins is another story, since this is clearly a different
use case.

> 
> My default action is to continue with the style/grouping as in the patch.
> 
> -Nate
> 
> Jan Kiszka wrote:
> 
> >Nathaniel Villaume wrote:
> >  
> >
> >>In RT_TASK_INFO, can someone tell me what is the set of all possible
> >>values for status?
> >>I'd like to include that in the documentation.
> >>    
> >>
> >
> >They are defined in include/native/task.h [1], but they widely redirect
> >to defines in include/nucleus/thread.h [2]. Maybe you could add comments
> >to the native/task.h defines and include them in doxygen.
> >
> >Thanks again for your effort!
> >Jan
> >
> >[1]http://www.rts.uni-hannover.de/xenomai/lxr/source/include/native/task.h#L37
> >[2]http://www.rts.uni-hannover.de/xenomai/lxr/source/include/nucleus/thread.h#L25
> >
> >  
> >
> plain text document attachment (task_defines.diff)
> Index: include/native/task.h
> ===================================================================
> --- include/native/task.h	(revision 1383)
> +++ include/native/task.h	(working copy)
> @@ -34,8 +34,20 @@
>  #define T_CPU(cpu) (1 << (24 + (cpu & 7))) /* Up to 8 cpus [0-7] */
>  #define T_CPUMASK  0xff000000
>  
> -/* Status/mode flags. */
> -#define T_BLOCKED  XNPEND
> +/*! 
> +  \ingroup native
> +  @defgroup native_task_status Task Status 
> +  @brief Defines used to specify task state and/or mode 
> +  */
> +/*! @addtogroup native_task_status 
> +  @{
> +  */
> +
> +/*! @def T_BLOCKED  
> +  Task is blocked. See define #XNPEND*/
> +#define T_BLOCKED  XNPEND 
> +/*! @def T_DELAYED  
> +  Task is delayed. See define #XNDELAY*/
>  #define T_DELAYED  XNDELAY
>  #define T_READY    XNREADY
>  #define T_DORMANT  XNDORMANT
> @@ -49,6 +61,7 @@
>  #define T_RPIOFF   XNRPIOFF
>  #define T_PRIMARY  0x00000200	/* Recycle internal bits status which */
>  #define T_JOINABLE 0x00000400	/* won't be passed to the nucleus.  */
> +/*! @} */ /* Ends addtogroup native_task_status */
>  
>  /* Task hook types. */
>  #define T_HOOK_START  XNHOOK_THREAD_START
> @@ -68,31 +81,50 @@
>  struct rt_queue_msg;
>  struct rt_task;
>  
> +/*! @brief Structure containing task-information useful to users.
> + *
> + *  @see rt_task_inquire()
> +  */
>  typedef struct rt_task_info {
> +    
> +    /** Base priority. */
> +    int bprio;  
>  
> -    int bprio;			/* !< Base priority. */
> +    /** Current priority. Can change through Priority Inheritance.*/
> +    int cprio;
> +    
> +    /** Task's status.
> +     * Status may be any of the defines in task.h
> +     *  @see native_task_status shows possible values.
> +     */
> +    unsigned status; 
> +    
> +    /** Time of next release.*/
> +    RTIME relpoint; 
> +    
> +    /** Symbolic name assigned in creation */
> +    char name[XNOBJECT_NAME_LEN];  
>  
> -    int cprio;			/* !< Current priority. */
> -
> -    unsigned status;		/* !< Status. */
> -
> -    RTIME relpoint;		/* !< Next periodic release point. */
> -
> -    char name[XNOBJECT_NAME_LEN]; /* !< Symbolic name. */
> -
>  } RT_TASK_INFO;
>  
>  #define RT_MCB_FSTORE_LIMIT  64
> +/*! @typedef RT_TASK_MCB
> +  @brief Structure used in passing messages between tasks.
>  
> +  @param  flowid  Flow identifier.
> +  @param  opcode  Operation code.
> +  @param  data    Message address.
> +  @param  size    Message size (bytes).
> +*/
>  typedef struct rt_task_mcb {
>  
> -    int flowid;			/* !< Flow identifier. */
> +    int flowid;
>  
> -    int opcode;			/* !< Operation code. */
> +    int opcode;
>  
> -    caddr_t data;		/* !< Address of message. */
> +    caddr_t data;
>  
> -    size_t size;		/* !< Size of message. */
> +    size_t size;
>  
>  } RT_TASK_MCB;
>  
> Index: include/nucleus/thread.h
> ===================================================================
> --- include/nucleus/thread.h	(revision 1383)
> +++ include/nucleus/thread.h	(working copy)
> @@ -1,4 +1,4 @@
> -/*
> +/*! @file nucleus/thread.h
>   * Copyright (C) 2001,2002,2003 Philippe Gerum <rpm@xenomai.org>.
>   *
>   * Xenomai is free software; you can redistribute it and/or modify
> @@ -23,9 +23,13 @@
>  #include <nucleus/timer.h>
>  
>  /* Status flags */
> -#define XNSUSP    0x00000001	/* Suspended */
> -#define XNPEND    0x00000002	/* Sleep-wait for a resource */
> -#define XNDELAY   0x00000004	/* Delayed */
> +
> +/*! @def XNSUSP */
> +#define XNSUSP    0x00000001	/*!< @brief Suspended */
> +/*! @def XNPEND */
> +#define XNPEND    0x00000002	/*!< Sleep-wait for a resource */
> +/*! @def XNPEND */
> +#define XNDELAY   0x00000004	/*!< Delayed */
>  #define XNREADY   0x00000008	/* Linked to the ready queue */
>  #define XNDORMANT 0x00000010	/* Not started yet or killed */
>  #define XNZOMBIE  0x00000020	/* Zombie thread in deletion process */
> _______________________________________________
> Xenomai-help mailing list
> Xenomai-help@domain.hid
> https://mail.gna.org/listinfo/xenomai-help
-- 
Philippe.

Re: [Xenomai-help] Re: RT_TASK_INFO status

[Gilles Chanteperdrix]

Jan Kiszka wrote:
 > > Third: I removed the duplication as you requested. This is not without
 > > consequence.  Please note the difference between RT_TASK_INFO and
 > > RT_TASK_MCB (which remainded the same).  To keep the brief member
 > > documentation, I had to use the /**  comment */ syntax. This is
 > > inconsistent with other usage, but... this gives the results we want.
 > 
 > Yeah, I noticed this as well. Is this somewhere documented in the
 > doxygen manual? Anyway, I prefer the output format of "/**" or "/**<"
 > for such small structures like we have here.

Here is how (I think) this works:
- the '<' syntax may only be used to comment members of something larger
  like a structure or union
- they will not appear if the larger thing is not itself commented
- putting a documentation with a /** */ before the member is equivalent
  to putting a documentation block with a /**< */ after the member.

As for the brief documentation, the autobrief mode is enabled, so the
first sentence of each documentation block should be taken as brief
automatically.

-- 


					    Gilles Chanteperdrix.

Re: [Xenomai-help] Re: RT_TASK_INFO status

[Nathaniel Villaume]

[-- Attachment #1: Type: text/plain, Size: 290 bytes --]

Please see attached diff. I think I found a good way to do it that 
preserves the readable C-code style ( I gave up using the @define command).
This patch includes changes to the defines and the RT_TASK_INFO and 
RT_TASK_MCB structures.

Let me know if you want something different.

-Nate

[-- Attachment #2: defines_documentation.diff --]
[-- Type: text/plain, Size: 7279 bytes --]

Index: include/native/task.h
===================================================================
--- include/native/task.h	(revision 1383)
+++ include/native/task.h	(working copy)
@@ -34,21 +34,28 @@
 #define T_CPU(cpu) (1 << (24 + (cpu & 7))) /* Up to 8 cpus [0-7] */
 #define T_CPUMASK  0xff000000
 
-/* Status/mode flags. */
-#define T_BLOCKED  XNPEND
-#define T_DELAYED  XNDELAY
-#define T_READY    XNREADY
-#define T_DORMANT  XNDORMANT
-#define T_STARTED  XNSTARTED
-#define T_BOOST    XNBOOST
-#define T_LOCK     XNLOCK
-#define T_RRB      XNRRB
-#define T_NOSIG    XNASDI
-#define T_SHIELD   XNSHIELD
-#define T_WARNSW   XNTRAPSW
-#define T_RPIOFF   XNRPIOFF
+/*! 
+  \ingroup native
+  @defgroup native_task_status Task Status 
+  @brief Defines used to specify task state and/or mode 
+  @{
+ */
+
+#define T_BLOCKED  XNPEND     /**< See #XNPEND    */
+#define T_DELAYED  XNDELAY    /**< See #XNDELAY   */
+#define T_READY    XNREADY    /**< See #XNREADY   */
+#define T_DORMANT  XNDORMANT  /**< See #XNDORMANT */
+#define T_STARTED  XNSTARTED  /**< See #XNSTARTED */
+#define T_BOOST    XNBOOST    /**< See #XNBOOST   */
+#define T_LOCK     XNLOCK     /**< See #XNLOCK    */
+#define T_RRB      XNRRB      /**< See #XNRRB     */
+#define T_NOSIG    XNASDI     /**< See #XNASDI    */ 
+#define T_SHIELD   XNSHIELD   /**< See #XNSHIELD  */ 
+#define T_WARNSW   XNTRAPSW   /**< See #XNTRAPSW  */ 
+#define T_RPIOFF   XNRPIOFF   /**< See #XNRPIOFF  */ 
 #define T_PRIMARY  0x00000200	/* Recycle internal bits status which */
 #define T_JOINABLE 0x00000400	/* won't be passed to the nucleus.  */
+/*! @} */ /* Ends doxygen-group native_task_status */
 
 /* Task hook types. */
 #define T_HOOK_START  XNHOOK_THREAD_START
@@ -68,31 +75,38 @@
 struct rt_queue_msg;
 struct rt_task;
 
+/** Structure containing task-information useful to users.
+ *
+ *  @see rt_task_inquire()
+ */
 typedef struct rt_task_info {
+    
+    int bprio;  /**< Base priority. */
 
-    int bprio;			/* !< Base priority. */
+    int cprio; /**< Current priority. May change through Priority Inheritance.*/
+    
+    unsigned status; /**< Task's status. @see native_task_status */ 
+    
+    RTIME relpoint; /**< Time of next release.*/ 
+    
+    char name[XNOBJECT_NAME_LEN];  /**< Symbolic name assigned at creation. */
 
-    int cprio;			/* !< Current priority. */
-
-    unsigned status;		/* !< Status. */
-
-    RTIME relpoint;		/* !< Next periodic release point. */
-
-    char name[XNOBJECT_NAME_LEN]; /* !< Symbolic name. */
-
 } RT_TASK_INFO;
 
 #define RT_MCB_FSTORE_LIMIT  64
 
+/** Structure used in passing messages between tasks.
+  @see rt_task_send(), rt_task_reply(), rt_task_receive()
+*/
 typedef struct rt_task_mcb {
 
-    int flowid;			/* !< Flow identifier. */
+    int flowid;   /**< Flow identifier. */
 
-    int opcode;			/* !< Operation code. */
+    int opcode;   /**< Operation code. */
 
-    caddr_t data;		/* !< Address of message. */
+    caddr_t data; /**< Message address. */
 
-    size_t size;		/* !< Size of message. */
+    size_t size;  /**< Message size (bytes). */
 
 } RT_TASK_MCB;
 
Index: include/nucleus/thread.h
===================================================================
--- include/nucleus/thread.h	(revision 1383)
+++ include/nucleus/thread.h	(working copy)
@@ -1,4 +1,4 @@
-/*
+/* 
  * Copyright (C) 2001,2002,2003 Philippe Gerum <rpm@xenomai.org>.
  *
  * Xenomai is free software; you can redistribute it and/or modify
@@ -22,38 +22,48 @@
 
 #include <nucleus/timer.h>
 
+/*! @ingroup nucleus 
+  @defgroup nucleus_status_mode Status and Mode Defines.
+  @brief These defines are the used by the skins to report status of 
+         tasks and other objects. 
+  @{
+*/
+
 /* Status flags */
-#define XNSUSP    0x00000001	/* Suspended */
-#define XNPEND    0x00000002	/* Sleep-wait for a resource */
-#define XNDELAY   0x00000004	/* Delayed */
-#define XNREADY   0x00000008	/* Linked to the ready queue */
-#define XNDORMANT 0x00000010	/* Not started yet or killed */
-#define XNZOMBIE  0x00000020	/* Zombie thread in deletion process */
-#define XNRESTART 0x00000040	/* Restarting thread */
-#define XNSTARTED 0x00000080	/* Could be restarted */
-#define XNRELAX   0x00000100	/* Relaxed shadow thread (blocking bit) */
-#define XNHELD    0x00000200	/* Held thread from suspended partition */
 
-#define XNTIMEO   0x00000400	/* Woken up due to a timeout condition */
-#define XNRMID    0x00000800	/* Pending on a removed resource */
-#define XNBREAK   0x00001000	/* Forcibly awaken from a wait state */
-#define XNKICKED  0x00002000	/* Kicked upon Linux signal (shadow only) */
-#define XNBOOST   0x00004000	/* Undergoes regular PIP boost */
-#define XNDEBUG   0x00008000	/* Hit debugger breakpoint (shadow only) */
+#define XNSUSP    0x00000001 /**< Suspended. */
+#define XNPEND    0x00000002 /**< Sleep-wait for a resource. */
+#define XNDELAY   0x00000004 /**< Delayed */
+#define XNREADY   0x00000008 /**< Linked to the ready queue. */
+#define XNDORMANT 0x00000010 /**< Not started yet or killed */
+#define XNZOMBIE  0x00000020 /**< Zombie thread in deletion process */
+#define XNRESTART 0x00000040 /**< Restarting thread */
+#define XNSTARTED 0x00000080 /**< Could be restarted */
+#define XNRELAX   0x00000100 /**< Relaxed shadow thread (blocking bit) */
+#define XNHELD    0x00000200 /**< Held thread from suspended partition */
 
+#define XNTIMEO   0x00000400 /**< Woken up due to a timeout condition */
+#define XNRMID    0x00000800 /**< Pending on a removed resource */
+#define XNBREAK   0x00001000 /**< Forcibly awaken from a wait state */
+#define XNKICKED  0x00002000 /**< Kicked upon Linux signal (shadow only) */
+#define XNBOOST   0x00004000 /**< Undergoes regular PIP boost */
+#define XNDEBUG   0x00008000 /**< Hit debugger breakpoint (shadow only) */
+
 /* Mode flags. */
-#define XNLOCK    0x00010000	/* Not preemptible */
-#define XNRRB     0x00020000	/* Undergoes a round-robin scheduling */
-#define XNASDI    0x00040000	/* ASR are disabled */
-#define XNSHIELD  0x00080000	/* IRQ shield is enabled (shadow only) */
-#define XNTRAPSW  0x00100000	/* Trap execution mode switches */
-#define XNRPIOFF  0x00200000	/* Stop priority coupling (shadow only) */
+#define XNLOCK    0x00010000 /**< Not preemptible */
+#define XNRRB     0x00020000 /**< Undergoes a round-robin scheduling */
+#define XNASDI    0x00040000 /**< ASR are disabled */
+#define XNSHIELD  0x00080000 /**< IRQ shield is enabled (shadow only) */
+#define XNTRAPSW  0x00100000 /**< Trap execution mode switches */
+#define XNRPIOFF  0x00200000 /**< Stop priority coupling (shadow only) */
 
-#define XNFPU     0x00400000	/* Thread uses FPU */
-#define XNSHADOW  0x00800000	/* Shadow thread */
-#define XNROOT    0x01000000	/* Root thread (i.e. Linux/IDLE) */
-#define XNINVPS   0x02000000	/* Using inverted priority scale */
+#define XNFPU     0x00400000 /**< Thread uses FPU */
+#define XNSHADOW  0x00800000 /**< Shadow thread */
+#define XNROOT    0x01000000 /**< Root thread (that is, Linux/IDLE) */
+#define XNINVPS   0x02000000 /**< Using inverted priority scale */
 
+/*! @} */ /* Ends doxygen comment group: nucleus_status_modes */
+
 /*
   Must follow the declaration order of the above bits. Status symbols
   are defined as follows:

Re: [Xenomai-help] Re: RT_TASK_INFO status

[Jan Kiszka]

[-- Attachment #1: Type: text/plain, Size: 8352 bytes --]

Nathaniel Villaume wrote:
> Please see attached diff. I think I found a good way to do it that
> preserves the readable C-code style ( I gave up using the @define command).
> This patch includes changes to the defines and the RT_TASK_INFO and
> RT_TASK_MCB structures.
> 
> Let me know if you want something different.
> 

The patch looks good to me, and I assume the output does so as well. :)

Thanks,
Jan

> -Nate
> 
> 
> ------------------------------------------------------------------------
> 
> Index: include/native/task.h
> ===================================================================
> --- include/native/task.h	(revision 1383)
> +++ include/native/task.h	(working copy)
> @@ -34,21 +34,28 @@
>  #define T_CPU(cpu) (1 << (24 + (cpu & 7))) /* Up to 8 cpus [0-7] */
>  #define T_CPUMASK  0xff000000
>  
> -/* Status/mode flags. */
> -#define T_BLOCKED  XNPEND
> -#define T_DELAYED  XNDELAY
> -#define T_READY    XNREADY
> -#define T_DORMANT  XNDORMANT
> -#define T_STARTED  XNSTARTED
> -#define T_BOOST    XNBOOST
> -#define T_LOCK     XNLOCK
> -#define T_RRB      XNRRB
> -#define T_NOSIG    XNASDI
> -#define T_SHIELD   XNSHIELD
> -#define T_WARNSW   XNTRAPSW
> -#define T_RPIOFF   XNRPIOFF
> +/*! 
> +  \ingroup native
> +  @defgroup native_task_status Task Status 
> +  @brief Defines used to specify task state and/or mode 
> +  @{
> + */
> +
> +#define T_BLOCKED  XNPEND     /**< See #XNPEND    */
> +#define T_DELAYED  XNDELAY    /**< See #XNDELAY   */
> +#define T_READY    XNREADY    /**< See #XNREADY   */
> +#define T_DORMANT  XNDORMANT  /**< See #XNDORMANT */
> +#define T_STARTED  XNSTARTED  /**< See #XNSTARTED */
> +#define T_BOOST    XNBOOST    /**< See #XNBOOST   */
> +#define T_LOCK     XNLOCK     /**< See #XNLOCK    */
> +#define T_RRB      XNRRB      /**< See #XNRRB     */
> +#define T_NOSIG    XNASDI     /**< See #XNASDI    */ 
> +#define T_SHIELD   XNSHIELD   /**< See #XNSHIELD  */ 
> +#define T_WARNSW   XNTRAPSW   /**< See #XNTRAPSW  */ 
> +#define T_RPIOFF   XNRPIOFF   /**< See #XNRPIOFF  */ 
>  #define T_PRIMARY  0x00000200	/* Recycle internal bits status which */
>  #define T_JOINABLE 0x00000400	/* won't be passed to the nucleus.  */
> +/*! @} */ /* Ends doxygen-group native_task_status */
>  
>  /* Task hook types. */
>  #define T_HOOK_START  XNHOOK_THREAD_START
> @@ -68,31 +75,38 @@
>  struct rt_queue_msg;
>  struct rt_task;
>  
> +/** Structure containing task-information useful to users.
> + *
> + *  @see rt_task_inquire()
> + */
>  typedef struct rt_task_info {
> +    
> +    int bprio;  /**< Base priority. */
>  
> -    int bprio;			/* !< Base priority. */
> +    int cprio; /**< Current priority. May change through Priority Inheritance.*/
> +    
> +    unsigned status; /**< Task's status. @see native_task_status */ 
> +    
> +    RTIME relpoint; /**< Time of next release.*/ 
> +    
> +    char name[XNOBJECT_NAME_LEN];  /**< Symbolic name assigned at creation. */
>  
> -    int cprio;			/* !< Current priority. */
> -
> -    unsigned status;		/* !< Status. */
> -
> -    RTIME relpoint;		/* !< Next periodic release point. */
> -
> -    char name[XNOBJECT_NAME_LEN]; /* !< Symbolic name. */
> -
>  } RT_TASK_INFO;
>  
>  #define RT_MCB_FSTORE_LIMIT  64
>  
> +/** Structure used in passing messages between tasks.
> +  @see rt_task_send(), rt_task_reply(), rt_task_receive()
> +*/
>  typedef struct rt_task_mcb {
>  
> -    int flowid;			/* !< Flow identifier. */
> +    int flowid;   /**< Flow identifier. */
>  
> -    int opcode;			/* !< Operation code. */
> +    int opcode;   /**< Operation code. */
>  
> -    caddr_t data;		/* !< Address of message. */
> +    caddr_t data; /**< Message address. */
>  
> -    size_t size;		/* !< Size of message. */
> +    size_t size;  /**< Message size (bytes). */
>  
>  } RT_TASK_MCB;
>  
> Index: include/nucleus/thread.h
> ===================================================================
> --- include/nucleus/thread.h	(revision 1383)
> +++ include/nucleus/thread.h	(working copy)
> @@ -1,4 +1,4 @@
> -/*
> +/* 
>   * Copyright (C) 2001,2002,2003 Philippe Gerum <rpm@xenomai.org>.
>   *
>   * Xenomai is free software; you can redistribute it and/or modify
> @@ -22,38 +22,48 @@
>  
>  #include <nucleus/timer.h>
>  
> +/*! @ingroup nucleus 
> +  @defgroup nucleus_status_mode Status and Mode Defines.
> +  @brief These defines are the used by the skins to report status of 
> +         tasks and other objects. 
> +  @{
> +*/
> +
>  /* Status flags */
> -#define XNSUSP    0x00000001	/* Suspended */
> -#define XNPEND    0x00000002	/* Sleep-wait for a resource */
> -#define XNDELAY   0x00000004	/* Delayed */
> -#define XNREADY   0x00000008	/* Linked to the ready queue */
> -#define XNDORMANT 0x00000010	/* Not started yet or killed */
> -#define XNZOMBIE  0x00000020	/* Zombie thread in deletion process */
> -#define XNRESTART 0x00000040	/* Restarting thread */
> -#define XNSTARTED 0x00000080	/* Could be restarted */
> -#define XNRELAX   0x00000100	/* Relaxed shadow thread (blocking bit) */
> -#define XNHELD    0x00000200	/* Held thread from suspended partition */
>  
> -#define XNTIMEO   0x00000400	/* Woken up due to a timeout condition */
> -#define XNRMID    0x00000800	/* Pending on a removed resource */
> -#define XNBREAK   0x00001000	/* Forcibly awaken from a wait state */
> -#define XNKICKED  0x00002000	/* Kicked upon Linux signal (shadow only) */
> -#define XNBOOST   0x00004000	/* Undergoes regular PIP boost */
> -#define XNDEBUG   0x00008000	/* Hit debugger breakpoint (shadow only) */
> +#define XNSUSP    0x00000001 /**< Suspended. */
> +#define XNPEND    0x00000002 /**< Sleep-wait for a resource. */
> +#define XNDELAY   0x00000004 /**< Delayed */
> +#define XNREADY   0x00000008 /**< Linked to the ready queue. */
> +#define XNDORMANT 0x00000010 /**< Not started yet or killed */
> +#define XNZOMBIE  0x00000020 /**< Zombie thread in deletion process */
> +#define XNRESTART 0x00000040 /**< Restarting thread */
> +#define XNSTARTED 0x00000080 /**< Could be restarted */
> +#define XNRELAX   0x00000100 /**< Relaxed shadow thread (blocking bit) */
> +#define XNHELD    0x00000200 /**< Held thread from suspended partition */
>  
> +#define XNTIMEO   0x00000400 /**< Woken up due to a timeout condition */
> +#define XNRMID    0x00000800 /**< Pending on a removed resource */
> +#define XNBREAK   0x00001000 /**< Forcibly awaken from a wait state */
> +#define XNKICKED  0x00002000 /**< Kicked upon Linux signal (shadow only) */
> +#define XNBOOST   0x00004000 /**< Undergoes regular PIP boost */
> +#define XNDEBUG   0x00008000 /**< Hit debugger breakpoint (shadow only) */
> +
>  /* Mode flags. */
> -#define XNLOCK    0x00010000	/* Not preemptible */
> -#define XNRRB     0x00020000	/* Undergoes a round-robin scheduling */
> -#define XNASDI    0x00040000	/* ASR are disabled */
> -#define XNSHIELD  0x00080000	/* IRQ shield is enabled (shadow only) */
> -#define XNTRAPSW  0x00100000	/* Trap execution mode switches */
> -#define XNRPIOFF  0x00200000	/* Stop priority coupling (shadow only) */
> +#define XNLOCK    0x00010000 /**< Not preemptible */
> +#define XNRRB     0x00020000 /**< Undergoes a round-robin scheduling */
> +#define XNASDI    0x00040000 /**< ASR are disabled */
> +#define XNSHIELD  0x00080000 /**< IRQ shield is enabled (shadow only) */
> +#define XNTRAPSW  0x00100000 /**< Trap execution mode switches */
> +#define XNRPIOFF  0x00200000 /**< Stop priority coupling (shadow only) */
>  
> -#define XNFPU     0x00400000	/* Thread uses FPU */
> -#define XNSHADOW  0x00800000	/* Shadow thread */
> -#define XNROOT    0x01000000	/* Root thread (i.e. Linux/IDLE) */
> -#define XNINVPS   0x02000000	/* Using inverted priority scale */
> +#define XNFPU     0x00400000 /**< Thread uses FPU */
> +#define XNSHADOW  0x00800000 /**< Shadow thread */
> +#define XNROOT    0x01000000 /**< Root thread (that is, Linux/IDLE) */
> +#define XNINVPS   0x02000000 /**< Using inverted priority scale */
>  
> +/*! @} */ /* Ends doxygen comment group: nucleus_status_modes */
> +
>  /*
>    Must follow the declaration order of the above bits. Status symbols
>    are defined as follows:



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 250 bytes --]

Re: [Xenomai-help] Re: RT_TASK_INFO status

[Gilles Chanteperdrix]

Nathaniel Villaume wrote:
 > Please see attached diff. I think I found a good way to do it that 
 > preserves the readable C-code style ( I gave up using the @define command).
 > This patch includes changes to the defines and the RT_TASK_INFO and 
 > RT_TASK_MCB structures.
 > 
 > Let me know if you want something different.

The patch looks good, nobody protested, so, it is applied, thanks. And
sorry for the long response time.

-- 


					    Gilles Chanteperdrix.