From a549ec03826298e91dd9ea6eaa2427c01a55f1fa Mon Sep 17 00:00:00 2001 From: likewise Date: Mon, 27 Dec 2004 14:42:02 +0000 Subject: [PATCH] Added inline source documentation. --- src/core/pbuf.c | 14 +++++++----- src/core/tcp_out.c | 48 ++++++++++++++++++++++++++---------------- src/include/lwip/tcp.h | 21 +++++++----------- 3 files changed, 47 insertions(+), 36 deletions(-) diff --git a/src/core/pbuf.c b/src/core/pbuf.c index 8e23825a..5cd75dda 100644 --- a/src/core/pbuf.c +++ b/src/core/pbuf.c @@ -183,7 +183,7 @@ pbuf_pool_alloc(void) /** - * Allocates a pbuf. + * Allocates a pbuf of the given type (possibly a chain for PBUF_POOL type). * * The actual memory allocated for the pbuf is determined by the * layer at which the pbuf is allocated and the requested size @@ -319,7 +319,7 @@ pbuf_alloc(pbuf_layer l, u16_t length, pbuf_flag flag) LWIP_ASSERT("pbuf_alloc: pbuf->payload properly aligned", ((mem_ptr_t)p->payload % MEM_ALIGNMENT) == 0); break; - /* pbuf references existing (static constant) ROM payload? */ + /* pbuf references existing (non-volatile static constant) ROM payload? */ case PBUF_ROM: /* pbuf references existing (externally allocated) RAM payload? */ case PBUF_REF: @@ -664,8 +664,8 @@ pbuf_cat(struct pbuf *h, struct pbuf *t) { struct pbuf *p; - LWIP_ASSERT("h != NULL", h != NULL); - LWIP_ASSERT("t != NULL", t != NULL); + LWIP_ASSERT("h != NULL (programmer violates API)", h != NULL); + LWIP_ASSERT("t != NULL (programmer violates API)", t != NULL); if ((h == NULL) || (t == NULL)) return; /* proceed to last pbuf of chain */ @@ -675,10 +675,14 @@ pbuf_cat(struct pbuf *h, struct pbuf *t) } /* { p is last pbuf of first h chain, p->next == NULL } */ LWIP_ASSERT("p->tot_len == p->len (of last pbuf in chain)", p->tot_len == p->len); + LWIP_ASSERT("p->next == NULL", p->next == NULL); /* add total length of second chain to last pbuf total of first chain */ p->tot_len += t->tot_len; /* chain last pbuf of head (p) with first of tail (t) */ p->next = t; + /* p->next now references t, but the caller will drop its reference to t, + * so netto there is no change to the reference count of t. + */ } /** @@ -792,7 +796,7 @@ pbuf_dequeue(struct pbuf *p) /* { p->tot_len == p->len } => p is the last pbuf of the first packet */ /* remember next packet on queue in q */ q = p->next; - /* dequeue p from queue */ + /* dequeue packet p from queue */ p->next = NULL; /* any next packet on queue? */ if (q != NULL) { diff --git a/src/core/tcp_out.c b/src/core/tcp_out.c index b4a0a94c..d8612cbf 100644 --- a/src/core/tcp_out.c +++ b/src/core/tcp_out.c @@ -62,16 +62,21 @@ static void tcp_output_segment(struct tcp_seg *seg, struct tcp_pcb *pcb); err_t tcp_send_ctrl(struct tcp_pcb *pcb, u8_t flags) { + /* no data, no length, flags, copy=1, no optdata, no optdatalen */ return tcp_enqueue(pcb, NULL, 0, flags, 1, NULL, 0); - } -/* - * NB. tcp_write() enqueues data for sending, but does not send it - * straight away. It waits in the expectation of more data being sent - * soon (as it can send them more efficiently by combining them - * together). To prompt the system to send data now, call - * tcp_output() after calling tcp_write(). +/** + * Write data for sending (but does not send it immediately). + * + * It waits in the expectation of more data being sent soon (as + * it can send them more efficiently by combining them together). + * To prompt the system to send data now, call tcp_output() after + * calling tcp_write(). + * + * @arg pcb Protocol control block of the TCP connection to enqueue data for. + * + * @see tcp_write() */ err_t @@ -95,12 +100,16 @@ tcp_write(struct tcp_pcb *pcb, const void *arg, u16_t len, u8_t copy) } /** - * Enqueue data for tranmission + * Enqueue either data or TCP options (but not both) for tranmission + * + * * * @arg pcb Protocol control block for the TCP connection to enqueue data for. * @arg arg Pointer to the data to be enqueued for sending. * @arg len Data length in bytes * @arg flags + * @arg copy 1 if data must be copied, 0 if data is non-volatile and can be + * referenced. * @arg optdata * @arg optlen */ @@ -118,6 +127,10 @@ tcp_enqueue(struct tcp_pcb *pcb, void *arg, u16_t len, LWIP_DEBUGF(TCP_OUTPUT_DEBUG, ("tcp_enqueue(pcb=%p, arg=%p, len=%u, flags=%x, copy=%u)\n", (void *)pcb, arg, len, (unsigned int)flags, (unsigned int)copy)); + LWIP_ASSERT("tcp_enqueue: len == 0 || optlen == 0 (programmer violates API)", + len == 0 || optlen == 0); + LWIP_ASSERT("tcp_enqueue: arg == NULL || optdata == NULL (programmer violates API)", + arg == NULL || optdata == NULL); /* fail on too much data */ if (len > pcb->snd_buf) { LWIP_DEBUGF(TCP_OUTPUT_DEBUG | 3, ("tcp_enqueue: too much data (len=%u > snd_buf=%u)\n", len, pcb->snd_buf)); @@ -132,18 +145,18 @@ tcp_enqueue(struct tcp_pcb *pcb, void *arg, u16_t len, LWIP_DEBUGF(TCP_QLEN_DEBUG, ("tcp_enqueue: queuelen: %u\n", (unsigned int)pcb->snd_queuelen)); - /* Check if the queue length exceeds the configured maximum queue - * length. If so, we return an error. */ + /* If total number of pbufs on the unsent/unacked queues exceeds the + * configured maximum, return an error */ queuelen = pcb->snd_queuelen; if (queuelen >= TCP_SND_QUEUELEN) { LWIP_DEBUGF(TCP_OUTPUT_DEBUG | 3, ("tcp_enqueue: too long queue %u (max %u)\n", queuelen, TCP_SND_QUEUELEN)); goto memerr; } if (queuelen != 0) { - LWIP_ASSERT("tcp_enqueue: queue length non-zero and at least one queue non-empty", + LWIP_ASSERT("tcp_enqueue: pbufs on queue => at least one queue non-empty", pcb->unacked != NULL || pcb->unsent != NULL); } else { - LWIP_ASSERT("tcp_enqueue: queue length zero and queues empty", + LWIP_ASSERT("tcp_enqueue: no pbufs on queue => both queues empty", pcb->unacked == NULL && pcb->unsent == NULL); } @@ -168,17 +181,16 @@ tcp_enqueue(struct tcp_pcb *pcb, void *arg, u16_t len, /* first segment of to-be-queued data? */ if (queue == NULL) { - useg = queue = seg; + queue = seg; } /* subsequent segments of to-be-queued data */ else { - /* Attach the segment to the end of the queued segments. */ + /* Attach the segment to the end of the queued segments */ LWIP_ASSERT("useg != NULL", useg != NULL); useg->next = seg; - /* remember last segment of to-be-queued data for next iteration */ - useg = seg; } - /* { useg == seg } */ + /* remember last segment of to-be-queued data for next iteration */ + useg = seg; /* If copy is set, memory should be allocated * and data copied into pbuf, otherwise data comes from @@ -207,7 +219,6 @@ tcp_enqueue(struct tcp_pcb *pcb, void *arg, u16_t len, } /* do not copy data */ else { - /* First, allocate a pbuf for holding the data. * since the referenced data is available at least until it is sent out on the * link (as it has to be ACKed by the remote party) we can safely use PBUF_ROM @@ -328,6 +339,7 @@ tcp_enqueue(struct tcp_pcb *pcb, void *arg, u16_t len, } pcb->snd_lbb += len; pcb->snd_buf -= len; + /* update number of segments on the queues */ pcb->snd_queuelen = queuelen; LWIP_DEBUGF(TCP_QLEN_DEBUG, ("tcp_enqueue: %d (after enqueued)\n", pcb->snd_queuelen)); if (pcb->snd_queuelen != 0) { diff --git a/src/include/lwip/tcp.h b/src/include/lwip/tcp.h index b4bebc90..301a3f02 100644 --- a/src/include/lwip/tcp.h +++ b/src/include/lwip/tcp.h @@ -213,18 +213,13 @@ enum tcp_state { TIME_WAIT = 10 }; - /* the TCP protocol control block */ struct tcp_pcb { -/* Common members of all PCB types */ +/** common PCB members */ IP_PCB; - -/* Protocol specific PCB members */ - - struct tcp_pcb *next; /* for the linked list */ - - enum tcp_state state; /* TCP state */ - +/** protocol specific PCB members */ + struct tcp_pcb *next; /* for the linked list */ + enum tcp_state state; /* TCP state */ u8_t prio; void *callback_arg; @@ -240,7 +235,7 @@ struct tcp_pcb { #define TF_GOT_FIN (u8_t)0x20U /* Connection was closed by the remote end. */ #define TF_NODELAY (u8_t)0x40U /* Disable Nagle algorithm */ - /* receiver varables */ + /* receiver variables */ u32_t rcv_nxt; /* next seqno expected */ u16_t rcv_wnd; /* receiver window */ @@ -253,10 +248,10 @@ struct tcp_pcb { u16_t mss; /* maximum segment size */ - /* RTT estimation variables. */ + /* RTT (round trip time) estimation variables */ u32_t rttest; /* RTT estimate in 500ms ticks */ u32_t rtseq; /* sequence number being timed */ - s16_t sa, sv; + s16_t sa, sv; /* @todo document this */ u16_t rto; /* retransmission time-out */ u8_t nrtx; /* number of retransmissions */ @@ -392,7 +387,7 @@ err_t lwip_tcp_event(void *arg, struct tcp_pcb *pcb, (errf)((arg),(err)) #endif /* LWIP_EVENT_API */ -/* This structure is used to repressent TCP segments when queued. */ +/* This structure represents a TCP segment on the unsent and unacked queues */ struct tcp_seg { struct tcp_seg *next; /* used when putting segements on a queue */ struct pbuf *p; /* buffer containing data + TCP header */