tinygo.org/x/drivers@v0.27.1-0.20240509133757-7dbca2a54349/netdev/README.md (about)

     1  ### Table of Contents
     2  
     3  - [Netdever](#netdever)
     4  - [Netdev Driver](#netdev-driver)
     5  - [Netdev Driver Notes](#netdev-driver-notes)
     6  
     7  ## Netdever
     8  
     9  TinyGo's network device driver model comprises two Go interfaces: Netdever and
    10  Netlinker.  This README covers Netdever.
    11  
    12  The Netdever interface describes an L4/L3 network interface modeled after the
    13  BSD sockets.  A netdev is a concrete implementation of a Netdever.  See
    14  [Netlinker](../netlink/) for the L2 network interface.
    15  
    16  A netdev can:
    17  
    18  - Send and receive L4/L3 packets
    19  - Resolve DNS lookups
    20  - Get/set the device's IP address
    21  
    22  TinyGo network drivers implement the Netdever interface, providing a BSD
    23  sockets interface to TinyGo's "net" package.  net.Conn implementations
    24  (TCPConn, UDPConn, and TLSConn) use the netdev socket.  For example,
    25  net.DialTCP, which returns a net.TCPConn, calls netdev.Socket() and
    26  netdev.Connect():
    27  
    28  ```go
    29  func DialTCP(network string, laddr, raddr *TCPAddr) (*TCPConn, error) {
    30  
    31          fd, _ := netdev.Socket(netdev.AF_INET, netdev.SOCK_STREAM, netdev.IPPROTO_TCP)
    32  
    33          netdev.Connect(fd, "", raddr.IP, raddr.Port)
    34  
    35          return &TCPConn{
    36                  fd:    fd,
    37                  laddr: laddr,
    38                  raddr: raddr,
    39          }, nil
    40  }
    41  ```
    42  
    43  ## Setting Netdev
    44  
    45  Before the app can use TinyGo's "net" package, the app must set the netdev
    46  using UseNetdev().  This binds the "net" package to the netdev driver.  For
    47  example, setting the wifinina driver as the netdev:
    48  
    49  ```
    50  	nina := wifinina.New(&cfg)
    51  	netdev.UseNetdev(nina)
    52  ```
    53  
    54  ## Netdev Driver Notes
    55  
    56  See the wifinina and rtl8720dn for examples of netdev drivers.  Here are some
    57  notes for netdev drivers.
    58  
    59  #### Locking
    60  
    61  Multiple goroutines may invoke methods on a net.Conn simultaneously, and since
    62  the net package translates net.Conn calls into netdev socket calls, it follows
    63  that multiple goroutines may invoke socket calls, so locking is required to
    64  keep socket calls from stepping on one another.
    65  
    66  Don't hold a lock while Time.Sleep()ing waiting for a long hardware operation to
    67  finish.  Unlocking while sleeping let's other goroutines make progress.
    68  
    69  #### Sockfd
    70  
    71  The netdev BSD socket interface uses a socket fd (int) to represent a socket
    72  connection (end-point).  Each fd maps 1:1 to a net.Conn maps.  The number of fds
    73  available is a hardware limitation.  Wifinina, for example, can hand out 10
    74  fds, representing 10 active sockets.
    75  
    76  #### Testing
    77  
    78  The netdev driver should minimally run all of the example/net examples.