Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 7bbb4a0c authored by David Pursell's avatar David Pursell Committed by Android (Google) Code Review
Browse files

Merge changes Ib17f0a55,Ia5bbae6b,I339d42fc into nyc-dev

* changes:
  fastboot: fix TCP protocol version check.
  fastboot: add UDP protocol.
  fastboot: add Socket timeout detection.
parents 14ae3f2b 022d8f58
Loading
Loading
Loading
Loading
+3 −0
Original line number Diff line number Diff line
@@ -32,6 +32,7 @@ LOCAL_SRC_FILES := \
    protocol.cpp \
    socket.cpp \
    tcp.cpp \
    udp.cpp \
    util.cpp \

LOCAL_MODULE := fastboot
@@ -114,6 +115,8 @@ LOCAL_SRC_FILES := \
    socket_test.cpp \
    tcp.cpp \
    tcp_test.cpp \
    udp.cpp \
    udp_test.cpp \

LOCAL_STATIC_LIBRARIES := libbase libcutils

+32 −11
Original line number Diff line number Diff line
@@ -59,6 +59,7 @@
#include "fs.h"
#include "tcp.h"
#include "transport.h"
#include "udp.h"
#include "usb.h"

#ifndef O_BINARY
@@ -245,22 +246,41 @@ static Transport* open_device() {
        return transport;
    }

    Socket::Protocol protocol = Socket::Protocol::kTcp;
    std::string host;
    int port = tcp::kDefaultPort;
    if (serial != nullptr && android::base::StartsWith(serial, "tcp:")) {
        std::string error;
        const char* address = serial + strlen("tcp:");
    int port = 0;
    if (serial != nullptr) {
        const char* net_address = nullptr;

        if (android::base::StartsWith(serial, "tcp:")) {
            protocol = Socket::Protocol::kTcp;
            port = tcp::kDefaultPort;
            net_address = serial + strlen("tcp:");
        } else if (android::base::StartsWith(serial, "udp:")) {
            protocol = Socket::Protocol::kUdp;
            port = udp::kDefaultPort;
            net_address = serial + strlen("udp:");
        }

        if (!android::base::ParseNetAddress(address, &host, &port, nullptr, &error)) {
            fprintf(stderr, "error: Invalid network address '%s': %s\n", address, error.c_str());
        if (net_address != nullptr) {
            std::string error;
            if (!android::base::ParseNetAddress(net_address, &host, &port, nullptr, &error)) {
                fprintf(stderr, "error: Invalid network address '%s': %s\n", net_address,
                        error.c_str());
                return nullptr;
            }
        }
    }

    while (true) {
        if (!host.empty()) {
            std::string error;
            if (protocol == Socket::Protocol::kTcp) {
                transport = tcp::Connect(host, port, &error).release();
            } else if (protocol == Socket::Protocol::kUdp) {
                transport = udp::Connect(host, port, &error).release();
            }

            if (transport == nullptr && announce) {
                fprintf(stderr, "error: %s\n", error.c_str());
            }
@@ -337,8 +357,9 @@ static void usage() {
            "                                           formatting.\n"
            "  -s <specific device>                     Specify a device. For USB, provide either\n"
            "                                           a serial number or path to device port.\n"
            "                                           For TCP, provide an address in the form\n"
            "                                           tcp:<hostname>[:port].\n"
            "                                           For ethernet, provide an address in the"
            "                                           form <protocol>:<hostname>[:port] where"
            "                                           <protocol> is either tcp or udp.\n"
            "  -p <product>                             Specify product name.\n"
            "  -c <cmdline>                             Override kernel commandline.\n"
            "  -i <vendor id>                           Specify a custom USB vendor id.\n"
+225 −2
Original line number Diff line number Diff line
@@ -17,9 +17,9 @@ Basic Requirements
  * The protocol is entirely host-driven and synchronous (unlike the
    multi-channel, bi-directional, asynchronous ADB protocol)

* TCP
* TCP or UDP
  * Device must be reachable via IP.
  * Device will act as the TCP server, fastboot will be the client.
  * Device will act as the server, fastboot will be the client.
  * Fastboot data is wrapped in a simple protocol; see below for details.


@@ -217,3 +217,226 @@ Device [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x07]OKAY0.4
Host    [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0B]getvar:none
Device  [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x04]OKAY
Host    <disconnect>


UDP Protocol v1
---------------

The UDP protocol is more complex than TCP since we must implement reliability
to ensure no packets are lost, but the general concept of wrapping the fastboot
protocol is the same.

Overview:
  1. As with TCP, the device will listen on UDP port 5554.
  2. Maximum UDP packet size is negotiated during initialization.
  3. The host drives all communication; the device may only send a packet as a
     response to a host packet.
  4. If the host does not receive a response in 500ms it will re-transmit.

-- UDP Packet format --
  +----------+----+-------+-------+--------------------+
  | Byte #   | 0  |   1   | 2 - 3 |  4+                |
  +----------+----+-------+-------+--------------------+
  | Contents | ID | Flags | Seq # | Data               |
  +----------+----+-------+-------+--------------------+

  ID      Packet ID:
            0x00: Error.
            0x01: Query.
            0x02: Initialization.
            0x03: Fastboot.

          Packet types are described in more detail below.

  Flags   Packet flags: 0 0 0 0 0 0 0 C
            C=1 indicates a continuation packet; the data is too large and will
                continue in the next packet.

            Remaining bits are reserved for future use and must be set to 0.

  Seq #   2-byte packet sequence number (big-endian). The host will increment
          this by 1 with each new packet, and the device must provide the
          corresponding sequence number in the response packets.

  Data    Packet data, not present in all packets.

-- Packet Types --
Query     The host sends a query packet once on startup to sync with the device.
          The host will not know the current sequence number, so the device must
          respond to all query packets regardless of sequence number.

          The response data field should contain a 2-byte big-endian value
          giving the next expected sequence number.

Init      The host sends an init packet once the query response is returned. The
          device must abort any in-progress operation and prepare for a new
          fastboot session. This message is meant to allow recovery if a
          previous session failed, e.g. due to network error or user Ctrl+C.

          The data field contains two big-endian 2-byte values, a protocol
          version and the max UDP packet size (including the 4-byte header).
          Both the host and device will send these values, and in each case
          the minimum of the sent values must be used.

Fastboot  These packets wrap the fastboot protocol. To write, the host will
          send a packet with fastboot data, and the device will reply with an
          empty packet as an ACK. To read, the host will send an empty packet,
          and the device will reply with fastboot data. The device may not give
          any data in the ACK packet.

Error     The device may respond to any packet with an error packet to indicate
          a UDP protocol error. The data field should contain an ASCII string
          describing the error. This is the only case where a device is allowed
          to return a packet ID other than the one sent by the host.

-- Packet Size --
The maximum packet size is negotiated by the host and device in the Init packet.
Devices must support at least 512-byte packets, but packet size has a direct
correlation with download speed, so devices are strongly suggested to support at
least 1024-byte packets. On a local network with 0.5ms round-trip time this will
provide transfer rates of ~2MB/s. Over WiFi it will likely be significantly
less.

Query and Initialization packets, which are sent before size negotiation is
complete, must always be 512 bytes or less.

-- Packet Re-Transmission --
The host will re-transmit any packet that does not receive a response. The
requirement of exactly one device response packet per host packet is how we
achieve reliability and in-order delivery of packets.

For simplicity of implementation, there is no windowing of multiple
unacknowledged packets in this version of the protocol. The host will continue
to send the same packet until a response is received. Windowing functionality
may be implemented in future versions if necessary to increase performance.

The first Query packet will only be attempted a small number of times, but
subsequent packets will attempt to retransmit for at least 1 minute before
giving up. This means a device may safely ignore host UDP packets for up to 1
minute during long operations, e.g. writing to flash.

-- Continuation Packets --
Any packet may set the continuation flag to indicate that the data is
incomplete. Large data such as downloading an image may require many
continuation packets. The receiver should respond to a continuation packet with
an empty packet to acknowledge receipt. See examples below.

-- Summary --
The host starts with a Query packet, then an Initialization packet, after
which only Fastboot packets are sent. Fastboot packets may contain data from
the host for writes, or from the device for reads, but not both.

Given a next expected sequence number S and a received packet P, the device
behavior should be:
  if P is a Query packet:
    * respond with a Query packet with S in the data field
  else if P has sequence == S:
    * process P and take any required action
    * create a response packet R with the same ID and sequence as P, containing
      any response data required.
    * transmit R and save it in case of re-transmission
    * increment S
  else if P has sequence == S - 1:
    * re-transmit the saved response packet R from above
  else:
    * ignore the packet

-- Examples --
In the examples below, S indicates the starting client sequence number.

Host                                    Client
======================================================================
[Initialization, S = 0x55AA]
[Host: version 1, 2048-byte packets. Client: version 2, 1024-byte packets.]
[Resulting values to use: version = 1, max packet size = 1024]
ID   Flag SeqH SeqL Data                ID   Flag SeqH SeqL Data
----------------------------------------------------------------------
0x01 0x00 0x00 0x00
                                        0x01 0x00 0x00 0x00 0x55 0xAA
0x02 0x00 0x55 0xAA 0x00 0x01 0x08 0x00
                                        0x02 0x00 0x55 0xAA 0x00 0x02 0x04 0x00

----------------------------------------------------------------------
[fastboot "getvar" commands, S = 0x0001]
ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
----------------------------------------------------------------------
0x03  0x00  0x00  0x01  getvar:version
                                        0x03  0x00  0x00  0x01
0x03  0x00  0x00  0x02
                                        0x03  0x00  0x00  0x02  OKAY0.4
0x03  0x00  0x00  0x03  getvar:foo
                                        0x03  0x00  0x00  0x03
0x03  0x00  0x00  0x04
                                        0x03  0x00  0x00  0x04  OKAY

----------------------------------------------------------------------
[fastboot "INFO" responses, S = 0x0000]
ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
----------------------------------------------------------------------
0x03  0x00  0x00  0x00  <command>
                                        0x03  0x00  0x00  0x00
0x03  0x00  0x00  0x01
                                        0x03  0x00  0x00  0x01  INFOWait1
0x03  0x00  0x00  0x02
                                        0x03  0x00  0x00  0x02  INFOWait2
0x03  0x00  0x00  0x03
                                        0x03  0x00  0x00  0x03  OKAY

----------------------------------------------------------------------
[Chunking 2100 bytes of data, max packet size = 1024, S = 0xFFFF]
ID   Flag SeqH SeqL Data                ID   Flag SeqH SeqL Data
----------------------------------------------------------------------
0x03 0x00 0xFF 0xFF download:0000834
                                        0x03 0x00 0xFF 0xFF
0x03 0x00 0x00 0x00
                                        0x03 0x00 0x00 0x00 DATA0000834
0x03 0x01 0x00 0x01 <1020 bytes>
                                        0x03 0x00 0x00 0x01
0x03 0x01 0x00 0x02 <1020 bytes>
                                        0x03 0x00 0x00 0x02
0x03 0x00 0x00 0x03 <60 bytes>
                                        0x03 0x00 0x00 0x03
0x03 0x00 0x00 0x04
                                        0x03 0x00 0x00 0x04 OKAY

----------------------------------------------------------------------
[Unknown ID error, S = 0x0000]
ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
----------------------------------------------------------------------
0x10  0x00  0x00  0x00
                                        0x00  0x00  0x00  0x00  <error message>

----------------------------------------------------------------------
[Host packet loss and retransmission, S = 0x0000]
ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
----------------------------------------------------------------------
0x03  0x00  0x00  0x00  getvar:version [lost]
0x03  0x00  0x00  0x00  getvar:version [lost]
0x03  0x00  0x00  0x00  getvar:version
                                        0x03  0x00  0x00  0x00
0x03  0x00  0x00  0x01
                                        0x03  0x00  0x00  0x01  OKAY0.4

----------------------------------------------------------------------
[Client packet loss and retransmission, S = 0x0000]
ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
----------------------------------------------------------------------
0x03  0x00  0x00  0x00  getvar:version
                                        0x03  0x00  0x00  0x00 [lost]
0x03  0x00  0x00  0x00  getvar:version
                                        0x03  0x00  0x00  0x00 [lost]
0x03  0x00  0x00  0x00  getvar:version
                                        0x03  0x00  0x00  0x00
0x03  0x00  0x00  0x01
                                        0x03  0x00  0x00  0x01  OKAY0.4

----------------------------------------------------------------------
[Host packet delayed, S = 0x0000]
ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
----------------------------------------------------------------------
0x03  0x00  0x00  0x00  getvar:version [delayed]
0x03  0x00  0x00  0x00  getvar:version
                                        0x03  0x00  0x00  0x00
0x03  0x00  0x00  0x01
                                        0x03  0x00  0x00  0x01  OKAY0.4
0x03  0x00  0x00  0x00  getvar:version [arrives late with old seq#, is ignored]
+36 −14
Original line number Diff line number Diff line
@@ -48,18 +48,6 @@ int Socket::Close() {
    return ret;
}

bool Socket::SetReceiveTimeout(int timeout_ms) {
    if (timeout_ms != receive_timeout_ms_) {
        if (socket_set_receive_timeout(sock_, timeout_ms) == 0) {
            receive_timeout_ms_ = timeout_ms;
            return true;
        }
        return false;
    }

    return true;
}

ssize_t Socket::ReceiveAll(void* data, size_t length, int timeout_ms) {
    size_t total = 0;

@@ -82,6 +70,40 @@ int Socket::GetLocalPort() {
    return socket_get_local_port(sock_);
}

// According to Windows setsockopt() documentation, if a Windows socket times out during send() or
// recv() the state is indeterminate and should not be used. Our UDP protocol relies on being able
// to re-send after a timeout, so we must use select() rather than SO_RCVTIMEO.
// See https://msdn.microsoft.com/en-us/library/windows/desktop/ms740476(v=vs.85).aspx.
bool Socket::WaitForRecv(int timeout_ms) {
    receive_timed_out_ = false;

    // In our usage |timeout_ms| <= 0 means block forever, so just return true immediately and let
    // the subsequent recv() do the blocking.
    if (timeout_ms <= 0) {
        return true;
    }

    // select() doesn't always check this case and will block for |timeout_ms| if we let it.
    if (sock_ == INVALID_SOCKET) {
        return false;
    }

    fd_set read_set;
    FD_ZERO(&read_set);
    FD_SET(sock_, &read_set);

    timeval timeout;
    timeout.tv_sec = timeout_ms / 1000;
    timeout.tv_usec = (timeout_ms % 1000) * 1000;

    int result = TEMP_FAILURE_RETRY(select(sock_ + 1, &read_set, nullptr, nullptr, &timeout));

    if (result == 0) {
        receive_timed_out_ = true;
    }
    return result == 1;
}

// Implements the Socket interface for UDP.
class UdpSocket : public Socket {
  public:
@@ -127,7 +149,7 @@ bool UdpSocket::Send(std::vector<cutils_socket_buffer_t> buffers) {
}

ssize_t UdpSocket::Receive(void* data, size_t length, int timeout_ms) {
    if (!SetReceiveTimeout(timeout_ms)) {
    if (!WaitForRecv(timeout_ms)) {
        return -1;
    }

@@ -206,7 +228,7 @@ bool TcpSocket::Send(std::vector<cutils_socket_buffer_t> buffers) {
}

ssize_t TcpSocket::Receive(void* data, size_t length, int timeout_ms) {
    if (!SetReceiveTimeout(timeout_ms)) {
    if (!WaitForRecv(timeout_ms)) {
        return -1;
    }

+11 −6
Original line number Diff line number Diff line
@@ -81,13 +81,17 @@ class Socket {
    virtual bool Send(std::vector<cutils_socket_buffer_t> buffers) = 0;

    // Waits up to |timeout_ms| to receive up to |length| bytes of data. |timout_ms| of 0 will
    // block forever. Returns the number of bytes received or -1 on error/timeout. On timeout
    // errno will be set to EAGAIN or EWOULDBLOCK.
    // block forever. Returns the number of bytes received or -1 on error/timeout; see
    // ReceiveTimedOut() to distinguish between the two.
    virtual ssize_t Receive(void* data, size_t length, int timeout_ms) = 0;

    // Calls Receive() until exactly |length| bytes have been received or an error occurs.
    virtual ssize_t ReceiveAll(void* data, size_t length, int timeout_ms);

    // Returns true if the last Receive() call timed out normally and can be retried; fatal errors
    // or successful reads will return false.
    bool ReceiveTimedOut() { return receive_timed_out_; }

    // Closes the socket. Returns 0 on success, -1 on error.
    virtual int Close();

@@ -102,10 +106,13 @@ class Socket {
    // Protected constructor to force factory function use.
    Socket(cutils_socket_t sock);

    // Update the socket receive timeout if necessary.
    bool SetReceiveTimeout(int timeout_ms);
    // Blocks up to |timeout_ms| until a read is possible on |sock_|, and sets |receive_timed_out_|
    // as appropriate to help distinguish between normal timeouts and fatal errors. Returns true if
    // a subsequent recv() on |sock_| will complete without blocking or if |timeout_ms| <= 0.
    bool WaitForRecv(int timeout_ms);

    cutils_socket_t sock_ = INVALID_SOCKET;
    bool receive_timed_out_ = false;

    // Non-class functions we want to override during tests to verify functionality. Implementation
    // should call this rather than using socket_send_buffers() directly.
@@ -113,8 +120,6 @@ class Socket {
            socket_send_buffers_function_ = &socket_send_buffers;

  private:
    int receive_timeout_ms_ = 0;

    FRIEND_TEST(SocketTest, TestTcpSendBuffers);
    FRIEND_TEST(SocketTest, TestUdpSendBuffers);

Loading