Re: [lng-odp] [API-NEXT PATCH v3 3/7] api: doc: re-organize doxygen doc for synchronizer

2015-10-23 Thread Mike Holmes 
On 23 October 2015 at 08:40, Christophe Milard <christophe.mil...@linaro.org
> wrote:

> Well, I agree that the test environment should not prevent API
> improvement: The test environment should simply follow the API as it moves.
> I see no problem with this change as long as the test environment follows
> it. I do see a problem, though, if it does not... What structure should the
> test environment have then? none?
>


This is an api-next patch so it could go in and wait for the follow-up, but
history is starting to show that doing this is starting to leave api-next
changes floating that cannot be merged to master because no one addresses
the gating items. If we take this in I think we need to make a bug to
address the follow up.




>
> On 23 October 2015 at 14:35, Savolainen, Petri (Nokia - FI/Espoo) <
> petri.savolai...@nokia.com> wrote:
>
>>
>>
>>
>>
>> *From:* EXT Mike Holmes [mailto:mike.hol...@linaro.org]
>> *Sent:* Friday, October 23, 2015 3:22 PM
>> *To:* Savolainen, Petri (Nokia - FI/Espoo)
>> *Cc:* lng-odp
>> *Subject:* Re: [lng-odp] [API-NEXT PATCH v3 3/7] api: doc: re-organize
>> doxygen doc for synchronizer
>>
>>
>>
>>
>>
>>
>>
>> On 23 October 2015 at 03:00, Petri Savolainen <petri.savolai...@nokia.com>
>> wrote:
>>
>> Removed module synchronizer from doxygen documentation and
>> introduced new modules for locks, atomics and barriers.
>>
>>
>>
>> This ripples though the to the validation directory structure which is
>> 1:1 in sync with the module definitions.
>>
>> We should move them at the same time.
>>
>>
>>
>> This improves a lot documentation readability. It’s nice that validation
>> suites are named with the same names, but it’s not technically mandatory.
>> API doc readability is number one goal (visible to all users), validation
>> suite development is second (visible to implementers). Majority of people
>> need well documented API and examples, and not validation tests (if they
>> believe vendor on API compatibility).
>>
>>
>>
>> -Petri
>>
>>
>>
>> ___
>> lng-odp mailing list
>> lng-odp@lists.linaro.org
>> https://lists.linaro.org/mailman/listinfo/lng-odp
>>
>>
>


-- 
Mike Holmes
Technical Manager - Linaro Networking Group
Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs
___
lng-odp mailing list
lng-odp@lists.linaro.org
https://lists.linaro.org/mailman/listinfo/lng-odp

Re: [lng-odp] [API-NEXT PATCH v3 3/7] api: doc: re-organize doxygen doc for synchronizer

2015-10-23 Thread Christophe Milard 
As long as the test-environment follows up (within a reasonable time), I am
fine.


On 23 October 2015 at 14:52, Savolainen, Petri (Nokia - FI/Espoo) <
petri.savolai...@nokia.com> wrote:

>
>
>
>
> *From:* EXT Mike Holmes [mailto:mike.hol...@linaro.org]
> *Sent:* Friday, October 23, 2015 3:43 PM
> *To:* Christophe Milard
> *Cc:* Savolainen, Petri (Nokia - FI/Espoo); lng-odp
> *Subject:* Re: [lng-odp] [API-NEXT PATCH v3 3/7] api: doc: re-organize
> doxygen doc for synchronizer
>
>
>
>
>
>
>
> On 23 October 2015 at 08:40, Christophe Milard <
> christophe.mil...@linaro.org> wrote:
>
> Well, I agree that the test environment should not prevent API
> improvement: The test environment should simply follow the API as it moves.
> I see no problem with this change as long as the test environment follows
> it. I do see a problem, though, if it does not... What structure should the
> test environment have then? none?
>
>
>
>
>
> This is an api-next patch so it could go in and wait for the follow-up,
> but history is starting to show that doing this is starting to leave
> api-next changes floating that cannot be merged to master because no one
> addresses the gating items. If we take this in I think we need to make a
> bug to address the follow up.
>
>
>
> It fine to report a bug. Missing validation tests are easier to track with
> code coverage tools, etc. I choose to fix broken API documentation logic
> instead of just copying it (which would have been less work for us all).
>
> -Petri
>
>
>
>
>
>
>
___
lng-odp mailing list
lng-odp@lists.linaro.org
https://lists.linaro.org/mailman/listinfo/lng-odp

