netbuf 结构体

  1.  struct netbuf
  2.  {
  3.      struct pbuf *p, *ptr; (1) 
  4.      ip_addr_t addr; (2)
  5.      u16_t port; (3)
  6.  };

**

p 字段 的指针指向 pbuf 链表，这是基于 pbuf 上封装的结构体
ptr 也是指向 pbuf，但是它与 p 字段的指针有一点不一样，因为它可以指向任意的 pbuf，由 netbuf_next()与 netbuf_first()函数来控制。
addr 字段记录了数据发送方的 IP 地址。
port 记录了数据发送方的端口号。

处理 netbuf 字段的带参宏

  1.  #define netbuf_fromaddr(buf) (&((buf)->addr))
  3.  #define netbuf_set_fromaddr(buf, fromaddr) \
  4.           ip_addr_set(&((buf)->addr), fromaddr)
  6.  #define netbuf_fromport(buf) ((buf)->port)

指向不同类型的pbuf链表

image.png

指向相同类型的pbuf链表

image.png

netbuf相关函数

netbuf_new() 申请结构体空间

  1.  struct netbuf *netbuf_new(void)
  2.      {
  3.      struct netbuf *buf;
  5.      buf = (struct netbuf *)memp_malloc(MEMP_NETBUF);
  6.     if (buf != NULL)
  7.      {
  8.      memset(buf, 0, sizeof(struct netbuf));
  9.      }
  10.      return buf;
  11.  }

netbuf_alloc() 申请pbuf内存空间


  1. void * netbuf_alloc(struct netbuf *buf, u16_t size)
  2. {
  3.     LWIP_ERROR("netbuf_alloc: invalid buf", (buf != NULL), return NULL;);
  5.     /* Deallocate any previously allocated memory. */
  6.     if (buf->p != NULL)
  7.     {
  8.         pbuf_free(buf->p);
  9.     }
  10.     buf->p = pbuf_alloc(PBUF_TRANSPORT, size, PBUF_RAM);
  11.     if (buf->p == NULL)
  12.     {
  13.         return NULL;
  14.     }
  15.     LWIP_ASSERT("check that first pbuf can hold size",
  16.                 (buf->p->len >= size));
  17.     buf->ptr = buf->p;
  18.     return buf->p->payload;
  19. }


netbuf_free()释放pbuf的空间


  1. void netbuf_free(struct netbuf *buf)
  2. {
  3.     LWIP_ERROR("netbuf_free: invalid buf", (buf != NULL), return;);
  4.     if (buf->p != NULL)
  5.     {
  6.         pbuf_free(buf->p);
  7.     }
  8.     buf->p = buf->ptr = NULL;
  9. }


netbuf_ref()申请pbuf首部的内存空间

  1.  err_t netbuf_ref(struct netbuf *buf, const void *dataptr, u16_t size)
  2.  {
  3.      LWIP_ERROR("netbuf_ref: invalid buf", (buf != NULL), return ERR_ARG;);
  4.      if (buf->p != NULL)
  5.      {
  6.          pbuf_free(buf->p);
  7.      }
  8.      buf->p = pbuf_alloc(PBUF_TRANSPORT, 0, PBUF_REF);
  9.      if (buf->p == NULL)
  10.      {
  11.          buf->ptr = NULL;
  12.          return ERR_MEM;
  13.      }
  14.      ((struct pbuf_rom *)buf->p)->payload = dataptr;
  15.      buf->p->len = buf->p->tot_len = size;
  16.      buf->ptr = buf->p;
  17.      return ERR_OK;
  18.  }

netbuf_chain()

是将 tail 中的 pbuf 数据连接到 head 中的 pbuf 后面，形成一个 pbuf链表，在调用此函数之后，会将 tail 结构删除。

  1. void netbuf_chain(struct netbuf *head, struct netbuf *tail)
  2. {
  3.     LWIP_ERROR("netbuf_chain: invalid head", (head != NULL), return;);
  4.     LWIP_ERROR("netbuf_chain: invalid tail", (tail != NULL), return;);
  5.     pbuf_cat(head->p, tail->p);
  6.     head->ptr = head->p;
  7.     memp_free(MEMP_NETBUF, tail);
  8. }

netbuf_data()

