Reimport
This commit is contained in:
388
tools/adb/systrace/catapult/devil/docs/adb_wrapper.md
Normal file
388
tools/adb/systrace/catapult/devil/docs/adb_wrapper.md
Normal file
@@ -0,0 +1,388 @@
|
||||
# [devil.android.sdk.adb_wrapper](https://github.com/catapult-project/catapult/blob/master/devil/devil/android/sdk/adb_wrapper.py)
|
||||
|
||||
*This page was autogenerated by `devil/utils/markdown.py --module-link https://github.com/catapult-project/catapult/blob/master/devil/devil/android/sdk/adb_wrapper.py`*
|
||||
|
||||
## DeviceStat
|
||||
|
||||
DeviceStat(st\_mode, st\_size, st\_time)
|
||||
### DeviceStat.\_\_repr\_\_
|
||||
|
||||
Return a nicely formatted representation string
|
||||
### DeviceStat.\_\_getnewargs\_\_
|
||||
|
||||
Return self as a plain tuple. Used by copy and pickle.
|
||||
### DeviceStat.\_\_getstate\_\_
|
||||
|
||||
Exclude the OrderedDict from pickling
|
||||
## AdbWrapper
|
||||
|
||||
A wrapper around a local Android Debug Bridge executable.
|
||||
### AdbWrapper.GetDeviceSerial
|
||||
|
||||
Gets the device serial number associated with this object.
|
||||
```
|
||||
Returns:
|
||||
Device serial number as a string.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.Push
|
||||
|
||||
Pushes a file from the host to the device.
|
||||
```
|
||||
Args:
|
||||
local: Path on the host filesystem.
|
||||
remote: Path on the device filesystem.
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.Pull
|
||||
|
||||
Pulls a file from the device to the host.
|
||||
```
|
||||
Args:
|
||||
remote: Path on the device filesystem.
|
||||
local: Path on the host filesystem.
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.Shell
|
||||
|
||||
Runs a shell command on the device.
|
||||
```
|
||||
Args:
|
||||
command: A string with the shell command to run.
|
||||
expect_status: (optional) Check that the command's exit status matches
|
||||
this value. Default is 0. If set to None the test is skipped.
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
|
||||
Returns:
|
||||
The output of the shell command as a string.
|
||||
|
||||
Raises:
|
||||
device_errors.AdbCommandFailedError: If the exit status doesn't match
|
||||
|expect_status|.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.IterShell
|
||||
|
||||
Runs a shell command and returns an iterator over its output lines.
|
||||
```
|
||||
Args:
|
||||
command: A string with the shell command to run.
|
||||
timeout: Timeout in seconds.
|
||||
|
||||
Yields:
|
||||
The output of the command line by line.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.Ls
|
||||
|
||||
List the contents of a directory on the device.
|
||||
```
|
||||
Args:
|
||||
path: Path on the device filesystem.
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
|
||||
Returns:
|
||||
A list of pairs (filename, stat) for each file found in the directory,
|
||||
where the stat object has the properties: st_mode, st_size, and st_time.
|
||||
|
||||
Raises:
|
||||
AdbCommandFailedError if |path| does not specify a valid and accessible
|
||||
directory in the device, or the output of "adb ls" command is less
|
||||
than four columns
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.Logcat
|
||||
|
||||
Get an iterable over the logcat output.
|
||||
```
|
||||
Args:
|
||||
clear: If true, clear the logcat.
|
||||
dump: If true, dump the current logcat contents.
|
||||
filter_specs: If set, a list of specs to filter the logcat.
|
||||
logcat_format: If set, the format in which the logcat should be output.
|
||||
Options include "brief", "process", "tag", "thread", "raw", "time",
|
||||
"threadtime", and "long"
|
||||
ring_buffer: If set, a list of alternate ring buffers to request.
|
||||
Options include "main", "system", "radio", "events", "crash" or "all".
|
||||
The default is equivalent to ["main", "system", "crash"].
|
||||
iter_timeout: If set and neither clear nor dump is set, the number of
|
||||
seconds to wait between iterations. If no line is found before the
|
||||
given number of seconds elapses, the iterable will yield None.
|
||||
timeout: (optional) If set, timeout per try in seconds. If clear or dump
|
||||
is set, defaults to DEFAULT_TIMEOUT.
|
||||
retries: (optional) If clear or dump is set, the number of retries to
|
||||
attempt. Otherwise, does nothing.
|
||||
|
||||
Yields:
|
||||
logcat output line by line.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.Forward
|
||||
|
||||
Forward socket connections from the local socket to the remote socket.
|
||||
```
|
||||
Sockets are specified by one of:
|
||||
tcp:<port>
|
||||
localabstract:<unix domain socket name>
|
||||
localreserved:<unix domain socket name>
|
||||
localfilesystem:<unix domain socket name>
|
||||
dev:<character device name>
|
||||
jdwp:<process pid> (remote only)
|
||||
|
||||
Args:
|
||||
local: The host socket.
|
||||
remote: The device socket.
|
||||
allow_rebind: A boolean indicating whether adb may rebind a local socket;
|
||||
otherwise, the default, an exception is raised if the local socket is
|
||||
already being forwarded.
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.ForwardRemove
|
||||
|
||||
Remove a forward socket connection.
|
||||
```
|
||||
Args:
|
||||
local: The host socket.
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.ForwardList
|
||||
|
||||
List all currently forwarded socket connections.
|
||||
```
|
||||
Args:
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
Returns:
|
||||
The output of adb forward --list as a string.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.JDWP
|
||||
|
||||
List of PIDs of processes hosting a JDWP transport.
|
||||
```
|
||||
Args:
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
|
||||
Returns:
|
||||
A list of PIDs as strings.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.Install
|
||||
|
||||
Install an apk on the device.
|
||||
```
|
||||
Args:
|
||||
apk_path: Host path to the APK file.
|
||||
forward_lock: (optional) If set forward-locks the app.
|
||||
allow_downgrade: (optional) If set, allows for downgrades.
|
||||
reinstall: (optional) If set reinstalls the app, keeping its data.
|
||||
sd_card: (optional) If set installs on the SD card.
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.InstallMultiple
|
||||
|
||||
Install an apk with splits on the device.
|
||||
```
|
||||
Args:
|
||||
apk_paths: Host path to the APK file.
|
||||
forward_lock: (optional) If set forward-locks the app.
|
||||
reinstall: (optional) If set reinstalls the app, keeping its data.
|
||||
sd_card: (optional) If set installs on the SD card.
|
||||
allow_downgrade: (optional) Allow versionCode downgrade.
|
||||
partial: (optional) Package ID if apk_paths doesn't include all .apks.
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.Uninstall
|
||||
|
||||
Remove the app |package| from the device.
|
||||
```
|
||||
Args:
|
||||
package: The package to uninstall.
|
||||
keep_data: (optional) If set keep the data and cache directories.
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.Backup
|
||||
|
||||
Write an archive of the device's data to |path|.
|
||||
```
|
||||
Args:
|
||||
path: Local path to store the backup file.
|
||||
packages: List of to packages to be backed up.
|
||||
apk: (optional) If set include the .apk files in the archive.
|
||||
shared: (optional) If set buckup the device's SD card.
|
||||
nosystem: (optional) If set exclude system applications.
|
||||
include_all: (optional) If set back up all installed applications and
|
||||
|packages| is optional.
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.Restore
|
||||
|
||||
Restore device contents from the backup archive.
|
||||
```
|
||||
Args:
|
||||
path: Host path to the backup archive.
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.WaitForDevice
|
||||
|
||||
Block until the device is online.
|
||||
```
|
||||
Args:
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.GetState
|
||||
|
||||
Get device state.
|
||||
```
|
||||
Args:
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
|
||||
Returns:
|
||||
One of 'offline', 'bootloader', or 'device'.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.GetDevPath
|
||||
|
||||
Gets the device path.
|
||||
```
|
||||
Args:
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
|
||||
Returns:
|
||||
The device path (e.g. usb:3-4)
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.Remount
|
||||
|
||||
Remounts the /system partition on the device read-write.
|
||||
### AdbWrapper.Reboot
|
||||
|
||||
Reboots the device.
|
||||
```
|
||||
Args:
|
||||
to_bootloader: (optional) If set reboots to the bootloader.
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.Root
|
||||
|
||||
Restarts the adbd daemon with root permissions, if possible.
|
||||
```
|
||||
Args:
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.Emu
|
||||
|
||||
Runs an emulator console command.
|
||||
```
|
||||
See http://developer.android.com/tools/devices/emulator.html#console
|
||||
|
||||
Args:
|
||||
cmd: The command to run on the emulator console.
|
||||
timeout: (optional) Timeout per try in seconds.
|
||||
retries: (optional) Number of retries to attempt.
|
||||
|
||||
Returns:
|
||||
The output of the emulator console command.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.DisableVerity
|
||||
|
||||
Disable Marshmallow's Verity security feature
|
||||
### AdbWrapper.EnableVerity
|
||||
|
||||
Enable Marshmallow's Verity security feature
|
||||
### AdbWrapper.\_\_init\_\_
|
||||
|
||||
Initializes the AdbWrapper.
|
||||
```
|
||||
Args:
|
||||
device_serial: The device serial number as a string.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.\_\_eq\_\_
|
||||
|
||||
Consider instances equal if they refer to the same device.
|
||||
```
|
||||
Args:
|
||||
other: The instance to compare equality with.
|
||||
|
||||
Returns:
|
||||
True if the instances are considered equal, false otherwise.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.\_\_str\_\_
|
||||
|
||||
The string representation of an instance.
|
||||
```
|
||||
Returns:
|
||||
The device serial number as a string.
|
||||
```
|
||||
|
||||
|
||||
### AdbWrapper.\_\_repr\_\_
|
||||
|
||||
### VerifyLocalFileExists
|
||||
|
||||
Verifies a local file exists.
|
||||
```
|
||||
Args:
|
||||
path: Path to the local file.
|
||||
|
||||
Raises:
|
||||
IOError: If the file doesn't exist.
|
||||
```
|
||||
|
||||
|
||||
59
tools/adb/systrace/catapult/devil/docs/device_blacklist.md
Normal file
59
tools/adb/systrace/catapult/devil/docs/device_blacklist.md
Normal file
@@ -0,0 +1,59 @@
|
||||
<!-- Copyright 2016 The Chromium Authors. All rights reserved.
|
||||
Use of this source code is governed by a BSD-style license that can be
|
||||
found in the LICENSE file.
|
||||
-->
|
||||
|
||||
# Devil: Device Blacklist
|
||||
|
||||
## What is it?
|
||||
|
||||
The device blacklist is a per-run list of devices detected to be in a known bad
|
||||
state along with the reason they are suspected of being in a bad state (offline,
|
||||
not responding, etc). It is stored as a json file. This gets reset every run
|
||||
during the device recovery step (currently part of `bb_device_status_check`).
|
||||
|
||||
## Bots
|
||||
|
||||
On bots, this is normally found at `//out/bad_devices.json`. If you are having
|
||||
problems with blacklisted devices locally even though a device is in a good
|
||||
state, you can safely delete this file.
|
||||
|
||||
# Tools for interacting with device black list.
|
||||
|
||||
You can interact with the device blacklist via [devil.android.device\_blacklist](https://cs.chromium.org/chromium/src/third_party/catapult/devil/devil/android/device_blacklist.py).
|
||||
This allows for any interaction you would need with a device blacklist:
|
||||
|
||||
- Reading
|
||||
- Writing
|
||||
- Extending
|
||||
- Resetting
|
||||
|
||||
An example usecase of this is:
|
||||
```python
|
||||
from devil.android import device_blacklist
|
||||
|
||||
blacklist = device_blacklist.Blacklist(blacklist_path)
|
||||
blacklisted_devices = blacklist.Read()
|
||||
for device in blacklisted_devices:
|
||||
print 'Device %s is blacklisted' % device
|
||||
blacklist.Reset()
|
||||
new_blacklist = {'device_id1': {'timestamp': ts, 'reason': reason}}
|
||||
blacklist.Write(new_blacklist)
|
||||
blacklist.Extend([device_2, device_3], reason='Reason for blacklisting')
|
||||
```
|
||||
|
||||
|
||||
## Where it is used.
|
||||
|
||||
The blacklist file path is passed directly to the following scripts in chromium:
|
||||
|
||||
- [test\_runner.py](https://cs.chromium.org/chromium/src/build/android/test_runner.py)
|
||||
- [provision\_devices.py](https://cs.chromium.org/chromium/src/build/android/provision_devices.py)
|
||||
- [bb\_device\_status\_check.py](https://cs.chromium.org/chromium/src/build/android/buildbot/bb_device_status_check.py)
|
||||
|
||||
The blacklist is also used in the following scripts:
|
||||
|
||||
- [device\_status.py](https://cs.chromium.org/chromium/src/third_party/catapult/devil/devil/android/tools/device_status.py)
|
||||
- [device\_recovery.py](https://cs.chromium.org/chromium/src/third_party/catapult/devil/devil/android/tools/device_recovery.py)
|
||||
|
||||
|
||||
1086
tools/adb/systrace/catapult/devil/docs/device_utils.md
Normal file
1086
tools/adb/systrace/catapult/devil/docs/device_utils.md
Normal file
File diff suppressed because it is too large
Load Diff
139
tools/adb/systrace/catapult/devil/docs/markdown.md
Normal file
139
tools/adb/systrace/catapult/devil/docs/markdown.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# [devil.utils.markdown](https://github.com/catapult-project/catapult/blob/master/devil/devil/utils/markdown.py)
|
||||
|
||||
*This page was autogenerated by `devil/utils/markdown.py --module-link https://github.com/catapult-project/catapult/blob/master/devil/devil/utils/markdown.py`*
|
||||
|
||||
## MarkdownHelpAction
|
||||
|
||||
### MarkdownHelpAction.\_\_init\_\_
|
||||
|
||||
### MarkdownHelpAction.\_\_call\_\_
|
||||
|
||||
## MarkdownHelpFormatter
|
||||
|
||||
A really bare-bones argparse help formatter that generates valid markdown.
|
||||
```
|
||||
This will generate something like:
|
||||
|
||||
usage
|
||||
|
||||
# **section heading**:
|
||||
|
||||
## **--argument-one**
|
||||
|
||||
\`\`\`
|
||||
argument-one help text
|
||||
\`\`\`
|
||||
|
||||
```
|
||||
|
||||
|
||||
### MarkdownHelpFormatter.format\_help
|
||||
|
||||
### MarkdownHelpFormatter.start\_section
|
||||
|
||||
### md\_bold
|
||||
|
||||
Returns markdown-formatted bold text.
|
||||
### md\_code
|
||||
|
||||
Returns a markdown-formatted code block in the given language.
|
||||
### md\_escape
|
||||
|
||||
Escapes \* and \_.
|
||||
### md\_heading
|
||||
|
||||
Returns markdown-formatted heading.
|
||||
### md\_inline\_code
|
||||
|
||||
Returns markdown-formatted inline code.
|
||||
### md\_italic
|
||||
|
||||
Returns markdown-formatted italic text.
|
||||
### md\_link
|
||||
|
||||
returns a markdown-formatted link.
|
||||
### add\_md\_help\_argument
|
||||
|
||||
Adds --md-help to the given argparse.ArgumentParser.
|
||||
```
|
||||
Running a script with --md-help will print the help text for that script
|
||||
as valid markdown.
|
||||
|
||||
Args:
|
||||
parser: The ArgumentParser to which --md-help should be added.
|
||||
```
|
||||
|
||||
|
||||
### load\_module\_from\_path
|
||||
|
||||
Load a module given only the path name.
|
||||
```
|
||||
Also loads package modules as necessary.
|
||||
|
||||
Args:
|
||||
module_path: An absolute path to a python module.
|
||||
Returns:
|
||||
The module object for the given path.
|
||||
```
|
||||
|
||||
|
||||
### md\_module
|
||||
|
||||
Write markdown documentation for a class.
|
||||
```
|
||||
Documents public classes and functions.
|
||||
|
||||
Args:
|
||||
class_obj: a types.TypeType object for the class that should be
|
||||
documented.
|
||||
Returns:
|
||||
A list of markdown-formatted lines.
|
||||
```
|
||||
|
||||
|
||||
### md\_class
|
||||
|
||||
Write markdown documentation for a class.
|
||||
```
|
||||
Documents public methods. Does not currently document subclasses.
|
||||
|
||||
Args:
|
||||
class_obj: a types.TypeType object for the class that should be
|
||||
documented.
|
||||
Returns:
|
||||
A list of markdown-formatted lines.
|
||||
```
|
||||
|
||||
|
||||
### md\_docstring
|
||||
|
||||
Write a markdown-formatted docstring.
|
||||
```
|
||||
Returns:
|
||||
A list of markdown-formatted lines.
|
||||
```
|
||||
|
||||
|
||||
### md\_function
|
||||
|
||||
Write markdown documentation for a function.
|
||||
```
|
||||
Args:
|
||||
func_obj: a types.FunctionType object for the function that should be
|
||||
documented.
|
||||
Returns:
|
||||
A list of markdown-formatted lines.
|
||||
```
|
||||
|
||||
|
||||
### main
|
||||
|
||||
Write markdown documentation for the module at the provided path.
|
||||
```
|
||||
Args:
|
||||
raw_args: the raw command-line args. Usually sys.argv[1:].
|
||||
Returns:
|
||||
An integer exit code. 0 for success, non-zero for failure.
|
||||
```
|
||||
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
<!-- Copyright 2016 The Chromium Authors. All rights reserved.
|
||||
Use of this source code is governed by a BSD-style license that can be
|
||||
found in the LICENSE file.
|
||||
-->
|
||||
|
||||
# Devil: Persistent Device List
|
||||
|
||||
## What is it?
|
||||
|
||||
A persistent device list that stores all expected devices between builds. It
|
||||
is used by non-swarmed bots to detect any missing/extra devices attached to
|
||||
them.
|
||||
|
||||
This will be no longer needed when all bots are switched over to swarming.
|
||||
|
||||
## Bots
|
||||
|
||||
The list is usually located at:
|
||||
|
||||
- `~/.android/known_devices.json`.
|
||||
|
||||
Look at recipes listed below in order to find more up to date location.
|
||||
|
||||
## Local Runs
|
||||
|
||||
The persistent device list is unnecessary for local runs. It is only used on the
|
||||
bots that upload data to the perf dashboard.
|
||||
|
||||
## Where it is used
|
||||
|
||||
The persistent device list is used in the
|
||||
[chromium_android](https://cs.chromium.org/chromium/build/scripts/slave/recipe_modules/chromium_android/api.py?q=known_devices_file)
|
||||
recipe module, and consumed by the
|
||||
[device_status.py](https://cs.chromium.org/chromium/src/third_party/catapult/devil/devil/android/tools/device_status.py?q=\-\-known%5C-devices%5C-file)
|
||||
script among others.
|
||||
Reference in New Issue
Block a user