Re: [lng-odp] [API-NEXT PATCH v3 3/7] api: doc: re-organize doxygen doc for synchronizer

2015-10-23 Thread Christophe Milard 
Well, I agree that the test environment should not prevent API improvement:
The test environment should simply follow the API as it moves. I see no
problem with this change as long as the test environment follows it. I do
see a problem, though, if it does not... What structure should the test
environment have then? none?

On 23 October 2015 at 14:35, Savolainen, Petri (Nokia - FI/Espoo) <
petri.savolai...@nokia.com> wrote:

>
>
>
>
> *From:* EXT Mike Holmes [mailto:mike.hol...@linaro.org]
> *Sent:* Friday, October 23, 2015 3:22 PM
> *To:* Savolainen, Petri (Nokia - FI/Espoo)
> *Cc:* lng-odp
> *Subject:* Re: [lng-odp] [API-NEXT PATCH v3 3/7] api: doc: re-organize
> doxygen doc for synchronizer
>
>
>
>
>
>
>
> On 23 October 2015 at 03:00, Petri Savolainen <petri.savolai...@nokia.com>
> wrote:
>
> Removed module synchronizer from doxygen documentation and
> introduced new modules for locks, atomics and barriers.
>
>
>
> This ripples though the to the validation directory structure which is 1:1
> in sync with the module definitions.
>
> We should move them at the same time.
>
>
>
> This improves a lot documentation readability. It’s nice that validation
> suites are named with the same names, but it’s not technically mandatory.
> API doc readability is number one goal (visible to all users), validation
> suite development is second (visible to implementers). Majority of people
> need well documented API and examples, and not validation tests (if they
> believe vendor on API compatibility).
>
>
>
> -Petri
>
>
>
> ___
> lng-odp mailing list
> lng-odp@lists.linaro.org
> https://lists.linaro.org/mailman/listinfo/lng-odp
>
>
___
lng-odp mailing list
lng-odp@lists.linaro.org
https://lists.linaro.org/mailman/listinfo/lng-odp

Re: [lng-odp] [API-NEXT PATCH v3 3/7] api: doc: re-organize doxygen doc for synchronizer

2015-10-23 Thread Mike Holmes 
On 23 October 2015 at 03:00, Petri Savolainen 
wrote:

> Removed module synchronizer from doxygen documentation and
> introduced new modules for locks, atomics and barriers.


This ripples though the to the validation directory structure which is 1:1
in sync with the module definitions.
We should move them at the same time.



