Skip to content

Commit

Permalink
Add network device driver model, netdev
Browse files Browse the repository at this point in the history
This PR adds a network device driver model called netdev. There will be a companion PR for TinyGo drivers to update the netdev drivers and network examples. This PR covers the core "net" package.

An RFC for the work is here: #tinygo-org/drivers#487. Some things have changed from the RFC, but nothing major.

The "net" package is a partial port of Go's "net" package, version 1.19.3. The src/net/README file has details on what is modified from Go's "net" package.

Most "net" features are working as they would in normal Go. TCP/UDP/TLS protocol support is there. As well as HTTP client and server support. Standard Go network packages such as golang.org/x/net/websockets and Paho MQTT client work as-is. Other packages are likely to work as-is.

Testing results are here (https://docs.google.com/spreadsheets/d/e/2PACX-1vT0cCjBvwXf9HJf6aJV2Sw198F2ief02gmbMV0sQocKT4y4RpfKv3dh6Jyew8lQW64FouZ8GwA2yjxI/pubhtml?gid=1013173032&single=true).
  • Loading branch information
scottfeldman committed Mar 31, 2023
1 parent ca06718 commit 8e2a433
Show file tree
Hide file tree
Showing 39 changed files with 11,270 additions and 1,091 deletions.
107 changes: 107 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
This is a port of Go's "net" package. The port offers a subset of Go's "net"
package. The subset maintains Go 1 compatiblity guarantee.

The "net" package is modified to use netdev, TinyGo's network device driver interface.
Netdev replaces the OS syscall interface for I/O access to the networking
device.

#### Table of Contents

- ["net" Package](#net-package)
- [Netdev and Netlink](#netdev-and-netlink)
- [Using "net" and "net/http" Packages](#using-net-and-nethttp-packages)

## "net" Package

The "net" package is ported from Go 1.19.3. The tree listings below shows the
files copied. If the file is marked with an '\*', it is copied _and_ modified
to work with netdev. If the file is marked with an '+', the file is new. If
there is no mark, it is a straight copy.

```
src/net
├── dial.go *
├── http
│   ├── client.go *
│   ├── clone.go
│   ├── cookie.go
│   ├── fs.go
│   ├── header.go *
│   ├── http.go
│   ├── internal
│   │   ├── ascii
│   │   │   ├── print.go
│   │   │   └── print_test.go
│   │   ├── chunked.go
│   │   └── chunked_test.go
│   ├── jar.go
│   ├── method.go
│   ├── request.go *
│   ├── response.go *
│   ├── server.go *
│   ├── sniff.go
│   ├── status.go
│   ├── transfer.go *
│   └── transport.go *
├── ip.go
├── iprawsock.go *
├── ipsock.go *
├── mac.go
├── mac_test.go
├── netdev.go +
├── net.go *
├── parse.go
├── pipe.go
├── README.md
├── tcpsock.go *
├── tlssock.go +
└── udpsock.go *
src/crypto/tls/
├── common.go *
└── tls.go *
```

The modifications to "net" are to basically wrap TCPConn, UDPConn, and TLSConn
around netdev socket calls. In Go, these net.Conns call out to OS syscalls for
the socket operations. In TinyGo, the OS syscalls aren't available, so netdev
socket calls are substituted.

The modifications to "net/http" are on the client and the server side. On the
client side, the TinyGo code changes remove the back-end round-tripper code and
replaces it with direct calls to TCPConns/TLSConns. All of Go's http
request/response handling code is intact and operational in TinyGo. Same holds
true for the server side. The server side supports the normal server features
like ServeMux and Hijacker (for websockets).

### Maintaining "net"

As Go progresses, changes to the "net" package need to be periodically
back-ported to TinyGo's "net" package. This is to pick up any upstream bug
fixes or security fixes.

Changes "net" package files are marked with // TINYGO comments.

The files that are marked modified * may contain only a subset of the original
file. Basically only the parts necessary to compile and run the example/net
examples are copied (and maybe modified).

## Netdev and Netlink

Netdev is TinyGo's network device driver model. Network drivers implement the
netdever interface, providing a common network I/O interface to TinyGo's "net"
package. The interface is modeled after the BSD socket interface. net.Conn
implementations (TCPConn, UDPConn, and TLSConn) use the netdev interface for
device I/O access.

Network drivers also (optionally) implement the Netlinker interface. This
interface is not used by TinyGo's "net" package, but rather provides the TinyGo
application direct access to the network device for common settings and control
that fall outside of netdev's socket interface.

See the README-net.md in drivers repo for more details on netdev and netlink.

## Using "net" and "net/http" Packages

See README-net.md in drivers repo to more details on using "net" and "net/http"
packages in a TinyGo application.
Loading

0 comments on commit 8e2a433

Please sign in to comment.