[PATCHv6,6/9] api: odp_shared_memory.h: updated return descriptions

Message ID 1423084051-12962-7-git-send-email-ola.liljedahl@linaro.org
State New
Headers show

Commit Message

Ola Liljedahl Feb. 4, 2015, 9:07 p.m.
Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org>
---
(This document/code contribution attached is provided under the terms of
agreement LES-LTM-21309)

 include/odp/api/shared_memory.h | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

Comments

Ola Liljedahl Feb. 5, 2015, 12:25 p.m. | #1
On 5 February 2015 at 13:23, Savolainen, Petri (NSN - FI/Espoo)
<petri.savolainen@nsn.com> wrote:
>
>
>> -----Original Message-----
>> From: lng-odp-bounces@lists.linaro.org [mailto:lng-odp-
>> bounces@lists.linaro.org] On Behalf Of ext Ola Liljedahl
>> Sent: Wednesday, February 04, 2015 11:07 PM
>> To: lng-odp@lists.linaro.org
>> Subject: [lng-odp] [PATCHv6 6/9] api: odp_shared_memory.h: updated return
>> descriptions
>>
>> Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org>
>> ---
>> (This document/code contribution attached is provided under the terms of
>> agreement LES-LTM-21309)
>>
>>  include/odp/api/shared_memory.h | 18 +++++++++++-------
>>  1 file changed, 11 insertions(+), 7 deletions(-)
>>
>> diff --git a/include/odp/api/shared_memory.h
>> b/include/odp/api/shared_memory.h
>> index d4445f7..78e11a5 100644
>> --- a/include/odp/api/shared_memory.h
>> +++ b/include/odp/api/shared_memory.h
>> @@ -71,7 +71,8 @@ typedef struct odp_shm_info_t {
>>   * @param[in] flags  Shared memory parameter flags (ODP_SHM_*).
>>   *                   Default value is 0.
>>   *
>> - * @return Pointer to the reserved block, or NULL
>> + * @return Handle of the reserved block
>> + * @retval NULL on failure
>>   */
>
>
>
> There's actually bug in the original text. It should be:
>
> @retval ODP_SHM_INVALID on failure
>
> Maybe it's worth correcting it in this series, instead of correcting it on top of it.
I can fix that.

>
>
> -Petri
>
>
>
>>  odp_shm_t odp_shm_reserve(const char *name, uint64_t size, uint64_t
>> align,
>>                         uint32_t flags);
>> @@ -84,9 +85,8 @@ odp_shm_t odp_shm_reserve(const char *name, uint64_t
>> size, uint64_t align,
>>   *
>>   * @param[in] shm Block handle
>>   *
>> - * @retval 0 if the handle is already free
>> - * @retval 0 if the handle free succeeds
>> - * @retval -1 on failure to free the handle
>> + * @retval 0 on success
>> + * @retval <0 on failure to free the handle
>>   */
>>  int odp_shm_free(odp_shm_t shm);
>>
>> @@ -96,7 +96,7 @@ int odp_shm_free(odp_shm_t shm);
>>   * @param[in] name   Name of the block
>>   *
>>   * @return A handle to the block if it is found by name
>> - * @retval #ODP_SHM_INVALID if the block is not found
>> + * @retval ODP_SHM_INVALID on failure
>>   */
>>  odp_shm_t odp_shm_lookup(const char *name);
>>
>> @@ -106,18 +106,22 @@ odp_shm_t odp_shm_lookup(const char *name);
>>   *
>>   * @param[in] shm   Block handle
>>   *
>> - * @return Memory block address, or NULL on error
>> + * @return Memory block address
>> + * @retval NULL on failure
>>   */
>>  void *odp_shm_addr(odp_shm_t shm);
>>
>>
>>  /**
>>   * Shared memory block info
>> + * @note This is the only shared memory API function which accepts
>> invalid
>> + * shm handles (any bit value) without causing undefined behavior.
>>   *
>>   * @param[in]  shm   Block handle
>>   * @param[out] info  Block info pointer for output
>>   *
>> - * @return 0 on success, otherwise non-zero
>> + * @retval 0 on success
>> + * @retval <0 on failure
>>   */
>>  int odp_shm_info(odp_shm_t shm, odp_shm_info_t *info);
>>
>> --
>> 1.9.1
>>
>>
>> _______________________________________________
>> lng-odp mailing list
>> lng-odp@lists.linaro.org
>> http://lists.linaro.org/mailman/listinfo/lng-odp

Patch

diff --git a/include/odp/api/shared_memory.h b/include/odp/api/shared_memory.h
index d4445f7..78e11a5 100644
--- a/include/odp/api/shared_memory.h
+++ b/include/odp/api/shared_memory.h
@@ -71,7 +71,8 @@  typedef struct odp_shm_info_t {
  * @param[in] flags  Shared memory parameter flags (ODP_SHM_*).
  *                   Default value is 0.
  *
- * @return Pointer to the reserved block, or NULL
+ * @return Handle of the reserved block
+ * @retval NULL on failure
  */
 odp_shm_t odp_shm_reserve(const char *name, uint64_t size, uint64_t align,
 			  uint32_t flags);
@@ -84,9 +85,8 @@  odp_shm_t odp_shm_reserve(const char *name, uint64_t size, uint64_t align,
  *
  * @param[in] shm Block handle
  *
- * @retval 0 if the handle is already free
- * @retval 0 if the handle free succeeds
- * @retval -1 on failure to free the handle
+ * @retval 0 on success
+ * @retval <0 on failure to free the handle
  */
 int odp_shm_free(odp_shm_t shm);
 
@@ -96,7 +96,7 @@  int odp_shm_free(odp_shm_t shm);
  * @param[in] name   Name of the block
  *
  * @return A handle to the block if it is found by name
- * @retval #ODP_SHM_INVALID if the block is not found
+ * @retval ODP_SHM_INVALID on failure
  */
 odp_shm_t odp_shm_lookup(const char *name);
 
@@ -106,18 +106,22 @@  odp_shm_t odp_shm_lookup(const char *name);
  *
  * @param[in] shm   Block handle
  *
- * @return Memory block address, or NULL on error
+ * @return Memory block address
+ * @retval NULL on failure
  */
 void *odp_shm_addr(odp_shm_t shm);
 
 
 /**
  * Shared memory block info
+ * @note This is the only shared memory API function which accepts invalid
+ * shm handles (any bit value) without causing undefined behavior.
  *
  * @param[in]  shm   Block handle
  * @param[out] info  Block info pointer for output
  *
- * @return 0 on success, otherwise non-zero
+ * @retval 0 on success
+ * @retval <0 on failure
  */
 int odp_shm_info(odp_shm_t shm, odp_shm_info_t *info);