socket 相关代码注解.

    百万汉字注解 + 百篇博客分析 => 挖透鸿蒙内核源码
    国内:https://weharmony.21cloudbox.com
    国外:https://weharmony.github.io

compat/posix/src/socket.c

@@ -33,18 +33,48 @@
 #include <arpa/inet.h>
 #include <sys/socket.h>
 
+/**
+
+https://www.cnblogs.com/sparkdev/p/8341134.html
+*/
+
 #ifdef LOSCFG_NET_LWIP_SACK
 #include <lwip/sockets.h>
 
 #if !LWIP_COMPAT_SOCKETS
 
 #define CHECK_NULL_PTR(ptr) do { if (ptr == NULL) { set_errno(EFAULT); return -1; } } while (0)
-
+/***************************************************************
+TCP服务器端依次调用socket()、bind()、listen()之后，就会监听指定的socket地址了。
+TCP客户端依次调用socket()、connect()之后就向TCP服务器发送了一个连接请求。
+TCP服务器监听到这个请求之后，就会调用accept()函数取接收请求，这样连接就建立好了。
+之后就可以开始网络I/O操作了，即类同于普通文件的读写I/O操作。
+accept函数
+	第一个参数为服务器的socket描述字，
+	第二个参数为指向struct sockaddr *的指针，用于返回客户端的协议地址，
+	第三个参数为客户端协议地址的长度。
+如果accpet成功，那么其返回值是由内核自动生成的一个全新的描述字，代表与返回客户的TCP连接。
+注意：accept的第一个参数为服务器的socket描述字，是服务器开始调用socket()函数生成的，称为监听socket描述字；
+	  而accept函数返回的是已连接的socket描述字。一个服务器通常通常仅仅只创建一个监听socket描述字，
+	  它在该服务器的生命周期内一直存在。内核为每个由服务器进程接受的客户连接创建了一个已连接socket描述字，
+	  当服务器完成了对某个客户的服务，相应的已连接socket描述字就被关闭。
+***************************************************************/
 int accept(int s, struct sockaddr *addr, socklen_t *addrlen)
 {
     return lwip_accept(s, addr, addrlen);
 }
-
+/***************************************************************
+bind()函数把一个地址族中的特定地址赋给socket。
+例如对应AF_INET、AF_INET6就是把一个ipv4或ipv6地址和端口号组合赋给socket。
+函数的三个参数分别为： 
+	•sockfd：即socket描述字，它是通过socket()函数创建了，唯一标识一个socket。
+		bind()函数就是将给这个描述字绑定一个名字。 
+	•addr：一个const struct sockaddr *指针，指向要绑定给sockfd的协议地址。
+	•addrlen：对应的是地址的长度。 
+通常服务器在启动的时候都会绑定一个众所周知的地址（如ip地址+端口号），用于提供服务，
+客户就可以通过它来接连服务器；而客户端就不用指定，有系统自动分配一个端口号和自身的ip地址组合。
+这就是为什么通常服务器端在listen之前会调用bind()，而客户端就不会调用，而是在connect()时由系统随机生成一个。
+***************************************************************/
 int bind(int s, const struct sockaddr *name, socklen_t namelen)
 {
     CHECK_NULL_PTR(name);
@@ -54,41 +84,68 @@ int bind(int s, const struct sockaddr *name, socklen_t namelen)
     }
     return lwip_bind(s, name, namelen);
 }
+}
+/***************************************************************
+该函数的行为依赖于how的值 
+	SHUT_RD：值为0，关闭连接的读这一半。 
+	SHUT_WR：值为1，关闭连接的写这一半。 
+	SHUT_RDWR：值为2，连接的读和写都关闭。 
+终止网络连接的通用方法是调用close函数。但使用shutdown能更好的控制断连过程（使用第二个参数）。
 
+closesocket 与 shutdown 的区别主要表现在： 
+closesocket 函数会关闭套接字ID，如果有其他的进程共享着这个套接字，那么它仍然是打开的，
+	这个连接仍然可以用来读和写，并且有时候这是非常重要的 ，特别是对于多进程并发服务器来说。 
+而shutdown会切断进程共享的套接字的所有连接，不管这个套接字的引用计数是否为零，
+	那些试图读得进程将会接收到EOF标识，那些试图写的进程将会检测到SIGPIPE信号，
+	同时可利用shutdown的第二个参数选择断连的方式。 
+***************************************************************/
 int shutdown(int s, int how)
 {
     return lwip_shutdown(s, how);
 }
