Done some work on task #1549 (function documentation)

src/core/tcp_in.c

@@ -81,14 +81,15 @@ static void tcp_parseopt(struct tcp_pcb *pcb);
 static err_t tcp_listen_input(struct tcp_pcb_listen *pcb);
 static err_t tcp_timewait_input(struct tcp_pcb *pcb);
 
-/* tcp_input:
+/**
- *
  * The initial input processing of TCP. It verifies the TCP header, demultiplexes
  * the segment between the PCBs and passes it on to tcp_process(), which implements
  * the TCP finite state machine. This function is called by the IP layer (in
  * ip_input()).
+ *
+ * @param p received TCP segment to process (p->payload pointing to the IP header)
+ * @param inp network interface on which this segment was received
  */
-
 void
 tcp_input(struct pbuf *p, struct netif *inp)
 {
@@ -345,12 +346,18 @@ tcp_input(struct pbuf *p, struct netif *inp)
   PERF_STOP("tcp_input");
 }
 
-/* tcp_listen_input():
+/**
- *
  * Called by tcp_input() when a segment arrives for a listening
- * connection.
+ * connection (from tcp_input()).
+ *
+ * @param pcb the tcp_pcb_listen for which a segment arrived
+ * @return ERR_OK if the segment was processed
+ *         another err_t on error
+ *
+ * @note the return value is not (yet?) used in tcp_input()
+ * @note the segment which arrived is saved in global variables, therefore only the pcb
+ *       involved is passed as a parameter to this function
  */
-
 static err_t
 tcp_listen_input(struct tcp_pcb_listen *pcb)
 {
@@ -414,12 +421,15 @@ tcp_listen_input(struct tcp_pcb_listen *pcb)
   return ERR_OK;
 }
 
-/* tcp_timewait_input():
+/**
- *
  * Called by tcp_input() when a segment arrives for a connection in
  * TIME_WAIT.
+ *
+ * @param pcb the tcp_pcb for which a segment arrived
+ *
+ * @note the segment which arrived is saved in global variables, therefore only the pcb
+ *       involved is passed as a parameter to this function
  */
-
 static err_t
 tcp_timewait_input(struct tcp_pcb *pcb)
 {
@@ -432,14 +442,17 @@ tcp_timewait_input(struct tcp_pcb *pcb)
   return tcp_output(pcb);
 }
 
-/* tcp_process
+/**
- *
  * Implements the TCP state machine. Called by tcp_input. In some
  * states tcp_receive() is called to receive data. The tcp_seg
  * argument will be freed by the caller (tcp_input()) unless the
  * recv_data pointer in the pcb is set.
+ *
+ * @param pcb the tcp_pcb for which a segment arrived
+ *
+ * @note the segment which arrived is saved in global variables, therefore only the pcb
+ *       involved is passed as a parameter to this function
  */
-
 static err_t
 tcp_process(struct tcp_pcb *pcb)
 {
@@ -624,8 +637,7 @@ tcp_process(struct tcp_pcb *pcb)
   return ERR_OK;
 }
 
-/* tcp_receive:
+/**
- *
  * Called by tcp_process. Checks if the given segment is an ACK for outstanding
  * data, and if so frees the memory of the buffered data. Next, is places the
  * segment on any of the receive queues (pcb->recved or pcb->ooseq). If the segment
@@ -635,9 +647,10 @@ tcp_process(struct tcp_pcb *pcb)
  * If the incoming segment constitutes an ACK for a segment that was used for RTT
  * estimation, the RTT is estimated here as well.
  *
- * @return 1 if 
+ * Called from tcp_process().
+ *
+ * @return 1 if the incoming segment is the next in sequence, 0 if not
  */
-
 static u8_t
 tcp_receive(struct tcp_pcb *pcb)
 {
@@ -1180,14 +1193,14 @@ tcp_receive(struct tcp_pcb *pcb)
   return accepted_inseq;
 }
 
-/*
+/**
- * tcp_parseopt:
- *
  * Parses the options contained in the incoming segment. (Code taken
  * from uIP with only small changes.)
  *
+ * Called from tcp_listen_input() and tcp_process().
+ *
+ * @param pcb the tcp_pcb for which a segment arrived
  */
