Merge "fastboot: add UDP protocol." (c7f43c6a) · Commits · e / os / android_system_core

fastboot/Android.mk

+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

fastboot/fastboot.cpp

+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
		@@ -243,22 +244,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());
		}
		@@ -335,8 +355,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"

fastboot/fastboot_protocol.txt

+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]

fastboot/udp.cpp

0 → 100644

+391 −0

File added.

Preview size limit exceeded, changes collapsed.

fastboot/udp.h

0 → 100644

+81 −0

Original line number	Diff line number	Diff line
		/*
		* Copyright (C) 2015 The Android Open Source Project
		* All rights reserved.
		*
		* Redistribution and use in source and binary forms, with or without
		* modification, are permitted provided that the following conditions
		* are met:
		* * Redistributions of source code must retain the above copyright
		* notice, this list of conditions and the following disclaimer.
		* * Redistributions in binary form must reproduce the above copyright
		* notice, this list of conditions and the following disclaimer in
		* the documentation and/or other materials provided with the
		* distribution.
		*
		* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
		* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
		* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
		* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
		* COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
		* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
		* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
		* OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
		* AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
		* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
		* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
		* SUCH DAMAGE.
		*/

		#ifndef UDP_H_
		#define UDP_H_

		#include <memory>
		#include <string>

		#include "socket.h"
		#include "transport.h"

		namespace udp {

		constexpr int kDefaultPort = 5554;

		// Returns a newly allocated Transport object connected to \|hostname\|:\|port\|. On failure, \|error\| is
		// filled and nullptr is returned.
		std::unique_ptr<Transport> Connect(const std::string& hostname, int port, std::string* error);

		// Internal namespace for test use only.
		namespace internal {

		constexpr uint16_t kProtocolVersion = 1;

		// This will be negotiated with the device so may end up being smaller.
		constexpr uint16_t kHostMaxPacketSize = 8192;

		// Retransmission constants. Retransmission timeout must be at least 500ms, and the host must
		// attempt to send packets for at least 1 minute once the device has connected. See
		// fastboot_protocol.txt for more information.
		constexpr int kResponseTimeoutMs = 500;
		constexpr int kMaxConnectAttempts = 4;
		constexpr int kMaxTransmissionAttempts = 60 * 1000 / kResponseTimeoutMs;

		enum Id : uint8_t {
		kIdError = 0x00,
		kIdDeviceQuery = 0x01,
		kIdInitialization = 0x02,
		kIdFastboot = 0x03
		};

		enum Flag : uint8_t {
		kFlagNone = 0x00,
		kFlagContinuation = 0x01
		};

		// Creates a UDP Transport object using a given Socket. Used for unit tests to create a Transport
		// object that uses a SocketMock.
		std::unique_ptr<Transport> Connect(std::unique_ptr<Socket> sock, std::string* error);

		} // namespace internal

		} // namespace udp

		#endif // UDP_H_