-
+//获取对等名称 = getsockname
 int getpeername(int s, struct sockaddr *name, socklen_t *namelen)
 {
-    CHECK_NULL_PTR(name);
+    CHECK_NULL_PTR(name);//参数判空检查,这种写法有点意思
     CHECK_NULL_PTR(namelen);
     return lwip_getpeername(s, name, namelen);
 }
-
+//获取socket名称和长度
 int getsockname(int s, struct sockaddr *name, socklen_t *namelen)
 {
     CHECK_NULL_PTR(name);
     CHECK_NULL_PTR(namelen);
     return lwip_getsockname(s, name, namelen);
 }
-
+//获取 socket 配置项
 int getsockopt(int s, int level, int optname, void *optval, socklen_t *optlen)
 {
     return lwip_getsockopt(s, level, optname, optval, optlen);
 }
-
+//设置socket 配置项
 int setsockopt(int s, int level, int optname, const void *optval, socklen_t optlen)
 {
     return lwip_setsockopt(s, level, optname, optval, optlen);
 }
-
+/***************************************************************
+closesocket 一个套接字的默认行为是把套接字标记为已关闭，然后立即返回到调用进程，
+该套接字描述符不能再由调用进程使用，也就是说它不能再作为read或write的第一个参数，
+然而TCP将尝试发送已排队等待发送到对端，发送完毕后发生的是正常的TCP连接终止序列。 
+在多进程并发服务器中，父子进程共享着套接字，套接字描述符引用计数记录着共享着的进程个数，
+当父进程或某一子进程close掉套接字时，描述符引用计数会相应的减一，
+当引用计数仍大于零时，这个close调用就不会引发TCP的四路握手断连过程。
+***************************************************************/
 int closesocket(int s)
 {
     return lwip_close(s);
 }
-
+/***************************************************************
+connect函数由客户端使用,发出连接请求，服务器端就会接收到这个请求
+	第一个参数即为客户端的socket描述字，
+	第二参数为服务器的socket地址，
+	第三个参数为socket地址的长度。
+客户端通过调用connect函数来建立与TCP服务器的连接。
+***************************************************************/
 int connect(int s, const struct sockaddr *name, socklen_t namelen)
 {
     CHECK_NULL_PTR(name);
@@ -98,25 +155,43 @@ int connect(int s, const struct sockaddr *name, socklen_t namelen)
     }
     return lwip_connect(s, name, namelen);
 }
-
+/***************************************************************
+如果作为一个服务器，在调用socket()、bind()之后就会调用listen()来监听这个socket，
+如果客户端这时调用connect()发出连接请求，服务器端就会接收到这个请求。
+listen函数的
+	第一个参数即为要监听的socket描述字，
+	第二个参数为相应socket可以排队的最大连接个数。
+	socket()函数创建的socket默认是一个主动类型的，listen函数将socket变为被动类型的，等待客户的连接请求。
+***************************************************************/
 int listen(int s, int backlog)
 {
     return lwip_listen(s, backlog);
 }
+/***************************************************************
+相当于文件操作的 read 功能,区别是第四个参数
 
+MSG_DONTROUTE：不查找表，是send函数使用的标志，这个标志告诉IP，目的主机在本地网络上，
+	没有必要查找表，这个标志一般用在网络诊断和路由程序里面。 
+MSG_OOB：表示可以接收和发送带外数据。 
+MSG_PEEK：查看数据，并不从系统缓冲区移走数据。是recv函数使用的标志，
+	表示只是从系统缓冲区中读取内容，而不清楚系统缓冲区的内容。这样在下次读取的时候，
+	依然是一样的内容，一般在有个进程读写数据的时候使用这个标志。 
+MSG_WAITALL：等待所有数据，是recv函数的使用标志，表示等到所有的信息到达时才返回，
+	使用这个标志的时候，recv返回一直阻塞，直到指定的条件满足时，或者是发生了错误。
+***************************************************************/
 ssize_t recv(int s, void *mem, size_t len, int flags)
 {
     CHECK_NULL_PTR(mem);
     return lwip_recv(s, mem, len, flags);
 }