将 netbuf 结构体中的 ptr 指针指向的 pbuf 数据起始地址填写到 dataptr 中，
同时将数据长度填入 len 中，
netbuf 结构体中 p 字段的指针指向的数据可能是一个 pbuf 链表，但是这个函数的操作只能是将 ptr 指针指向的 pbuf 数据填写到 dataptr 中，
如果想要操作 netbuf 中 p 指向的链表数据，想要使用 netbuf_next()或者 netbuf_first()函数来调整 ptr 指针指向的 pbuf.

  1. err_tm netbuf_data(struct netbuf *buf, void **dataptr, u16_t *len)
  2. {
  3.     LWIP_ERROR("netbuf_data: invalid buf", (buf != NULL), return ERR_ARG;);
  4.     LWIP_ERROR("netbuf_data: invalid dataptr", (dataptr != NULL), return ERR_ARG;);
  5.     LWIP_ERROR("netbuf_data: invalid len", (len != NULL), return ERR_ARG;);
  7.     if (buf->ptr == NULL)
  8.     {
  9.         return ERR_BUF;
  10.     }
  11.     *dataptr = buf->ptr->payload;
  12.     *len = buf->ptr->len;
  13.     return ERR_OK;
  14. }

netbuf_next()与 netbuf_first()

netbuf_next()用于移动 netbuf 的 ptr 数据指针，使 ptr 指针指向 pbuf 链表的下一个 pbuf。
netbuf_first()函数可以将 ptr 指针指向 pbuf 链表的第一个 pbuf。

  1. s8_t netbuf_next(struct netbuf *buf)
  2. {
  3.     LWIP_ERROR("netbuf_next: invalid buf", (buf != NULL), return -1;);
  4.     if (buf->ptr->next == NULL)
  5.     {
  6.         return -1;
  7.     }
  8.     buf->ptr = buf->ptr->next;
  9.     if (buf->ptr->next == NULL)
  10.     {
  11.         return 1;
  12.     }
  13.     return 0;
  14. }
  16. void netbuf_first(struct netbuf *buf)
  17. {
  18.     LWIP_ERROR("netbuf_first: invalid buf", (buf != NULL), return;);
  19.     buf->ptr = buf->p;
  20. }

netbuf_copy()

将 netbuf 结构体数据区域 pbuf 中的所有数据拷贝到 dataptr 指针指向的存储区，
即使 pbuf（链表）中的数据被保存在多个 pbuf 中，它也会完全拷贝出来，len 参数指定要拷贝数据的最大长度，
如果 netbuf 的数据区域空间小于 len 指定的大小，那么内核只会拷贝 netbuf 数据区域大小的数据，

  1.  #define netbuf_copy_partial(buf, dataptr, len, offset) \
  2.  pbuf_copy_partial((buf)->p, (dataptr), (len), (offset))
  3.  #define netbuf_copy(buf,dataptr,len) \
  4.  netbuf_copy_partial(buf, dataptr, len, 0)
  6. u16_t pbuf_copy_partial(const struct pbuf *buf, void *dataptr,
  7.                         u16_t len, u16_t offset)
  8. {
  9.     const struct pbuf *p;
  10.     u16_t left = 0;
  11.     u16_t buf_copy_len;
  12.     u16_t copied_total = 0;
  15.     for (p = buf; len != 0 && p != NULL; p = p->next)
  16.     {
  17.         if ((offset != 0) && (offset >= p->len))
  18.         {
  19.             offset = (u16_t)(offset - p->len);
  20.         }
  21.         else
  22.         {
  23.             buf_copy_len = (u16_t)(p->len - offset);
  24.             if (buf_copy_len > len)
  25.             {
  26.                 buf_copy_len = len;
  27.             } 
  28.             MEMCPY(&((char *)dataptr)[left],
  29.                    &((char *)p->payload)[offset], buf_copy_len);
  30.             copied_total = (u16_t)(copied_total + buf_copy_len);
  31.             left = (u16_t)(left + buf_copy_len);
  32.             len = (u16_t)(len - buf_copy_len);
  33.             offset = 0;
  34.         }
  35.     }
  36.     return copied_total;
  37. }

