auto import from //depot/cupcake/@135843

#

# Copyright (C) 2008 The Android Open Source Project

#

# Licensed under the Apache License, Version 2.0 (the "License");

# you may not use this file except in compliance with the License.

# You may obtain a copy of the License at

#

#      http://www.apache.org/licenses/LICENSE-2.0

#

# Unless required by applicable law or agreed to in writing, software

# distributed under the License is distributed on an "AS IS" BASIS,

# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

# See the License for the specific language governing permissions and

# limitations under the License.

#

LOCAL_PATH := $(my-dir)

ifneq ($(TARGET_SIMULATOR),true)

  include $(call first-makefiles-under,$(LOCAL_PATH))

else

  include $(addprefix $(LOCAL_PATH)/,$(addsuffix /Android.mk, \

	      adb \

	      libcutils \

	      liblog \

	      libnetutils \

	      libpixelflinger \

	      libzipfile \

	   ))

endif

The system/ directory is intended for pieces of the world that are the

core of the embedded linux platform at the heart of Android.  These

essential bits are required for basic booting, operation, and debugging.

They should not depend on libraries outside of system/... (some of them

do currently -- they need to be updated or changed) and they should not

be required for the simulator build.

The license for all these pieces should be clean (Apache2, BSD, or MIT).

Currently system/bluetooth/... and system/extra/... have some pieces

with GPL/LGPL licensed code.

Assorted Issues:

- pppd depends on libutils for logging

- pppd depends on libcrypt/libcrypto

- init, linker, debuggerd, toolbox, usbd depend on libcutils

- should probably rename bionic to libc

# Copyright 2005 The Android Open Source Project

#

# Android.mk for adb

#

LOCAL_PATH:= $(call my-dir)

# adb host tool

# =========================================================

ifneq ($(TARGET_SIMULATOR),true) # not 64 bit clean (also unused with the sim)

include $(CLEAR_VARS)

# Default to a virtual (sockets) usb interface

USB_SRCS :=

EXTRA_SRCS :=

ifeq ($(HOST_OS),linux)

  USB_SRCS := usb_linux.c

  EXTRA_SRCS := get_my_path_linux.c

  LOCAL_LDLIBS += -lrt -lncurses -lpthread

endif

ifeq ($(HOST_OS),darwin)

  USB_SRCS := usb_osx.c

  EXTRA_SRCS := get_my_path_darwin.c

  LOCAL_LDLIBS += -lpthread -framework CoreFoundation -framework IOKit -framework Carbon

endif

ifeq ($(HOST_OS),windows)

  USB_SRCS := usb_windows.c

  EXTRA_SRCS := get_my_path_windows.c

  EXTRA_STATIC_LIBS := AdbWinApi

  LOCAL_C_INCLUDES += /usr/include/w32api/ddk development/host/windows/usb/api/

  ifneq ($(strip $(USE_CYGWIN)),)

    LOCAL_LDLIBS += -lpthread

  else

    LOCAL_LDLIBS += -lws2_32

    USE_SYSDEPS_WIN32 := 1

  endif

endif

LOCAL_SRC_FILES := \

	adb.c \

	console.c \

	transport.c \

	transport_local.c \

	transport_usb.c \

	commandline.c \

	adb_client.c \

	sockets.c \

	services.c \

	file_sync_client.c \

	$(EXTRA_SRCS) \

	$(USB_SRCS) \

	shlist.c \

	utils.c \

ifneq ($(USE_SYSDEPS_WIN32),)

  LOCAL_SRC_FILES += sysdeps_win32.c

endif

LOCAL_CFLAGS += -O2 -g -DADB_HOST=1  -Wall -Wno-unused-parameter

LOCAL_CFLAGS += -D_XOPEN_SOURCE -D_GNU_SOURCE -DSH_HISTORY

LOCAL_MODULE := adb

LOCAL_STATIC_LIBRARIES := libzipfile libunz $(EXTRA_STATIC_LIBS)

ifeq ($(USE_SYSDEPS_WIN32),)

	LOCAL_STATIC_LIBRARIES += libcutils

endif

include $(BUILD_HOST_EXECUTABLE)

$(call dist-for-goals,droid,$(LOCAL_BUILT_MODULE))

ifeq ($(HOST_OS),windows)

$(LOCAL_INSTALLED_MODULE): $(HOST_OUT_EXECUTABLES)/AdbWinApi.dll

endif

endif

# adbd device daemon

# =========================================================

# build adbd in all non-simulator builds

BUILD_ADBD := false

ifneq ($(TARGET_SIMULATOR),true)

    BUILD_ADBD := true