-
+//区别是返回源地址,意思是这些数据是从哪个地址过来的
 ssize_t recvfrom(int s, void *mem, size_t len, int flags,
                  struct sockaddr *from, socklen_t *fromlen)
 {
     CHECK_NULL_PTR(mem);
     return lwip_recvfrom(s, mem, len, flags, from, fromlen);
 }
-
+//只是数据的格式的不同
 ssize_t recvmsg(int s, struct msghdr *message, int flags)
 {
     CHECK_NULL_PTR(message);
@@ -125,18 +200,20 @@ ssize_t recvmsg(int s, struct msghdr *message, int flags)
     }
     return lwip_recvmsg(s, message, flags);
 }
-
+/***************************************************************
+相当于文件操作的 write 功能,区别是第四个参数 同 recv
+***************************************************************/
 ssize_t send(int s, const void *dataptr, size_t size, int flags)
 {
     CHECK_NULL_PTR(dataptr);
     return  lwip_send(s, dataptr, size, flags);
 }
-
+//只是发送数据的格式的不同
 ssize_t sendmsg(int s, const struct msghdr *message, int flags)
 {
     return lwip_sendmsg(s, message, flags);
 }
-
+//区别是送达地址,意思是这些数据要发给哪个地址的
 ssize_t sendto(int s, const void *dataptr, size_t size, int flags,
                const struct sockaddr *to, socklen_t tolen)
 {
@@ -147,17 +224,48 @@ ssize_t sendto(int s, const void *dataptr, size_t size, int flags,
     }
     return lwip_sendto(s, dataptr, size, flags, to, tolen);
 }
+/***************************************************************
+用于创建一个socket描述符（socket descriptor），它唯一标识一个socket。
+这个socket描述符跟文件描述符一样，后续的操作都有用到它，把它作为参数，通过它来进行一些读写操作。
+正如可以给fopen的传入不同参数值，以打开不同的文件。创建socket的时候，也可以指定不同的参数
+创建不同的socket描述符，socket函数的三个参数分别为： 
 
+•domain：即协议域，又称为协议族（family）。
+	常用的协议族有，
+	AF_INET（IPv4)、
+	AF_INET6(IPv6)、
+	AF_LOCAL（或称AF_UNIX，Unix域socket）、
+	AF_ROUTE等等。
+	协议族决定了socket的地址类型，在通信中必须采用对应的地址，
+	如AF_INET决定了要用ipv4地址（32位的）与端口号（16位的）的组合、
+	AF_UNIX决定了要用一个绝对路径名作为地址。 
+•type：指定socket类型。
+	常用的socket类型有，
+	SOCK_STREAM（流式套接字）、
+	SOCK_DGRAM（数据报式套接字）、
+	SOCK_RAW、SOCK_PACKET、
+	SOCK_SEQPACKET等等 
+•protocol：就是指定协议。
+	常用的协议有，
+	IPPROTO_TCP、PPTOTO_UDP、IPPROTO_SCTP、IPPROTO_TIPC等，
+	它们分别对应TCP传输协议、UDP传输协议、STCP传输协议、TIPC传输协议。
+注意：并不是上面的type和protocol可以随意组合的，如SOCK_STREAM不可以跟IPPROTO_UDP组合。
+当protocol为0时，会自动选择type类型对应的默认协议。	
+***************************************************************/
 int socket(int domain, int type, int protocol)
 {
     return lwip_socket(domain, type, protocol);
 }
-
+/***************************************************************
+inet_ntop 函数转换网络二进制结构到ASCII类型的地址，参数的作用和上面相同，
+只是多了一个参数socklen_t cnt,他是所指向缓存区dst的大小，避免溢出，
+如果缓存区太小无法存储地址的值，则返回一个空指针，并将errno置为ENOSPC
+***************************************************************/
 const char *inet_ntop(int af, const void *src, char *dst, socklen_t size)
 {
     return lwip_inet_ntop(af, src, dst, size);
 }