-
 static void
 tcp_parseopt(struct tcp_pcb *pcb)
 {
@@ -1203,7 +1216,7 @@ tcp_parseopt(struct tcp_pcb *pcb)
       opt = opts[c];
       if (opt == 0x00) {
         /* End of options. */
-  break;
+        break;
       } else if (opt == 0x01) {
         ++c;
         /* NOP option. */
@@ -1216,7 +1229,7 @@ tcp_parseopt(struct tcp_pcb *pcb)
         /* And we are done processing options. */
         break;
       } else {
-  if (opts[c + 1] == 0) {
+        if (opts[c + 1] == 0) {
           /* If the length field is zero, the options are malformed
              and we don't process them further. */
           break;
@@ -1229,5 +1242,3 @@ tcp_parseopt(struct tcp_pcb *pcb)
   }
 }
 #endif /* LWIP_TCP */
-
-

src/core/tcp_out.c

@@ -58,6 +58,13 @@
 /* Forward declarations.*/
 static void tcp_output_segment(struct tcp_seg *seg, struct tcp_pcb *pcb);
 
+/**
+ * Called by tcp_close() to send a segment including flags but not data.
+ *
+ * @param pcb the tcp_pcb over which to send a segment
+ * @param flags the flags to set in the segment header
+ * @return ERR_OK if sent, another err_t otherwise
+ */
 err_t
 tcp_send_ctrl(struct tcp_pcb *pcb, u8_t flags)
 {
@@ -73,23 +80,27 @@ tcp_send_ctrl(struct tcp_pcb *pcb, u8_t flags)
  * 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. 
+ * @param pcb Protocol control block of the TCP connection to enqueue data for.
+ * @param data pointer to the data to send
+ * @param len length (in bytes) of the data to send
+ * @param copy 1 if data must be copied, 0 if data is non-volatile and can be
+ * referenced.
+ * @return ERR_OK if enqueued, another err_t on error
  * 
  * @see tcp_write()
  */
-
 err_t
-tcp_write(struct tcp_pcb *pcb, const void *arg, u16_t len, u8_t copy)
+tcp_write(struct tcp_pcb *pcb, const void *data, u16_t len, u8_t copy)
 {
-  LWIP_DEBUGF(TCP_OUTPUT_DEBUG, ("tcp_write(pcb=%p, arg=%p, len=%"U16_F", copy=%"U16_F")\n", (void *)pcb,
+  LWIP_DEBUGF(TCP_OUTPUT_DEBUG, ("tcp_write(pcb=%p, data=%p, len=%"U16_F", copy=%"U16_F")\n", (void *)pcb,
-    arg, len, (u16_t)copy));
+    data, len, (u16_t)copy));
   /* connection is in valid state for data transmission? */
   if (pcb->state == ESTABLISHED ||
      pcb->state == CLOSE_WAIT ||
      pcb->state == SYN_SENT ||
      pcb->state == SYN_RCVD) {
     if (len > 0) {
-      return tcp_enqueue(pcb, (void *)arg, len, 0, copy, NULL, 0);
+      return tcp_enqueue(pcb, (void *)data, len, 0, copy, NULL, 0);
     }
     return ERR_OK;
   } else {
@@ -101,16 +112,16 @@ tcp_write(struct tcp_pcb *pcb, const void *arg, u16_t len, u8_t copy)
 /**
  * Enqueue either data or TCP options (but not both) for tranmission
  *
+ * Called by tcp_connect(), tcp_listen_input(), tcp_send_ctrl() and tcp_write().
  *
- * 
+ * @param pcb Protocol control block for the TCP connection to enqueue data for.
- * @arg pcb Protocol control block for the TCP connection to enqueue data for.
+ * @param arg Pointer to the data to be enqueued for sending.
- * @arg arg Pointer to the data to be enqueued for sending.
+ * @param len Data length in bytes
- * @arg len Data length in bytes
+ * @param flags tcp header flags to set in the outgoing segment
- * @arg flags
+ * @param copy 1 if data must be copied, 0 if data is non-volatile and can be
- * @arg copy 1 if data must be copied, 0 if data is non-volatile and can be
  * referenced.
- * @arg optdata
+ * @param optdata
- * @arg optlen
+ * @param optlen
  */
 err_t
 tcp_enqueue(struct tcp_pcb *pcb, void *arg, u16_t len,
@@ -375,7 +386,13 @@ memerr:
   return ERR_MEM;
 }
 
-/* find out what we can send and send it */
+/**
+ * Find out what we can send and send it
+ *
+ * @param pcb Protocol control block for the TCP connection to send data
+ * @return ERR_OK if data has been sent or nothing to send
+ *         another err_t on error
+ */
 err_t
 tcp_output(struct tcp_pcb *pcb)
 {
@@ -518,7 +535,10 @@ tcp_output(struct tcp_pcb *pcb)
 }
 
 /**
- * Actually send a TCP segment over IP
+ * Called by tcp_output() to actually send a TCP segment over IP.
+ *
+ * @param seg the tcp_seg to send
+ * @param pcb the tcp_pcb for the TCP connection used to send the segment
  */
 static void
 tcp_output_segment(struct tcp_seg *seg, struct tcp_pcb *pcb)
@@ -585,6 +605,26 @@ tcp_output_segment(struct tcp_seg *seg, struct tcp_pcb *pcb)
       IP_PROTO_TCP);
 }
 
+/**
+ * Send a TCP RESET packet (empty segment with RST flag set) either to
+ * abort a connection or to show that there is no matching local connection
+ * for a received segment.
+ *
+ * Called by tcp_abort() (to abort a local connection), tcp_input() (if no
+ * matching local pcb was found), tcp_listen_input() (if incoming segment
+ * has ACK flag set) and tcp_process() (received segment in the wrong state)
+ *
+ * Since a RST segment is in most cases not sent for an active connection,
+ * tcp_rst() has a number of arguments that are taken from a tcp_pcb for
+ * most other segment output functions.
+ *
+ * @param seqno the sequence number to use for the outgoing segment
+ * @param ackno the acknowledge number to use for the outgoing segment
+ * @param local_ip the local IP address to send the segment from
+ * @param remote_ip the remote IP address to send the segment to
+ * @param local_port the local TCP port to send the segment from
+ * @param remote_port the remote TCP port to send the segment to
+ */
 void
 tcp_rst(u32_t seqno, u32_t ackno,
   struct ip_addr *local_ip, struct ip_addr *remote_ip,
@@ -621,7 +661,13 @@ tcp_rst(u32_t seqno, u32_t ackno,
   LWIP_DEBUGF(TCP_RST_DEBUG, ("tcp_rst: seqno %"U32_F" ackno %"U32_F".\n", seqno, ackno));
 }
 
-/* requeue all unacked segments for retransmission */
+/**
+ * Requeue all unacked segments for retransmission
+ *
+ * Called by tcp_slowtmr() for slow retransmission.
+ *
+ * @param pcb the tcp_pcb for which to re-enqueue all unacked segments
+ */
 void
 tcp_rexmit_rto(struct tcp_pcb *pcb)
 {
@@ -651,6 +697,13 @@ tcp_rexmit_rto(struct tcp_pcb *pcb)
   tcp_output(pcb);
 }
 
+/**
+ * Requeue the first unacked segment for retransmission
+ *
+ * Called by tcp_receive() for fast retramsmit.
+ *
+ * @param pcb the tcp_pcb for which to retransmit the first unacked segment
+ */
 void
 tcp_rexmit(struct tcp_pcb *pcb)
 {
@@ -678,7 +731,14 @@ tcp_rexmit(struct tcp_pcb *pcb)
   tcp_output(pcb);
 }
 
-
+/**
+ * Send keepalive packets to keep a connection active although
+ * no data is sent over it.
+ *
+ * Called by tcp_slowtmr()
+ *
+ * @param pcb the tcp_pcb for which to send a keepalive packet
+ */
 void
 tcp_keepalive(struct tcp_pcb *pcb)
 {
@@ -722,12 +782,3 @@ tcp_keepalive(struct tcp_pcb *pcb)
 }
 
 #endif /* LWIP_TCP */
-
-
-
-
-
-
-
-
-