sys_arch.txt, api.h, api_lib.c, api_msg.h, api_msg.c, tcpip.c, sys.h, opt.h: Introduce changes for task #7490 "Add return value to sys_mbox_post" with some modifications in the sys_mbox api: sys_mbox_new take a "size" parameters which indicate the number of pointers query by the mailbox. There is three defines in opt.h to indicate sizes for tcpip::mbox, netconn::recvmbox, and for the netconn::acceptmbox. Port maintainers, you can decide to just add this new parameter in your implementation, but to ignore it to keep the previous behavior. The new sys_mbox_trypost function return a value to know if the mailbox is full or if the message is posted. Take a look to sys_arch.txt for more details. This new function is used in tcpip_input (so, can be called in an interrupt context since the function is not blocking), and in recv_udp and recv_raw.

doc/sys_arch.txt

@@ -69,9 +69,12 @@ The following functions must be implemented by the sys_arch:
   Notice that lwIP implements a function with a similar name,
   sys_sem_wait(), that uses the sys_arch_sem_wait() function.
 
-- sys_mbox_t sys_mbox_new(void)
+- sys_mbox_t sys_mbox_new(int size)
 
-  Creates an empty mailbox.
+  Creates an empty mailbox for maximum "size" elements. Elements stored
+  in mailboxes are pointers. You have to define macros "_MBOX_SIZE"
+  in your lwipopts.h, or ignore this parameter in your implementation
+  and use a default size.
 
 - void sys_mbox_free(sys_mbox_t mbox)
 
@@ -81,7 +84,13 @@ The following functions must be implemented by the sys_arch:
 
 - void sys_mbox_post(sys_mbox_t mbox, void *msg)
 
-  Posts the "msg" to the mailbox.
+  Posts the "msg" to the mailbox. This function have to block until
+  the "msg" is really posted.
+
+- err_t sys_mbox_trypost(sys_mbox_t mbox, void *msg)
+
+  Try to post the "msg" to the mailbox. Returns ERR_MEM if this one
+  is full, else, ERR_OK if the "msg" is posted.
 
 - u32_t sys_arch_mbox_fetch(sys_mbox_t mbox, void **msg, u32_t timeout)