> Removed
> unnecessary group tagging from internal headers, which are not
> visible to doxygen anyway.
>
> Signed-off-by: Petri Savolainen 
> ---
>  include/odp/api/atomic.h  |  2 +-
>  include/odp/api/barrier.h |  4 ++--
>  include/odp/api/rwlock.h  | 19
> +++
>  include/odp/api/rwlock_recursive.h| 17
> ++---
>  include/odp/api/spinlock.h| 11 ---
>  include/odp/api/spinlock_recursive.h  | 15 +--
>  include/odp/api/sync.h|  2 +-
>  include/odp/api/ticketlock.h  | 16
> ++--
>  platform/linux-generic/include/odp/atomic.h   |  2 +-
>  platform/linux-generic/include/odp/barrier.h  |  8 
>  .../linux-generic/include/odp/plat/atomic_types.h |  8 
>  .../linux-generic/include/odp/plat/barrier_types.h|  8 
>  .../include/odp/plat/rwlock_recursive_types.h | 13 +
>  .../linux-generic/include/odp/plat/rwlock_types.h | 13 +
>  .../include/odp/plat/spinlock_recursive_types.h   | 13 +
>  .../linux-generic/include/odp/plat/spinlock_types.h   | 14 +-
>  .../linux-generic/include/odp/plat/ticketlock_types.h | 13 +
>  platform/linux-generic/include/odp/rwlock.h   |  8 
>  platform/linux-generic/include/odp/spinlock.h |  8 
>  platform/linux-generic/include/odp/sync.h |  8 
>  platform/linux-generic/include/odp/ticketlock.h   |  9 -
>  platform/linux-generic/include/odp_atomic_internal.h  |  9 -
>  22 files changed, 58 insertions(+), 162 deletions(-)
>
> diff --git a/include/odp/api/atomic.h b/include/odp/api/atomic.h
> index ba5c354..8aacc9d 100644
> --- a/include/odp/api/atomic.h
> +++ b/include/odp/api/atomic.h
> @@ -18,7 +18,7 @@
>  extern "C" {
>  #endif
>
> -/** @addtogroup odp_synchronizers
> +/** @defgroup odp_atomic ODP ATOMIC
>   *  Atomic types and relaxed operations. These operations cannot be used
> for
>   *  synchronization.
>   *  @{
> diff --git a/include/odp/api/barrier.h b/include/odp/api/barrier.h
> index 28310ba..8ca2647 100644
> --- a/include/odp/api/barrier.h
> +++ b/include/odp/api/barrier.h
> @@ -18,8 +18,8 @@
>  extern "C" {
>  #endif
>
> -/** @addtogroup odp_synchronizers
> - *  Synchronize threads.
> +/** @defgroup odp_barrier ODP BARRIER
> + *  Thread excution and memory ordering barriers.
>   *  @{
>   */
>
> diff --git a/include/odp/api/rwlock.h b/include/odp/api/rwlock.h
> index d730a70..54f426f 100644
> --- a/include/odp/api/rwlock.h
> +++ b/include/odp/api/rwlock.h
> @@ -17,18 +17,21 @@
>  extern "C" {
>  #endif
>
> -/** @defgroup odp_synchronizers ODP SYNCRONIZERS
> - *  Operations on reader/writer locks.
> - *  A reader/writer lock allows multiple simultaneous readers but only one
> - *  writer at a time.
> - *  A thread that wants write access will have to wait until there are no
> - *  threads that want read access. This casues a risk for starvation.
> - *  @{
> +/**
> + * @defgroup odp_locks ODP LOCKS
> + * @details
> + *  Reader / writer lock (odp_rwlock_t) 
> + *
> + * A reader/writer lock allows multiple simultaneous readers but only one
> + * writer at a time. A thread that wants write access will have to wait
> until
> + * there are no threads that want read access. This casues a risk for
> + * starvation.
> + * @{
>   */
>
>  /**
>   * @typedef odp_rwlock_t
> - * ODP rwlock
> + * ODP reader/writer lock
>   */
>
>
> diff --git a/include/odp/api/rwlock_recursive.h
> b/include/odp/api/rwlock_recursive.h
> index 4c7556a..10b2f79 100644
> --- a/include/odp/api/rwlock_recursive.h
> +++ b/include/odp/api/rwlock_recursive.h
> @@ -17,15 +17,12 @@
>  extern "C" {
>  #endif
>
> -/** @addtogroup odp_synchronizers
> - *  Operations on recursive rwlocks.
> - *  @{
> - */
> -
>  /**
> - * @typedef odp_rwlock_recursive_t
> - * Recursive rwlock
> + * @addtogroup odp_locks
> + * @details
> + *  Recursive reader/writer lock (odp_rwlock_recursive_t) 
>   *
> + * This is recursive version of the reader/writer lock.
>   * A thread can read- or write-acquire a recursive read-write lock
> multiple
>   * times without a deadlock. To release the lock, the thread must unlock
> it
>   * the same number of times. Recursion is supported only for a pure
> series of
> @@ -38,6 +35,12 @@ extern "C" {
>   *
>   * ... but this is not supported.
>   *   * read_lock(); write_lock();

Re: [lng-odp] [API-NEXT PATCH v3 3/7] api: doc: re-organize doxygen doc for synchronizer

2015-10-23 Thread Savolainen, Petri (Nokia - FI/Espoo) 


From: EXT Mike Holmes [mailto:mike.hol...@linaro.org]
Sent: Friday, October 23, 2015 3:22 PM
To: Savolainen, Petri (Nokia - FI/Espoo)
Cc: lng-odp
Subject: Re: [lng-odp] [API-NEXT PATCH v3 3/7] api: doc: re-organize doxygen 
doc for synchronizer



On 23 October 2015 at 03:00, Petri Savolainen 
<petri.savolai...@nokia.com<mailto:petri.savolai...@nokia.com>> wrote:
Removed module synchronizer from doxygen documentation and
introduced new modules for locks, atomics and barriers.

This ripples though the to the validation directory structure which is 1:1 in 
sync with the module definitions.
We should move them at the same time.

This improves a lot documentation readability. It’s nice that validation suites 
are named with the same names, but it’s not technically mandatory. API doc 
readability is number one goal (visible to all users), validation suite 
development is second (visible to implementers). Majority of people need well 
documented API and examples, and not validation tests (if they believe vendor 
on API compatibility).

-Petri

___
lng-odp mailing list
lng-odp@lists.linaro.org
https://lists.linaro.org/mailman/listinfo/lng-odp

[lng-odp] [API-NEXT PATCH v3 3/7] api: doc: re-organize doxygen doc for synchronizer

2015-10-23 Thread Petri Savolainen 
Removed module synchronizer from doxygen documentation and
introduced new modules for locks, atomics and barriers. Removed
unnecessary group tagging from internal headers, which are not
visible to doxygen anyway.

Signed-off-by: Petri Savolainen 
---
 include/odp/api/atomic.h  |  2 +-
 include/odp/api/barrier.h |  4 ++--
 include/odp/api/rwlock.h  | 19 +++
 include/odp/api/rwlock_recursive.h| 17 ++---
 include/odp/api/spinlock.h| 11 ---
 include/odp/api/spinlock_recursive.h  | 15 +--
 include/odp/api/sync.h|  2 +-
 include/odp/api/ticketlock.h  | 16 ++--
 platform/linux-generic/include/odp/atomic.h   |  2 +-
 platform/linux-generic/include/odp/barrier.h  |  8 
 .../linux-generic/include/odp/plat/atomic_types.h |  8 
 .../linux-generic/include/odp/plat/barrier_types.h|  8 
 .../include/odp/plat/rwlock_recursive_types.h | 13 +
 .../linux-generic/include/odp/plat/rwlock_types.h | 13 +
 .../include/odp/plat/spinlock_recursive_types.h   | 13 +
 .../linux-generic/include/odp/plat/spinlock_types.h   | 14 +-
 .../linux-generic/include/odp/plat/ticketlock_types.h | 13 +
 platform/linux-generic/include/odp/rwlock.h   |  8 
 platform/linux-generic/include/odp/spinlock.h |  8 
 platform/linux-generic/include/odp/sync.h |  8 
 platform/linux-generic/include/odp/ticketlock.h   |  9 -
 platform/linux-generic/include/odp_atomic_internal.h  |  9 -
 22 files changed, 58 insertions(+), 162 deletions(-)

diff --git a/include/odp/api/atomic.h b/include/odp/api/atomic.h
index ba5c354..8aacc9d 100644
--- a/include/odp/api/atomic.h
+++ b/include/odp/api/atomic.h
@@ -18,7 +18,7 @@
 extern "C" {
 #endif
 
-/** @addtogroup odp_synchronizers
+/** @defgroup odp_atomic ODP ATOMIC
  *  Atomic types and relaxed operations. These operations cannot be used for
  *  synchronization.
  *  @{
diff --git a/include/odp/api/barrier.h b/include/odp/api/barrier.h
index 28310ba..8ca2647 100644
--- a/include/odp/api/barrier.h
+++ b/include/odp/api/barrier.h
@@ -18,8 +18,8 @@
 extern "C" {
 #endif
 
-/** @addtogroup odp_synchronizers
- *  Synchronize threads.
+/** @defgroup odp_barrier ODP BARRIER
+ *  Thread excution and memory ordering barriers.
  *  @{
  */
 
diff --git a/include/odp/api/rwlock.h b/include/odp/api/rwlock.h
index d730a70..54f426f 100644
--- a/include/odp/api/rwlock.h
+++ b/include/odp/api/rwlock.h
@@ -17,18 +17,21 @@
 extern "C" {
 #endif
 
-/** @defgroup odp_synchronizers ODP SYNCRONIZERS
- *  Operations on reader/writer locks.
- *  A reader/writer lock allows multiple simultaneous readers but only one
- *  writer at a time.
- *  A thread that wants write access will have to wait until there are no
- *  threads that want read access. This casues a risk for starvation.
- *  @{
+/**
+ * @defgroup odp_locks ODP LOCKS
+ * @details
+ *  Reader / writer lock (odp_rwlock_t) 
+ *
+ * A reader/writer lock allows multiple simultaneous readers but only one
+ * writer at a time. A thread that wants write access will have to wait until
+ * there are no threads that want read access. This casues a risk for
+ * starvation.
+ * @{
  */
 
 /**
  * @typedef odp_rwlock_t
- * ODP rwlock
+ * ODP reader/writer lock
  */
 
 
diff --git a/include/odp/api/rwlock_recursive.h 
b/include/odp/api/rwlock_recursive.h
index 4c7556a..10b2f79 100644
--- a/include/odp/api/rwlock_recursive.h
+++ b/include/odp/api/rwlock_recursive.h
@@ -17,15 +17,12 @@
 extern "C" {
 #endif
 
-/** @addtogroup odp_synchronizers
- *  Operations on recursive rwlocks.
- *  @{
- */
-
 /**
- * @typedef odp_rwlock_recursive_t
- * Recursive rwlock
+ * @addtogroup odp_locks
+ * @details
+ *  Recursive reader/writer lock (odp_rwlock_recursive_t) 
  *
+ * This is recursive version of the reader/writer lock.
  * A thread can read- or write-acquire a recursive read-write lock multiple
  * times without a deadlock. To release the lock, the thread must unlock it
  * the same number of times. Recursion is supported only for a pure series of
@@ -38,6 +35,12 @@ extern "C" {
  *
  * ... but this is not supported.
  *   * read_lock(); write_lock(); write_unlock(); read_unlock();
+ * @{
+ */
+
+/**
+ * @typedef odp_rwlock_recursive_t
+ * Recursive rwlock
  */
 
 /**
diff --git a/include/odp/api/spinlock.h b/include/odp/api/spinlock.h
index 9a5a929..154d025 100644
--- a/include/odp/api/spinlock.h
+++ b/include/odp/api/spinlock.h
@@ -18,9 +18,14 @@
 extern "C" {
 #endif
 
-/** @addtogroup odp_synchronizers
- *  Operations on spin locks.
- *  @{
+/**
+ * @addtogroup odp_locks
+ * @details
+ *  Spin lock (odp_spinlock_t) 
+ *
+