netbuf_take() 拷贝数据

  1. #define netbuf_take(buf, dataptr, len) \
  2.          pbuf_take((buf)->p, dataptr, len)
  4. err_t
  5.  pbuf_take(struct pbuf *buf, const void *dataptr, u16_t len)
  6. {
  7.     struct pbuf *p;
  8.     size_t buf_copy_len;
  9.     size_t total_copy_len = len;
  10.     size_t copied_total = 0;
  12.     if ((buf == NULL) || (dataptr == NULL) || (buf->tot_len < len))
  13.     {
  14.         return ERR_ARG;
  15.     }
  17.     /* 拷贝数据 */
  18.     for (p = buf; total_copy_len != 0; p = p->next)
  19.     {
  20.         LWIP_ASSERT("pbuf_take: invalid pbuf", p != NULL);
  21.         buf_copy_len = total_copy_len;
  22.         if (buf_copy_len > p->len)
  23.         {
  24.             /* 此 pbuf 无法保存所有剩余数据 */
  25.             buf_copy_len = p->len;
  26.         }
  27.         /* 从 dataptr 拷贝数据到 p->payload*/
  28.         MEMCPY(p->payload, &((const char *)dataptr)[copied_total], buf_copy_len);
  29.         total_copy_len -= buf_copy_len;
  30.         copied_total += buf_copy_len;
  31.     }
  32.     return ERR_OK;
  33. }

其他操作 netbuf 的宏定义

  1.  //获取数据的总长度
  2.  #define netbuf_len(buf) ((buf)->p->tot_len)
  4.  //得到远端 IP 地址（目标 IP 地址）
  5.  #define netbuf_fromaddr(buf) (&((buf)->addr))
  7.  //设置远端 IP 地址（目标 IP 地址）
  8.  #define netbuf_set_fromaddr(buf, fromaddr) \
  9.  ip_addr_set(&((buf)->addr), fromaddr)
  11.  //得到远端端口号
  12.  #define netbuf_fromport(buf) ((buf)->port)

netconn 结构体

它能描述一个连接，供应用程序使用，同时内核的 NETCONN API 接口也对各种连接操作函数进行了统一的封装。

  1. struct netconn
  2. {
  3.     /** netconn 类型 */
  4.     enum netconn_type type;
  5.     /** 当前 netconn 状态 */
  6.     enum netconn_state state;
  7.     /** LwIP 的控制块指针，如 TCP 控制块、UDP 控制块 */
  8.     union
  9.     {
  10.         10 struct ip_pcb *ip;
  11.         struct tcp_pcb *tcp;
  12.         struct udp_pcb *udp;
  13.         struct raw_pcb *raw;
  14.     } pcb;
  15.     err_t pending_err;/** 这个 netconn 最后一个异步未报告的错误 */
  16.     sys_sem_t op_completed; //信号量
  17.     /** 消息邮箱，存储接收的数据，直到它们被提取 */
  18.     sys_mbox_t recvmbox;
  19.     /** 用于 TCP 服务器上的请求连接缓冲区 */
  20.     sys_mbox_t acceptmbox;
  22.     /** socket 描述符，用于 Socket API */
  23.     #if LWIP_SOCKET
  24.     int socket;
  25.     #endif /* LWIP_SOCKET */
  28.     /** 标志 */
  29.     u8_t flags;
  30.     #if LWIP_TCP
  31.     /** 当调用 netconn_write()函数发送的数据不适合发送缓冲区时，
  32.  数据会暂时存储在 current_msg 中，等待数据合适的时候进行发送 */
  33.     struct api_msg *current_msg;
  34.     #endif /* LWIP_TCP */35 /** 连接相关的回调函数 */
  35.         netconn_callback callback;
  36. };

描述 netconn 的类型、状态及回调函数

  1. enum netconn_type
  2.  {
  3.      NETCONN_INVALID = 0,
  4.      /** TCP */
  5.      NETCONN_TCP = 0x10,
  6.      /** UDP */
  7.      NETCONN_UDP = 0x20,
  8.      /** UDP lite */
  9.     NETCONN_UDPLITE = 0x21,
  10.      /** 无校验 UDP */
  11.      NETCONN_UDPNOCHKSUM = 0x22,
  12.      /** Raw */
  13.      NETCONN_RAW = 0x40
  14.  };
  17. enum netconn_state
  18. {
  19.     NETCONN_NONE, //不处于任何状态
  20.     NETCONN_WRITE, //正在写（发送）数据
  21.     NETCONN_LISTEN, //处于监听状态
  22.     NETCONN_CONNECT, //处于连接状态
  23.     NETCONN_CLOSE //处于关闭状态
  24.     };
  27. typedef void (* netconn_callback)(struct netconn *,
  28.                                   enum netconn_evt,
  29.                                   u16_t len);

netconn 函数接口说明