endif

# build adbd for the Linux simulator build

# so we can use it to test the adb USB gadget driver on x86

ifeq ($(HOST_OS),linux)

    BUILD_ADBD := true

endif

ifeq ($(BUILD_ADBD),true)

include $(CLEAR_VARS)

LOCAL_SRC_FILES := \

	adb.c \

	transport.c \

	transport_local.c \

	transport_usb.c \

	sockets.c \

	services.c \

	file_sync_service.c \

	jdwp_service.c \

	framebuffer_service.c \

	remount_service.c \

	usb_linux_client.c \

	log_service.c \

	utils.c \

LOCAL_CFLAGS := -O2 -g -DADB_HOST=0 -Wall -Wno-unused-parameter

LOCAL_CFLAGS += -D_XOPEN_SOURCE -D_GNU_SOURCE

# TODO: This should probably be board specific, whether or not the kernel has

# the gadget driver; rather than relying on the architecture type.

ifeq ($(TARGET_ARCH),arm)

LOCAL_CFLAGS += -DANDROID_GADGET=1

endif

LOCAL_MODULE := adbd

LOCAL_FORCE_STATIC_EXECUTABLE := true

LOCAL_MODULE_PATH := $(TARGET_ROOT_OUT_SBIN)

LOCAL_UNSTRIPPED_PATH := $(TARGET_ROOT_OUT_SBIN_UNSTRIPPED)

ifeq ($(TARGET_SIMULATOR),true)

  LOCAL_STATIC_LIBRARIES := libcutils

  LOCAL_LDLIBS += -lpthread

  include $(BUILD_HOST_EXECUTABLE)

else

  LOCAL_STATIC_LIBRARIES := libcutils libc

  include $(BUILD_EXECUTABLE)

endif

endif

Implementation notes regarding ADB.

I. General Overview:

The Android Debug Bridge (ADB) is used to:

- keep track of all Android devices and emulators instances

  connected to or running on a given host developer machine

- implement various control commands (e.g. "adb shell", "adb pull", etc..)

  for the benefit of clients (command-line users, or helper programs like

  DDMS). These commands are what is called a 'service' in ADB.

As a whole, everything works through the following components:

  1. The ADB server

    This is a background process that runs on the host machine. Its purpose

    if to sense the USB ports to know when devices are attached/removed,

    as well as when emulator instances start/stop.

    It thus maintains a list of "connected devices" and assigns a 'state'

    to each one of them: OFFLINE, BOOTLOADER, RECOVERY or ONLINE (more on

    this below).

    The ADB server is really one giant multiplexing loop whose purpose is

    to orchestrate the exchange of data (packets, really) between clients,

    services and devices.

  2. The ADB daemon (adbd)

    The 'adbd' program runs as a background process within an Android device

    or emulated system. Its purpose is to connect to the ADB server

    (through USB for devices, through TCP for emulators) and provide a

    few services for clients that run on the host.

    The ADB server considers that a device is ONLINE when it has succesfully

    connected to the adbd program within it. Otherwise, the device is OFFLINE,

    meaning that the ADB server detected a new device/emulator, but could not

    connect to the adbd daemon.

    the BOOTLOADER and RECOVERY states correspond to alternate states of

    devices when they are in the bootloader or recovery mode.

  3. The ADB command-line client

    The 'adb' command-line program is used to run adb commands from a shell

    or a script. It first tries to locate the ADB server on the host machine,

    and will start one automatically if none is found.

    then, the client sends its service requests to the ADB server. It doesn't

    need to know.

    Currently, a single 'adb' binary is used for both the server and client.

    this makes distribution and starting the server easier.

  4. Services

    There are essentially two kinds of services that a client can talk to.

    Host Services:

      these services run within the ADB Server and thus do not need to

      communicate with a device at all. A typical example is "adb devices"

      which is used to return the list of currently known devices and their

      state. They are a few couple other services though.

    Local Services:

      these services either run within the adbd daemon, or are started by

      it on the device. The ADB server is used to multiplex streams

      between the client and the service running in adbd. In this case

      its role is to initiate the connection, then of being a pass-through

      for the data.

