From 7797ada1f55eb3289702006d628bfe0e72d1f798 Mon Sep 17 00:00:00 2001 From: goldsimon Date: Sat, 24 Nov 2007 21:19:47 +0000 Subject: [PATCH] Added documentation --- src/api/api_msg.c | 7 +++++-- src/include/lwip/api.h | 18 ++++++++++++++++- src/include/lwip/api_msg.h | 41 +++++++++++++++++++++++++++++++------- 3 files changed, 56 insertions(+), 10 deletions(-) diff --git a/src/api/api_msg.c b/src/api/api_msg.c index ec9e6bbf..849b4f41 100644 --- a/src/api/api_msg.c +++ b/src/api/api_msg.c @@ -377,6 +377,8 @@ pcb_new(struct api_msg_msg *msg) { msg->conn->err = ERR_OK; + LWIP_ASSERT("pcb_new: pcb already allocated", msg->conn->pcb.tcp == NULL); + /* Allocate a PCB for this connection */ switch(NETCONNTYPE_GROUP(msg->conn->type)) { #if LWIP_RAW @@ -775,7 +777,7 @@ do_recv(struct api_msg_msg *msg) * @return ERR_OK * ERR_MEM if LWIP_TCPIP_CORE_LOCKING=1 and sending hasn't yet finished */ -err_t +static err_t do_writemore(struct netconn *conn) { err_t err; @@ -996,7 +998,8 @@ do_join_leave_group(struct api_msg_msg *msg) #if LWIP_DNS /** * Callback function that is called when DNS name is resolved - * (or on timeout). + * (or on timeout). A waiting application thread is waked up by + * signaling the semaphore. */ static void do_dns_found(const char *name, struct ip_addr *ipaddr, void *arg) diff --git a/src/include/lwip/api.h b/src/include/lwip/api.h index f384de47..74731dfc 100644 --- a/src/include/lwip/api.h +++ b/src/include/lwip/api.h @@ -93,29 +93,45 @@ enum netconn_igmp { }; #endif /* LWIP_IGMP */ +/* forward-declare some structs to avoid to include their headers */ struct ip_pcb; struct tcp_pcb; struct udp_pcb; struct raw_pcb; +/** A netconn descriptor */ struct netconn { + /** type of the netconn (TCP, UDP or RAW) */ enum netconn_type type; + /** current state of the netconn */ enum netconn_state state; + /** the lwIP internal protocol control block */ union { struct ip_pcb *ip; struct tcp_pcb *tcp; struct udp_pcb *udp; struct raw_pcb *raw; } pcb; + /** the last error this netconn had */ err_t err; + /** mbox that is used mutex-like to synchroneously execute functions + in the core context */ sys_mbox_t mbox; + /** mbox where received packets are stored until they are fetched + by the netconn application thread (can grow quite big) */ sys_mbox_t recvmbox; + /** mbox where new connections are stored until processed + by the application thread */ sys_mbox_t acceptmbox; + /** only used for socket layer */ int socket; #if LWIP_SO_RCVTIMEO + /** timeout to wait for new data to be received + (or connections to arrive for listening netconns) */ int recv_timeout; #endif /* LWIP_SO_RCVTIMEO */ #if LWIP_SO_RCVBUF + /** maximum amount of bytes queued in recvmbox */ int recv_bufsize; #endif /* LWIP_SO_RCVBUF */ u16_t recv_avail; @@ -131,7 +147,7 @@ struct netconn { if data couldn't be sent in the first try. */ u8_t write_delayed; #endif /* LWIP_TCPIP_CORE_LOCKING */ - + /** A callback function that is informed about events for this netconn */ void (* callback)(struct netconn *, enum netconn_evt, u16_t len); }; diff --git a/src/include/lwip/api_msg.h b/src/include/lwip/api_msg.h index 25a002d1..4f5d292b 100644 --- a/src/include/lwip/api_msg.h +++ b/src/include/lwip/api_msg.h @@ -49,50 +49,77 @@ enum netconn_igmp; /* IP addresses and port numbers are expected to be in * the same byte order as in the corresponding pcb. */ +/** This struct includes everything that is necessary to execute a function + for a netconn in another thread context (mainly used to process netconns + in the tcpip_thread context to be thread safe). */ struct api_msg_msg { + /** The netconn which to process - always needed: it includes the semaphore + which is used to block the application thread until the function finished. */ struct netconn *conn; + /** Depending on the executed function, one of these union members is used */ union { - struct netbuf *b; /* do_send */ + /** used for do_send */ + struct netbuf *b; + /** used for do_newconn */ struct { u8_t proto; - } n; /* do_newconn */ + } n; + /** used for do_bind and do_connect */ struct { struct ip_addr *ipaddr; u16_t port; - } bc; /* do_bind, do_connect */ + } bc; + /** used for do_getaddr */ struct { struct ip_addr *ipaddr; u16_t *port; u8_t local; - } ad; /* do_getaddr */ + } ad; + /** used for do_write */ struct { const void *dataptr; int len; u8_t apiflags; - } w; /* do_write */ + } w; + /** used ofr do_recv */ struct { u16_t len; - } r; /* do_recv */ + } r; #if LWIP_IGMP + /** used for do_join_leave_group */ struct { struct ip_addr *multiaddr; struct ip_addr *interface; enum netconn_igmp join_or_leave; - } jl; /* do_join_leave_group */ + } jl; #endif /* LWIP_IGMP */ } msg; }; +/** This struct contains a function to execute in another thread context and + a struct api_msg_msg that serves as an argument for this function. + This is passed to tcpip_apimsg to execute functions in tcpip_thread context. */ struct api_msg { + /** function to execute in tcpip_thread context */ void (* function)(struct api_msg_msg *msg); + /** arguments for this function */ struct api_msg_msg msg; }; #if LWIP_DNS +/** As do_gethostbyname requires more arguments but doesn't require a netconn, + it has its own struct (to avoid struct api_msg getting bigger than necessary). + do_gethostbyname must be called using tcpip_callback instead of tcpip_apimsg + (see netconn_gethostbyname). */ struct dns_api_msg { + /** Hostname to query or dotted IP address string */ const char *name; + /** Rhe resolved address is stored here */ struct ip_addr *addr; + /** This semaphore is posted when the name is resolved, the application thread + should wait on it. */ sys_sem_t sem; + /** Errors are given back here */ err_t *err; }; #endif /* LWIP_DNS */