netconn_new() 创建新的连接结构

  1. //该函数本质是宏定义
  2. #define netconn_new(t) \
  3.  netconn_new_with_proto_and_callback(t, 0, NULL)
  5. //真正实现的函数
  6. struct netconn * netconn_new_with_proto_and_callback(enum netconn_type t,
  7.                                      u8_t proto,
  8.                                      netconn_callback callback)
  9. {
  10.     struct netconn *conn;
  11.     API_MSG_VAR_DECLARE(msg);
  12.     API_MSG_VAR_ALLOC_RETURN_NULL(msg);
  14.     conn = netconn_alloc(t, callback); (1)
  15.     if (conn != NULL)
  16.     {
  17.         err_t err;
  19.         API_MSG_VAR_REF(msg).msg.n.proto = proto;
  20.         API_MSG_VAR_REF(msg).conn = conn;
  21.         err = netconn_apimsg(lwip_netconn_do_newconn,
  22.                              &API_MSG_VAR_REF(msg)); (2)
  23.         if (err != ERR_OK)
  24.         {
  25.             sys_sem_free(&conn->op_completed);
  26.             sys_mbox_free(&conn->recvmbox);
  27.             memp_free(MEMP_NETCONN, conn);
  28.             API_MSG_VAR_FREE(msg);
  29.             return NULL;
  30.         }
  31.     }
  32.     API_MSG_VAR_FREE(msg);
  33.     return conn;
  34. }

netconn_delete() 终止连接

它用于删除一个 netconn 连接结构，对于 TCP 连接，如果此时是处于连接状态的，在调用该函数后，将请求内核执行终止连接操作。

  1. err_t netconn_delete(struct netconn *conn)
  2. {
  3.     err_t err;
  5.     /* 判断一下 netconn 结构是否正确 */
  6.     if (conn == NULL)
  7.     {
  8.         return ERR_OK;
  9.     }
  11.     err = netconn_prepare_delete(conn); (1)
  13.     if (err == ERR_OK)
  14.     {
  15.         netconn_free(conn);
  16.     }
  17.     return err;
  18. }
  21. err_t netconn_prepare_delete(struct netconn *conn)
  22. {
  23.     err_t err;
  24.     API_MSG_VAR_DECLARE(msg);
  26.     if (conn == NULL)
  27.     {
  28.         return ERR_OK;
  29.     }
  31.     API_MSG_VAR_ALLOC(msg);
  32.     API_MSG_VAR_REF(msg).conn = conn;
  34.     //记录时间
  35.     API_MSG_VAR_REF(msg).msg.sd.polls_left =
  36.         ((LWIP_TCP_CLOSE_TIMEOUT_MS_DEFAULT
  37.           + TCP_SLOW_INTERVAL - 1) / TCP_SLOW_INTERVAL) + 1;
  39.     err = netconn_apimsg(lwip_netconn_do_delconn,
  40.                          &API_MSG_VAR_REF(msg)); (2)
  42.     API_MSG_VAR_FREE(msg);
  44.     if (err != ERR_OK)
  45.     {
  46.         return err;
  47.     }
  48.     return ERR_OK;
  49. }

netconn_getaddr() 获取IP

连接结构的源 IP 地址、端口号与目标 IP 地址、端口号等信息

  1. err_t netconn_getaddr(struct netconn *conn,
  2.                          ip_addr_t *addr,
  3.                          u16_t *port,
  4.                          u8_t local)
  5. {
  6.     API_MSG_VAR_DECLARE(msg);
  7.     err_t err;
  9.     API_MSG_VAR_ALLOC(msg);
  10.     API_MSG_VAR_REF(msg).conn = conn;
  11.     API_MSG_VAR_REF(msg).msg.ad.local = local;
  12.     msg.msg.ad.ipaddr = addr;
  13.     msg.msg.ad.port = port;
  15.     err = netconn_apimsg(lwip_netconn_do_getaddr, &msg);
  17.     API_MSG_VAR_FREE(msg);
  19.     return err;
  20. }

netconn_bind() 绑定IP

netconn_bind()函数用于将一个 IP 地址及端口号与 netconn 连接结构进行绑定，如果作为服务器端，这一步操作是必然需要的。

  1.  err_t netconn_bind(struct netconn *conn,
  2.               const ip_addr_t *addr,
  3.               u16_t port)
  4.  {
  5.      API_MSG_VAR_DECLARE(msg);
  6.      err_t err;
  8.      /* 如果 IP 地址为空，将设置为 */
  9.      if (addr == NULL)
  10.      {
  11.          addr = IP4_ADDR_ANY;
  12.      }
  14.      API_MSG_VAR_ALLOC(msg);
  15.      API_MSG_VAR_REF(msg).conn = conn;
  16.      API_MSG_VAR_REF(msg).msg.bc.ipaddr = API_MSG_VAR_REF(addr);
  17.      API_MSG_VAR_REF(msg).msg.bc.port = port;
  19.      err = netconn_apimsg(lwip_netconn_do_bind,
  20.                           &API_MSG_VAR_REF(msg));
  22.      API_MSG_VAR_FREE(msg);
  24.      return err;
  25.  }