II. Protocol details:

  1. Client <-> Server protocol:

    This details the protocol used between ADB clients and the ADB

    server itself. The ADB server listens on TCP:localhost:5037.

    A client sends a request using the following format:

        1. A 4-byte hexadecimal string giving the length of the payload

        2. Followed by the payload itself.

    For example, to query the ADB server for its internal version number,

    the client will do the following:

        1. Connect to tcp:localhost:5037

        2. Send the string "000Chost:version" to the corresponding socket

    The 'host:' prefix is used to indicate that the request is addressed

    to the server itself (we will talk about other kinds of requests later).

    The content length is encoded in ASCII for easier debugging.

    The server should answer a request with one of the following:

        1. For success, the 4-byte "OKAY" string

        2. For failure, the 4-byte "FAIL" string, followed by a

           4-byte hex length, followed by a string giving the reason

           for failure.

        3. As a special exception, for 'host:version', a 4-byte

           hex string corresponding to the server's internal version number

    Note that the connection is still alive after an OKAY, which allows the

    client to make other requests. But in certain cases, an OKAY will even

    change the state of the connection. 

    For example, the case of the 'host:transport:<serialnumber>' request,

    where '<serialnumber>' is used to identify a given device/emulator; after

    the "OKAY" answer, all further requests made by the client will go

    directly to the corresponding adbd daemon.

    The file SERVICES.TXT lists all services currently implemented by ADB.

  2. Transports:

    An ADB transport models a connection between the ADB server and one device

    or emulator. There are currently two kinds of transports:

       - USB transports, for physical devices through USB

       - Local transports, for emulators running on the host, connected to

         the server through TCP

    In theory, it should be possible to write a local transport that proxies

    a connection between an ADB server and a device/emulator connected to/

    running on another machine. This hasn't been done yet though.

    Each transport can carry one or more multiplexed streams between clients

    and the device/emulator they point to. The ADB server must handle

    unexpected transport disconnections (e.g. when a device is physically

    unplugged) properly.

This file tries to document all requests a client can make

to the ADB server of an adbd daemon. See the OVERVIEW.TXT document

to understand what's going on here.

HOST SERVICES:

host:version

    Ask the ADB server for its internal version number.

    As a special exception, the server will respond with a 4-byte

    hex string corresponding to its internal version number, without

    any OKAY or FAIL.

host:kill

    Ask the ADB server to quit immediately. This is used when the

    ADB client detects that an obsolete server is running after an

    upgrade.

host:devices

    Ask to return the list of available Android devices and their

    state. After the OKAY, this is followed by a 4-byte hex len,

    and a string that will be dumped as-is by the client, then

    the connection is closed

host:track-devices

    This is a variant of host:devices which doesn't close the

    connection. Instead, a new device list description is sent

    each time a device is added/removed or the state of a given

    device changes (hex4 + content). This allows tools like DDMS

    to track the state of connected devices in real-time without

    polling the server repeatedly.

host:emulator:<port>

    This is a special query that is sent to the ADB server when a

    new emulator starts up. <port> is a decimal number corresponding

    to the emulator's ADB control port, i.e. the TCP port that the

    emulator will forward automatically to the adbd daemon running

    in the emulator system.

    This mechanism allows the ADB server to know when new emulator

    instances start.

host:transport:<serial-number>

    Ask to switch the connection to the device/emulator identified by

    <serial-number>. After the OKAY response, every client request will

    be sent directly to the adbd daemon running on the device.

    (Used to implement the -s option)

host:transport-usb

    Ask to switch the connection to one device connected through USB

    to the host machine. This will fail if there are more than one such

    devices. (Used to implement the -d convenience option)

host:transport-local

    Ask to switch the connection to one emulator connected through TCP.

    This will fail if there is more than one such emulator instance

    running. (Used to implement the -e convenience option)

host:transport-any

    Another host:transport variant. Ask to switch the connection to

    either the device or emulator connect to/running on the host.

    Will fail if there is more than one such device/emulator available.

    (Used when neither -s, -d or -e are provided)

host-serial:<serial-number>:<request>

    This is a special form of query, where the 'host-serial:<serial-number>:'

    prefix can be used to indicate that the client is asking the ADB server

    for information related to a specific device. <request> can be in one

    of the format described below.

host-usb:<request>

    A variant of host-serial used to target the single USB device connected

    to the host. This will fail if there is none or more than one.

host-local:<request>

    A variant of host-serial used to target the single emulator instance

    running on the host. This will fail if therre is none or more than one.

host:<request>

    When asking for information related to a device, 'host:' can also be

    interpreted as 'any single device or emulator connected to/running on

    the host'.

<host-prefix>:get-product

    XXX

<host-prefix>:get-serialno

    Returns the serial number of the corresponding device/emulator.

    Note that emulator serial numbers are of the form "emulator-5554"

<host-prefix>:get-state

    Returns the state of a given device as a string.