-
+//inet_pton 函数转换字符串到网络地址，第一个参数af是地址族，转换后存在dst中
 int inet_pton(int af, const char *src, void *dst)
 {
     return lwip_inet_pton(af, src, dst);

kernel/base/ipc/los_sem.c

@@ -178,7 +178,7 @@ LITE_OS_SEC_TEXT_INIT UINT32 OsSemCreate(UINT16 count, UINT16 maxCount, UINT32 *
 ERR_HANDLER:
     OS_RETURN_ERROR_P2(errLine, errNo);
 }
-//对外接口 创建信号 
+//对外接口 创建信号量 
 LITE_OS_SEC_TEXT_INIT UINT32 LOS_SemCreate(UINT16 count, UINT32 *semHandle)
 {
     return OsSemCreate(count, OS_SEM_COUNT_MAX, semHandle);

net/lwip-2.1/porting/include/arch/sys_arch.h

@@ -38,7 +38,7 @@
 #ifdef __cplusplus
 extern "C" {
 #endif
-
+//移值lwip对相关结构体的封装
 
 /**
  * Mutex

net/lwip-2.1/porting/include/lwip/lwipopts.h

@@ -80,11 +80,11 @@
 
 
 // Options only in new opt.h
-#define LWIP_SOCKET_SELECT              0
-#define LWIP_SOCKET_POLL                1
+#define LWIP_SOCKET_SELECT              0	//select 方式
+#define LWIP_SOCKET_POLL                1	//poll方式
 
 
-// Options in old opt.h that differs from new opt.h
+// Options in old opt.h that differs from new opt.h //旧 opt.h 中与新 opt.h 不同的选项
 #define MEM_ALIGNMENT                   __SIZEOF_POINTER__
 #define MEMP_NUM_NETDB                  8
 #define IP_REASS_MAXAGE                 3
@@ -116,7 +116,7 @@
 #define LWIP_IPV6_DHCP6_STATEFUL        1
 
 
-// Options in old lwipopts.h
+// Options in old lwipopts.h //旧 opt.h 中的选项
 #define ARP_QUEUEING                    1
 #define DEFAULT_ACCEPTMBOX_SIZE         32
 #define DEFAULT_RAW_RECVMBOX_SIZE       128
@@ -159,12 +159,12 @@
 #define PBUF_POOL_BUFSIZE               1550
 #define PBUF_POOL_SIZE                  64
 #define SO_REUSE                        1
-#define TCPIP_MBOX_SIZE                 512
-#define TCPIP_THREAD_PRIO               5
-#define TCPIP_THREAD_STACKSIZE          0x6000
+#define TCPIP_MBOX_SIZE                 512		//队列长度
+#define TCPIP_THREAD_PRIO               5		//lwip相关线程优先级 5 ,和资源回收任务优先级一样
+#define TCPIP_THREAD_STACKSIZE          0x6000	//线程内核栈大小 24K
 #define TCP_MAXRTX                      64
 #define TCP_MSS                         1400
-#define TCP_SND_BUF                     65535
+#define TCP_SND_BUF                     65535	//发送buf大小 64K
 #define TCP_SND_QUEUELEN                (8 * TCP_SND_BUF) / TCP_MSS
 #define TCP_TTL                         255
 #define TCP_WND                         32768
@@ -217,8 +217,8 @@
 
 // Options for enhancement code, same for old lwipopts.h
 #define LWIP_NETIF_PROMISC              1
-#define LWIP_DHCPS                      1
-#define LWIP_ENABLE_NET_CAPABILITY      1
-#define LWIP_ENABLE_CAP_NET_BROADCAST   0
+#define LWIP_DHCPS                      1	
+#define LWIP_ENABLE_NET_CAPABILITY      1	//网络开关
+#define LWIP_ENABLE_CAP_NET_BROADCAST   0	//广播开关
 
 #endif /* _LWIP_PORTING_LWIPOPTS_H_ */

net/lwip-2.1/porting/include/lwip/netif.h

@@ -64,8 +64,8 @@ extern "C" {
 #define NETIF_NAMESIZE IFNAMSIZ
 
 #define LOOPBACK_IF         0 // 772
-#define ETHERNET_DRIVER_IF  1
-#define WIFI_DRIVER_IF      801
+#define ETHERNET_DRIVER_IF  1	//以太网驱动接口
+#define WIFI_DRIVER_IF      801	//WIFI驱动接口
 
 err_t driverif_init(struct netif *netif);
 void driverif_input(struct netif *netif, struct pbuf *p);

net/lwip-2.1/porting/src/driverif.c

@@ -240,7 +240,7 @@ driverif_input(struct netif *netif, struct pbuf *p)
  *         any other err_t on error
  */
 err_t
-driverif_init(struct netif *netif)
+driverif_init(struct netif *netif)//网络接口驱动层初始化
 {
     u16_t link_layer_type;
 
@@ -263,7 +263,7 @@ driverif_init(struct netif *netif)
 
 #if LWIP_NETIF_HOSTNAME
     /* Initialize interface hostname */
-    netif->hostname = LWIP_NETIF_HOSTNAME_DEFAULT;
+    netif->hostname = LWIP_NETIF_HOSTNAME_DEFAULT;//初始化主机名
 #endif /* LWIP_NETIF_HOSTNAME */
 
     /*

net/lwip-2.1/porting/src/sockets.c

@@ -32,6 +32,7 @@
 #include <lwip/sockets.h>
 #include <lwip/priv/tcpip_priv.h>
 #include <lwip/fixme.h>
+//https://blog.csdn.net/zhaozhiyuan111/article/details/79197692
 
 #if LWIP_ENABLE_NET_CAPABILITY
 #include "capability_type.h"
@@ -136,15 +137,15 @@ static int lwip_socket_wrap(int domain, int type, int protocol)
 #endif
     return lwip_socket2(domain, type, protocol);
 }
-
+//设置选项
 static int lwip_setsockopt_wrap(int s, int level, int optname, const void *optval, socklen_t optlen)
 {
 #if LWIP_ENABLE_NET_CAPABILITY
     if (level == SOL_SOCKET) {
         switch (optname) {
 #if LWIP_ENABLE_CAP_NET_BROADCAST
-            case SO_BROADCAST:
-                if (!IsCapPermit(CAP_NET_BROADCAST)) {
+            case SO_BROADCAST:	//广播消息
+                if (!IsCapPermit(CAP_NET_BROADCAST)) {//鉴权,是否广播权限
                     set_errno(EPERM);
                     return -1;
                 }

net/lwip-2.1/porting/src/sys_arch.c

@@ -40,6 +40,8 @@
 #include <los_mux.h>
 #include <los_spinlock.h>
 
+//移值lwip 需实现的外部接口.
+
 #if (LOSCFG_KERNEL_SMP == YES)
 SPIN_LOCK_INIT(arch_protect_spin);
 static u32_t lwprot_thread = LOS_ERRNO_TSK_ID_INVALID;
@@ -51,7 +53,7 @@ static int lwprot_count = 0;
 /**
  * Thread and System misc
  */
-
+//在liteos上实现移值lwip的所需的创建线程接口
 sys_thread_t sys_thread_new(const char *name, lwip_thread_fn thread, void *arg, int stackSize, int prio)
 {
     UINT32 taskID = LOS_ERRNO_TSK_ID_INVALID;
@@ -60,8 +62,8 @@ sys_thread_t sys_thread_new(const char *name, lwip_thread_fn thread, void *arg,
 
     /* Create host Task */
     task.pfnTaskEntry = (TSK_ENTRY_FUNC)thread;
-    task.uwStackSize = stackSize;
-    task.pcName = (char *)name;
+    task.uwStackSize = stackSize;//内核栈大小
+    task.pcName = (char *)name;//任务名称
     task.usTaskPrio = prio;
     task.auwArgs[0] = (UINTPTR)arg;
     task.uwResved = LOS_TASK_STATUS_DETACHED;
@@ -145,11 +147,11 @@ void sys_arch_unprotect(sys_prot_t pval)
 /**
  * MessageBox
  */
-
+//创建消息盒子队列
 err_t sys_mbox_new(sys_mbox_t *mbox, int size)
 {
     CHAR qName[] = "lwIP";
-    UINT32 ret = LOS_QueueCreate(qName, (UINT16)size, mbox, 0, sizeof(void *));
+    UINT32 ret = LOS_QueueCreate(qName, (UINT16)size, mbox, 0, sizeof(void *));//创建一个队列 "lwip"
     switch (ret) {
         case LOS_OK:
             return ERR_OK;
@@ -162,7 +164,7 @@ err_t sys_mbox_new(sys_mbox_t *mbox, int size)
     LWIP_DEBUGF(SYS_DEBUG, ("%s: LOS_QueueCreate error %u\n", __FUNCTION__, ret));
     return ERR_ARG;
 }
-
+//发送消息,参数2不能为空,直到发送成功为止
 void sys_mbox_post(sys_mbox_t *mbox, void *msg)
 {
     /* Caution: the second parameter is NOT &msg */
@@ -171,7 +173,7 @@ void sys_mbox_post(sys_mbox_t *mbox, void *msg)
         LWIP_DEBUGF(SYS_DEBUG, ("%s: LOS_QueueWrite error %u\n", __FUNCTION__, ret));
     }
 }
-
+//尝试发送消息
 err_t sys_mbox_trypost(sys_mbox_t *mbox, void *msg)
 {
     /* Caution: the second parameter is NOT &msg */
@@ -189,7 +191,7 @@ err_t sys_mbox_trypost(sys_mbox_t *mbox, void *msg)
 }
 
 err_t sys_mbox_trypost_fromisr(sys_mbox_t *mbox, void *msg);
-
+//读消息
 u32_t sys_arch_mbox_fetch(sys_mbox_t *mbox, void **msg, u32_t timeoutMs)
 {
     void *ignore = 0; /* if msg==NULL, the fetched msg should be dropped */
@@ -207,7 +209,7 @@ u32_t sys_arch_mbox_fetch(sys_mbox_t *mbox, void **msg, u32_t timeoutMs)
     LWIP_DEBUGF(SYS_DEBUG, ("%s: LOS_QueueRead error %u\n", __FUNCTION__, ret));
     return SYS_ARCH_TIMEOUT; /* Errors should be treated as timeout */
 }
-
+//尝试都消息
 u32_t sys_arch_mbox_tryfetch(sys_mbox_t *mbox, void **msg)
 {
     void *ignore = 0; /* if msg==NULL, the fetched msg should be dropped */
@@ -225,12 +227,12 @@ u32_t sys_arch_mbox_tryfetch(sys_mbox_t *mbox, void **msg)
     LWIP_DEBUGF(SYS_DEBUG, ("%s: LOS_QueueRead error %u\n", __FUNCTION__, ret));
     return SYS_MBOX_EMPTY; /* Errors should be treated as timeout */
 }
-
+//删除队列
 void sys_mbox_free(sys_mbox_t *mbox)
 {
     (void)LOS_QueueDelete(*mbox);
 }
-
+//队列是否有效
 int sys_mbox_valid(sys_mbox_t *mbox)
 {
     QUEUE_INFO_S queueInfo;
@@ -246,7 +248,7 @@ void sys_mbox_set_invalid(sys_mbox_t *mbox)
 /**
  * Semaphore
  */
-
+//创建信号量
 err_t sys_sem_new(sys_sem_t *sem, u8_t count)
 {
     UINT32 ret = LOS_SemCreate(count, sem);

net/mac/los_mac.h

@@ -40,15 +40,15 @@ extern "C" {
 #endif /* __cplusplus */
 #endif /* __cplusplus */
 
-struct los_eth_driver {
-    void* driver_context;
-    struct netif ac_if;
+struct los_eth_driver {//以太网驱动
+    void* driver_context;//驱动上下文
+    struct netif ac_if;	
 };
 
-struct los_eth_funs {
-    void (*init)(struct los_eth_driver *drv, unsigned char *mac_addr);
-    void (*recv)(struct los_eth_driver *drv, int len);
-    void (*send_complete)(struct los_eth_driver *drv, unsigned int key, int state);
+struct los_eth_funs {//以太网功能接口
+    void (*init)(struct los_eth_driver *drv, unsigned char *mac_addr);//初始化
+    void (*recv)(struct los_eth_driver *drv, int len);//接收数据
+    void (*send_complete)(struct los_eth_driver *drv, unsigned int key, int state);//发送数据
 };
 
 #ifdef __cplusplus

zzz/git/push.sh

 git add -A
-git commit -m  '进程权限注解. 
+git commit -m  'socket 相关代码注解. 
     百万汉字注解 + 百篇博客分析 => 挖透鸿蒙内核源码
     国内:https://weharmony.21cloudbox.com
     国外:https://weharmony.github.io