From 3cd546aae43d9a1014dae536cb19b867778ab7a1 Mon Sep 17 00:00:00 2001 From: Petri Savolainen Date: Mon, 4 Jan 2016 15:07:15 +0200 Subject: api: thrmask: documented string format Documented string format for odp_thrmask_from_str() and _to_str(). Format is permissive in input, but fixed on output. Signed-off-by: Petri Savolainen Reviewed-by: Bill Fischofer Signed-off-by: Maxim Uvarov --- include/odp/api/thrmask.h | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) (limited to 'include/odp/api/thrmask.h') diff --git a/include/odp/api/thrmask.h b/include/odp/api/thrmask.h index 8666166e0..af0d9bae4 100644 --- a/include/odp/api/thrmask.h +++ b/include/odp/api/thrmask.h @@ -26,27 +26,37 @@ extern "C" { /** * @def ODP_THRMASK_STR_SIZE - * Minimum size of output buffer for odp_thrmask_to_str() + * The maximum number of characters needed to record any thread mask as + * a string (output of odp_thrmask_to_str()). */ /** * Add thread mask bits from a string * - * @param[out] mask Thread mask to modify - * @param str Hexadecimal digits in a string. Thread ID zero is located - * at the least significant bit (0x1). + * Each bit set in the string represents a thread ID to be added into the mask. + * The string is null terminated and consists of hexadecimal digits. It may be + * prepended with '0x' and may contain leading zeros (e.g. 0x0001, 0x1 or 1). + * Thread ID zero is located at the least significant bit (0x1). + * + * @param mask Thread mask to modify + * @param str String of hexadecimal digits */ void odp_thrmask_from_str(odp_thrmask_t *mask, const char *str); /** - * Format Thread mask as a string of hexadecimal digits + * Format a string from thread mask + * + * Output string format is defined in odp_thrmask_from_str() documentation, + * except that the string is always prepended with '0x' and does not have any + * leading zeros (e.g. outputs always 0x1 instead of 0x0001 or 1). * - * @param mask Thread mask to format - * @param[out] str Output buffer (use ODP_THRMASK_STR_SIZE) - * @param size Size of output buffer + * @param mask Thread mask + * @param[out] str String pointer for output + * @param size Size of output buffer. Buffer size ODP_THRMASK_STR_SIZE + * or larger will have enough space for any thread mask. * - * @return number of characters written (including terminating null char) - * @retval <0 on failure (buffer too small) + * @return Number of characters written (including terminating null char) + * @retval <0 on failure (e.g. buffer too small) */ int32_t odp_thrmask_to_str(const odp_thrmask_t *mask, char *str, int32_t size); -- cgit v1.2.3