<host-prefix>:forward:<local>;<remote>

    Asks the ADB server to forward local connections from <local>

    to the <remote> address on a given device.

    There, <host-prefix> can be one of the

    host-serial/host-usb/host-local/host prefixes as described previously

    and indicates which device/emulator to target.

    the format of <local> is one of:

        tcp:<port>      -> TCP connection on localhost:<port>

        local:<path>    -> Unix local domain socket on <path>

    the format of <remote> is one of:

        tcp:<port>      -> TCP localhost:<port> on device

        local:<path>    -> Unix local domain socket on device

        jdwp:<pid>      -> JDWP thread on VM process <pid>

    or even any one of the local services described below.

LOCAL SERVICES:

All the queries below assumed that you already switched the transport

to a real device, or that you have used a query prefix as described

above.

shell:command arg1 arg2 ...

    Run 'command arg1 arg2 ...' in a shell on the device, and return

    its output and error streams. Note that arguments must be separated

    by spaces. If an argument contains a space, it must be quoted with

    double-quotes. Arguments cannot contain double quotes or things

    will go very wrong.

    Note that this is the non-interactive version of "adb shell"

shell:

    Start an interactive shell session on the device. Redirect

    stdin/stdout/stderr as appropriate. Note that the ADB server uses

    this to implement "adb shell", but will also cook the input before

    sending it to the device (see interactive_shell() in commandline.c)

remount:

    Ask adbd to remount the device's filesystem in read-write mode,

    instead of read-only. This is usually necessary before performing

    an "adb sync" or "adb push" request.

    This request may not succeed on certain builds which do not allow

    that.

dev:<path>

    Opens a device file and connects the client directly to it for

    read/write purposes. Useful for debugging, but may require special

    priviledges and thus may not run on all devices. <path> is a full

    path from the root of the filesystem.

tcp:<port>

    Tries to connect to tcp port <port> on localhost.

tcp:<port>:<server-name>

    Tries to connect to tcp port <port> on machine <server-name> from

    the device. This can be useful to debug some networking/proxy

    issues that can only be revealed on the device itself.

local:<path>

    Tries to connect to a Unix domain socket <path> on the device

localreserved:<path>

localabstract:<path>

localfilesystem:<path>

    Variants of local:<path> that are used to access other Android

    socket namespaces.

log:<name>

    Opens one of the system logs (/dev/log/<name>) and allows the client

    to read them directly. Used to implement 'adb logcat'. The stream

    will be read-only for the client.

framebuffer:

    This service is used to send snapshots of the framebuffer to a client.

    It requires sufficient priviledges but works as follow:

      After the OKAY, the service sends 16-byte binary structure

      containing the following fields (little-endian format):

            depth:   uint32_t:    framebuffer depth

            size:    uint32_t:    framebuffer size in bytes

            width:   uint32_t:    framebuffer width in pixels

            height:  uint32_t:    framebuffer height in pixels

      With the current implementation, depth is always 16, and

      size is always width*height*2

      Then, each time the client wants a snapshot, it should send

      one byte through the channel, which will trigger the service

      to send it 'size' bytes of framebuffer data.

      If the adbd daemon doesn't have sufficient priviledges to open

      the framebuffer device, the connection is simply closed immediately.

dns:<server-name>

    This service is an exception because it only runs within the ADB server.

    It is used to implement USB networking, i.e. to provide a network connection

    to the device through the host machine (note: this is the exact opposite of

    network thetering).

    It is used to perform a gethostbyname(<address>) on the host and return

    the corresponding IP address as a 4-byte string.

recover:<size>

    This service is used to upload a recovery image to the device. <size>

    must be a number corresponding to the size of the file. The service works

    by:

       - creating a file named /tmp/update

       - reading 'size' bytes from the client and writing them to /tmp/update

       - when everything is read succesfully, create a file named /tmp/update.start

    This service can only work when the device is in recovery mode. Otherwise,

    the /tmp directory doesn't exist and the connection will be closed immediately.

jdwp:<pid>

    Connects to the JDWP thread running in the VM of process <pid>.

track-jdwp

    This is used to send the list of JDWP pids periodically to the client.

    The format of the returned data is the following:

        <hex4>:    the length of all content as a 4-char hexadecimal string

        <content>: a series of ASCII lines of the following format:

                        <pid> "\n"

    This service is used by DDMS to know which debuggable processes are running

    on the device/emulator.

    Note that there is no single-shot service to retrieve the list only once.

sync:

    This starts the file synchronisation service, used to implement "adb push"

    and "adb pull". Since this service is pretty complex, it will be detailed

    in a companion document named SYNC.TXT