On 4 February 2015 at 14:50, Savolainen, Petri (NSN - FI/Espoo) <petri.savolai...@nsn.com> wrote: > > >> -----Original Message----- >> From: lng-odp-boun...@lists.linaro.org [mailto:lng-odp- >> boun...@lists.linaro.org] On Behalf Of ext Ola Liljedahl >> Sent: Tuesday, February 03, 2015 6:48 PM >> To: lng-odp@lists.linaro.org >> Subject: [lng-odp] [PATCHv5 14/18] api: odp_shared_memory.h: updated >> return descriptions >> >> Updated doxygen descriptions, particularly the @return/@retval >> descriptions. >> No change of implementation necessary. >> Documented API calls which are guaranteed to handle invalid/stale handles. >> >> Signed-off-by: Ola Liljedahl <ola.liljed...@linaro.org> >> --- >> (This document/code contribution attached is provided under the terms of >> agreement LES-LTM-21309) >> >> include/odp/api/shared_memory.h | 17 ++++++++++------- >> 1 file changed, 10 insertions(+), 7 deletions(-) >> >> diff --git a/include/odp/api/shared_memory.h >> b/include/odp/api/shared_memory.h >> index 5b27b6b..18764ce 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,21 @@ 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 > > > > Missing the failure case. No this was intentional. How can odp_shm_addr() fail? What are those errors? Can the function spuriously return NULL?
Either the shm handle is valid and the function returns an address. Or the handle is invalid and the behavior is undefined (possibly function does not return at all). If we require odp_shm_addr() to detect invalid shm handles, this behavior and requirement needs to be specified. How can an ODP implementer otherwise know what needs to be implemented? How can the test program writer know what scenarios to test and their expected outcomes? > > @retval NULL on failure > > > -Petri > > >> */ >> 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 _______________________________________________ lng-odp mailing list lng-odp@lists.linaro.org http://lists.linaro.org/mailman/listinfo/lng-odp
