From b16f5f0e195cd5e67509aa3b39af7fa72c140817 Mon Sep 17 00:00:00 2001
From: Dirk Ziegelmeier <dirk@ziegelmeier.net>
Date: Thu, 4 Jan 2018 08:23:49 +0100
Subject: [PATCH] Rename tcpip_trycallback() tcpip_callbackmsg_trycallback() to
 avoid confusion with tcpip_try_callback() Add tcpip_callbackmsg_new(),
 tcpip_callbackmsg_delete(), tcpip_callbackmsg_trycallback() to documentation

---
 UPGRADING                |  3 +++
 src/api/tcpip.c          | 25 +++++++++++++++++++------
 src/include/lwip/tcpip.h |  2 +-
 3 files changed, 23 insertions(+), 7 deletions(-)

diff --git a/UPGRADING b/UPGRADING
index 9298e949..806b93c7 100644
--- a/UPGRADING
+++ b/UPGRADING
@@ -10,6 +10,9 @@ with newer versions.
 
   ++ Application changes:
 
+  * tcpip_trycallback() was renamed to tcpip_callbackmsg_trycallback() to avoid confusion
+    with tcpip_try_callback()
+
   * MDNS: Functions mdns_resp_add_netif() and mdns_resp_add_service() do not automatically announce
     any more. Users need to call mdns_resp_announce() after adding netifs or services.
 
diff --git a/src/api/tcpip.c b/src/api/tcpip.c
index c192a0fb..ff01032b 100644
--- a/src/api/tcpip.c
+++ b/src/api/tcpip.c
@@ -473,12 +473,20 @@ tcpip_api_call(tcpip_api_call_fn fn, struct tcpip_api_call_data *call)
 }
 
 /**
+ * @ingroup lwip_os
  * Allocate a structure for a static callback message and initialize it.
- * This is intended to be used to send "static" messages from interrupt context.
- *
+ * The message has a special type such that lwIP never frees it.
+ * This is intended to be used to send "static" messages from interrupt context,
+ * e.g. the message is allocated once and posted several times from an IRQ
+ * using tcpip_callbackmsg_trycallback().
+ * Example usage: Trigger execution of an ethernet IRQ DPC routine in lwIP thread context.
+ * 
  * @param function the function to call
  * @param ctx parameter passed to function
- * @return a struct pointer to pass to tcpip_trycallback().
+ * @return a struct pointer to pass to tcpip_callbackmsg_trycallback().
+ *
+ * @see tcpip_callbackmsg_trycallback()
+ * @see tcpip_callbackmsg_delete()
  */
 struct tcpip_callback_msg *
 tcpip_callbackmsg_new(tcpip_callback_fn function, void *ctx)
@@ -494,9 +502,12 @@ tcpip_callbackmsg_new(tcpip_callback_fn function, void *ctx)
 }
 
 /**
+ * @ingroup lwip_os
  * Free a callback message allocated by tcpip_callbackmsg_new().
  *
  * @param msg the message to free
+ *
+ * @see tcpip_callbackmsg_new()
  */
 void
 tcpip_callbackmsg_delete(struct tcpip_callback_msg *msg)
@@ -505,14 +516,16 @@ tcpip_callbackmsg_delete(struct tcpip_callback_msg *msg)
 }
 
 /**
- * Try to post a callback-message to the tcpip_thread mbox
- * This is intended to be used to send "static" messages from interrupt context.
+ * @ingroup lwip_os
+ * Try to post a callback-message to the tcpip_thread mbox.
  *
  * @param msg pointer to the message to post
  * @return sys_mbox_trypost() return code
+ *
+ * @see tcpip_callbackmsg_new()
  */
 err_t
-tcpip_trycallback(struct tcpip_callback_msg *msg)
+tcpip_callbackmsg_trycallback(struct tcpip_callback_msg *msg)
 {
   LWIP_ASSERT("Invalid mbox", sys_mbox_valid_val(mbox));
   return sys_mbox_trypost(&mbox, msg);
diff --git a/src/include/lwip/tcpip.h b/src/include/lwip/tcpip.h
index 76e4d6d6..b4cd7aaa 100644
--- a/src/include/lwip/tcpip.h
+++ b/src/include/lwip/tcpip.h
@@ -88,7 +88,7 @@ err_t  tcpip_callback(tcpip_callback_fn function, void *ctx);
 
 struct tcpip_callback_msg* tcpip_callbackmsg_new(tcpip_callback_fn function, void *ctx);
 void   tcpip_callbackmsg_delete(struct tcpip_callback_msg* msg);
-err_t  tcpip_trycallback(struct tcpip_callback_msg* msg);
+err_t  tcpip_callbackmsg_trycallback(struct tcpip_callback_msg* msg);
 
 /* free pbufs or heap memory from another context without blocking */
 err_t  pbuf_free_callback(struct pbuf *p);