netconn_connect()客户端主动建立连接

netconn_connect()函数是一个主动建立连接的函数，它一般在客户端中调用，
将服务器端的 IP 地址和端口号与本地的 netconn 连接结构绑定，

  • TCP 协议
    • 使用该函数的时候就是进行握手的过程，调用的应用线程将阻塞至握手完成；
  • UDP 协议
    • 调用该函数只是设置 UDP 控制块的目标 IP 地址与目标端口号
  1. err_t netconn_connect(struct netconn *conn,
  2.                  const ip_addr_t *addr,
  3.                  u16_t port)
  4. {
  5.     API_MSG_VAR_DECLARE(msg);
  6.     err_t err;
  8.     if (addr == NULL)
  9.     {
  10.         addr = IP4_ADDR_ANY;
  11.     }
  13.     API_MSG_VAR_ALLOC(msg);
  14.     API_MSG_VAR_REF(msg).conn = conn;
  15.     API_MSG_VAR_REF(msg).msg.bc.ipaddr = API_MSG_VAR_REF(addr);
  16.     API_MSG_VAR_REF(msg).msg.bc.port = port;
  18.     err = netconn_apimsg(lwip_netconn_do_connect,
  19.                          &API_MSG_VAR_REF(msg));
  21.     API_MSG_VAR_FREE(msg);
  23.     return err;
  24. }

netconn_disconnect() 终止UDP 协议


  1. err_t netconn_disconnect(struct netconn *conn)
  2. {
  3.     API_MSG_VAR_DECLARE(msg);
  4.     err_t err;
  6.     API_MSG_VAR_ALLOC(msg);
  7.     API_MSG_VAR_REF(msg).conn = conn;
  9.     err = netconn_apimsg(lwip_netconn_do_disconnect,
  10.                          &API_MSG_VAR_REF(msg));
  12.     API_MSG_VAR_FREE(msg);
  14.     return err;
  15. }


netconn_accept()

该函数用于 TCP 服务器中，接受远端主机的连接，内核会在 acceptmbox 邮箱中获取一个连接请求

  1. err_t netconn_accept(struct netconn *conn, struct netconn **new_conn)
  2. {
  3.     #if LWIP_TCP
  4.     err_t err;
  5.     void *accept_ptr;
  6.     struct netconn *newconn;
  8.     err = netconn_err(conn);
  9.     if (err != ERR_OK)
  10.     {
  11.         /* return pending error */
  12.         return err;
  13.     }
  14.     if (!NETCONN_ACCEPTMBOX_WAITABLE(conn))
  15.     {
  16.         /* 如果 acceptmbox 无效 */
  17.         return ERR_CLSD;
  18.     }
  19.     //如果 netconn 是不阻塞的
  20.     if (netconn_is_nonblocking(conn))
  21.     {
  22.         //从 acceptmbox 邮箱获取远端主机的连接请求
  23.         if (sys_arch_mbox_tryfetch(&conn->acceptmbox, &accept_ptr)
  24.             == SYS_ARCH_TIMEOUT)
  25.         {
  26.             //如果超时
  27.             return ERR_WOULDBLOCK;
  28.         }
  29.     }
  30.     else
  31.     {
  32.         //一直等待着远端的连接请求
  33.         sys_arch_mbox_fetch(&conn->acceptmbox, &accept_ptr, 0);
  34.     }
  36.     /* 触发连接事件的回调函数 */
  37.     API_EVENT(conn, NETCONN_EVT_RCVMINUS, 0);
  39.     if (lwip_netconn_is_err_msg(accept_ptr, &err))
  40.     {
  41.         /* 如果连接错误 */
  42.         return err;
  43.     }
  44.     if (accept_ptr == NULL)
  45.     {
  46.         /* 连接已终止 */
  47.         return ERR_CLSD;
  48.     }
  49.     newconn = (struct netconn *)accept_ptr;
  50.     *new_conn = newconn;
  52.     return ERR_OK;
  53. }

netconn_recv() 获取数据包

从 recvmbox 邮箱中获取数据包，如果该邮箱中没有数据包，
那么线程调用这个函数将会进入阻塞状态以等待消息的到来，
如果在等待 TCP 连接上的数据时，远端主机终止连接，将返回一个终止连接的错误代码（ERR_CLSD）