doc: Clarify semantics of k_msgq_put

Amend Doxygen documentation for k_msgq_put to note that the message
content will not be modified as a result of the function call and
constify data parameter in function prototype.

Fixes #22301

Signed-off-by: Lauren Murphy <lauren.murphy@intel.com>
This commit is contained in:
Lauren Murphy 2020-09-16 21:13:40 -05:00 committed by Maureen Helm
commit f29a2d1ccc
2 changed files with 7 additions and 4 deletions

View file

@ -3997,6 +3997,9 @@ int k_msgq_cleanup(struct k_msgq *msgq);
* This routine sends a message to message queue @a q.
*
* @note Can be called by ISRs.
* @note The message content is copied from @a data into @a msgq and the @a data
* pointer is not retained, so the message content will not be modified
* by this function.
*
* @param msgq Address of the message queue.
* @param data Pointer to the message.
@ -4008,7 +4011,7 @@ int k_msgq_cleanup(struct k_msgq *msgq);
* @retval -ENOMSG Returned without waiting or queue purged.
* @retval -EAGAIN Waiting period timed out.
*/
__syscall int k_msgq_put(struct k_msgq *msgq, void *data, k_timeout_t timeout);
__syscall int k_msgq_put(struct k_msgq *msgq, const void *data, k_timeout_t timeout);
/**
* @brief Receive a message from a message queue.

View file

@ -113,7 +113,7 @@ int k_msgq_cleanup(struct k_msgq *msgq)
}
int z_impl_k_msgq_put(struct k_msgq *msgq, void *data, k_timeout_t timeout)
int z_impl_k_msgq_put(struct k_msgq *msgq, const void *data, k_timeout_t timeout)
{
__ASSERT(!arch_is_in_isr() || K_TIMEOUT_EQ(timeout, K_NO_WAIT), "");
@ -150,7 +150,7 @@ int z_impl_k_msgq_put(struct k_msgq *msgq, void *data, k_timeout_t timeout)
result = -ENOMSG;
} else {
/* wait for put message success, failure, or timeout */
_current->base.swap_data = data;
_current->base.swap_data = (void *) data;
return z_pend_curr(&msgq->lock, key, &msgq->wait_q, timeout);
}
@ -160,7 +160,7 @@ int z_impl_k_msgq_put(struct k_msgq *msgq, void *data, k_timeout_t timeout)
}
#ifdef CONFIG_USERSPACE
static inline int z_vrfy_k_msgq_put(struct k_msgq *q, void *data,
static inline int z_vrfy_k_msgq_put(struct k_msgq *q, const void *data,
k_timeout_t timeout)
{
Z_OOPS(Z_SYSCALL_OBJ(q, K_OBJ_MSGQ));