| #!/bin/bash |
| # Copyright 2019 The Fuchsia Authors. All rights reserved. |
| # Use of this source code is governed by a BSD-style license that can be |
| # found in the LICENSE file. |
| |
| #### CATEGORY=Run, inspect and debug |
| ### run fidlcat on given target. |
| |
| ## Runs fidlcat in the given configuration; currently, fidlcat logs all FIDL |
| ## chatter from the given target executable. Starts the debug agent on the |
| ## proposed target, and closes the debug agent on exit. |
| ## |
| ## CAUTION: This support is experimental, and invocation strategy is likely to |
| ## change. The component launching configuration is *especially* likely to go |
| ## away over time. |
| ## |
| ## TROUBLESHOOTING TIPS: |
| ## |
| ## - Remember to use "fx set-device" when working with multiple devices. |
| ## - This scripts by default will mute the SSH connection stdout/stderr, so any |
| ## errors triggered by it won't appear. Use the --debug-mode flag to see |
| ## the debug log's from the debug agent and fidlcat. |
| ## - This scripts uses the tool "nc" for testing TCP connections. Check that it |
| ## is in $PATH and that it works. |
| ## |
| ## Usage: fx fidlcat [(--port|-p) <PORT>] [--with-symbol-server] [--debug-mode] |
| ## [--symbol-path=<path>] [--fidl-ir-path=<path>] [--gdb] |
| ## [--from=<source>] [--to=<path>] [--format=<output>] |
| ## [--with-process-info] [--stack=<value>] |
| ## [--syscalls=<regexp>] [--exclude-syscalls=<regexp>] |
| ## [--messages=<regexp>] [--exclude-messages=<regexp>] [--trigger=<regexp>] |
| ## [--dump-messages] |
| ## [--verbose=<value> | --quiet=<value>] [--log-file <path>] |
| ## [--remote-pid=<pid>] [--remote-name=<name>] [--extra-name=<name>] |
| ## [run <component specification>] |
| ## |
| ## System options: |
| ## --port Port the debug agent will be listening on. Will use 2345 by default. |
| ## --with-symbol-server Connect to the symbol server. The first time you use this option, |
| ## fidlcat will give you a link to an authentication page. |
| ## You then have to use the generated key to authenticate. |
| ## --debug-mode Whether the debug agent's debug logs should be shown. |
| ## --symbol-path=<path> An extra location where fidlcat can find debug symbols. |
| ## --fidl-ir-path=<path> An extra location where fidlcat can find FIDL compiled files. |
| ## --gdb Launch fidlcat using gdb. This is only useful to be able to debug |
| ## fidlcat. When this option is used, the string you have to type within |
| ## gdb to launch fidlcat is printed and then, gdb is launched. |
| ## This option only works if you have the unstripped version of fidlcat. |
| ## |
| ## Input options: |
| ## --from=<source> This option must be used at most once. |
| ## Source can be: |
| ## --from=device This is the default input. The input comes from the live |
| ## monitoring of one or several processes. |
| ## At least one of '--remote-pid', '--remote-name', 'run' must |
| ## be specified. |
| ## --from=<path> The input comes from a previously recorded session (protobuf |
| ## format). Path gives the name of the file to read. If path is |
| ## '-' then the standard input is used. |
| ## |
| ## Session save option: |
| ## --to=<path> The session is saved to the specified file (binary protobuf format). |
| ## When a session is saved, you can replay it using "--from=<path>". |
| ## The raw data is saved. That means that the data saved is independent from what is |
| ## displayed. |
| ## |
| ## Format (output) options: |
| ## --format=<output> You can use one of this output formats: |
| ## --format=pretty The session is pretty printed (with colors). |
| ## This is the default output if --with is not used. |
| ## --format=json The session is printed using a json format. |
| ## --format=textproto The session is printed using a text protobuf format. |
| ## --format= Nothing is displayed on the standard output (this option |
| ## only makes sense when used with --to=<path> or with |
| ## --with). |
| ## When there is no output, fidlcat is much faster (this is |
| ## better when you want to monitor real time components). |
| ## This is the default output is --with is used. |
| ## |
| ## Extra generation: |
| ## These options can be used several times. |
| ## --with=summary At the end of the session, a summary of the session is displayed on the |
| ## standard output. |
| ## --with=summary=<path> Like --with=summary but the result is stored into the file specified by |
| ## <path>. |
| ## --with=top At the end of the session, generate a view that groups the output by |
| ## process, protocol, and method. The groups are sorted by number of |
| ## events, so groups with more associated events are listed earlier. |
| ## --with=top=<path> Like --with=top but the result is stored into the file specified by |
| ## <path>. |
| ## |
| ## Display options: |
| ## --with-process-info Display the process name, process id and thread id on |
| ## each line (useful for grep). |
| ## --stack=<value> Define the amount of stack frame to display |
| ## 0: none (default value) |
| ## 1: call site (1 to 4 levels) |
| ## 2: full stack frame (adds some overhead) |
| ## --syscalls=<regexp> A regular expression which selects the syscalls to decode and |
| ## display. |
| ## Can be passed multiple times. |
| ## By default, only zx_channel_.* syscalls are displayed. |
| ## To display all the syscalls, use: --syscalls ".*" |
| ## --exclude-syscalls=<regexp> A regular expression which selects the syscalls to not decode and |
| ## display. |
| ## Can be passed multiple times. |
| ## To be displayed, a syscall must verify --syscalls and not verify |
| ## --exclude-syscalls. |
| ## To display all the syscalls but the zx_handle syscalls, use: |
| ## --syscalls ".*" --exclude-syscalls "zx_handle_.*" |
| ## --messages=<regexp> A regular expression which selects the messages to display. |
| ## To display a message, the method name must satisfy the regexp. |
| ## This option can be specified multiple times. |
| ## Message filtering works on the method's fully qualified name. |
| ## --exclude-messages=<regexp> A regular expression which selects the messages to not display. |
| ## If a message method name satisfy the regexp, the message is not |
| ## displayed (even if it satisfies --messages). |
| ## This option can be specified multiple times. |
| ## Message filtering works on the method's fully qualified name. |
| ## --trigger=<regexp> Start displaying messages and syscalls only when a message for |
| ## which the method name satisfies the filter is found. |
| ## This option can be specified multiple times. |
| ## Message filtering works on the method's fully qualified name. |
| ## --dump-messages Always does a hexadecimal dump of the messages even if we can |
| ## decode them. |
| ## |
| ## Logging options: |
| ## --verbose=<value> The log verbosity. Legal values are "info", "warning", "error", "fatal", |
| ## or a number, starting from 0. Extra verbosity comes with higher levels. |
| ## --quiet=<value> The log verbosity. Legal values are "info", "warning", "error", "fatal", |
| ## or a number, starting from 0. Extra verbosity comes with lower levels. |
| ## --log-file=<path> The log file destination. |
| ## |
| ## Monitoring options: |
| ## --remote-pid=<pid> The koid of the remote process to trace. |
| ## --remote-name=<name> A set of comma-separated regexes. Fidlcat will monitor all existing |
| ## and future processes whose names match one of the regexes. |
| ## Can be provided multiple times for multiple regexes. |
| ## --extra-name=<name> Like --remote-name, it monitors some processes. However, for these |
| ## processes, monitoring starts only when one of of the "--remote-name" |
| ## process is launched. Also, fidlcat stops when the last "--remote-name" |
| ## process stops (even if some "--extra-name" processes are still |
| ## monitored). |
| ## run <component spec> A token indicating that you want to invoke and trace the following |
| ## component. The component is specified with either a bash regex that |
| ## matches a component URL known to the build, or a full component URL not |
| ## known to your build, but available to your target. |
| ## |
| ## Flags after -- are parsed by fidlcat. |
| ## |
| ## Example usage: |
| ## |
| ## # Attaches to the process with the given pid on the target: |
| ## fx fidlcat --remote-pid=4755 |
| ## |
| ## # Launches the echo client, and monitors its FIDL chatter: |
| ## fx fidlcat run fuchsia-pkg://fuchsia.com/echo_client_cpp#meta/echo_client_cpp.cmx |
| ## |
| ## # Also launches the echo client, and monitors its FIDL chatter: |
| ## fx fidlcat run echo_client_cpp.cmx |
| ## |
| ## # Will trace existing and future processes whose name contains "echo_client" |
| ## fx fidlcat --remote-name=echo_client |
| ## |
| ## All options --remote-pid, --remote-name, --extra-name and, run can be used together. |
| ## However, run must always be the last one. |
| ## When --remote-name and run are used together, only processes which match --remote-name are |
| ## monitored. |
| ## |
| ## Examples (echo_server is launched by echo_client): |
| ## |
| ## # run and monitor echo_client. |
| ## fx fidlcat run echo_client_cpp.cmx |
| ## |
| ## # run and monitor echo_client. |
| ## fx fidlcat --remote-name=echo_client run echo_client_cpp.cmx |
| ## |
| ## # run echo_client and monitor echo_server. |
| ## fx fidlcat --remote-name=echo_server run echo_client_cpp.cmx |
| ## |
| ## # run echo_client and monitor echo_client and echo_server. |
| ## fx fidlcat --remote-name=echo run echo_client_cpp.cmx |
| ## |
| ## # run echo_client and monitor echo_client and echo_server. |
| ## fx fidlcat --remote-name=echo_client --remote-name=echo_server run echo_client_cpp.cmx |
| |
| source "$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"/../lib/vars.sh || exit $? |
| fx-config-read |
| source "$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"/lib/debug-agent.sh || exit $? |
| source "$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"/lib/symbol-index.sh || exit $? |
| |
| launch_agent=1 |
| |
| action= |
| |
| arguments=() |
| |
| use_gdb=0 |
| |
| # Options for the zxdb client. |
| agent_out="/dev/null" |
| debug_mode= |
| |
| while [[ $# -gt 0 ]]; do |
| case "$1" in |
| --help|-h) |
| fx-command-help |
| exit 0 |
| ;; |
| --port|-p) |
| shift |
| port="$1" |
| ;; |
| --with-symbol-server) |
| arguments+=("--symbol-server") |
| arguments+=("gs://fuchsia-artifacts-release/debug") |
| ;; |
| --debug-mode) |
| agent_out="/dev/stdout" |
| debug_mode="--debug-mode" |
| ;; |
| --symbol-path=*) |
| arguments+=("$1") |
| ;; |
| --fidl-ir-path=*) |
| arguments+=("$1") |
| ;; |
| --gdb) |
| use_gdb=1 |
| ;; |
| --from=device) |
| arguments+=("$1") |
| ;; |
| --from=*) |
| arguments+=("$1") |
| launch_agent=0 |
| ;; |
| --to=*) |
| arguments+=("$1") |
| ;; |
| --format=) |
| arguments+=("--format=none") |
| ;; |
| --format=*) |
| arguments+=("$1") |
| ;; |
| --with=*) |
| arguments+=("$1") |
| ;; |
| --with-process-info) |
| arguments+=("--with-process-info") |
| ;; |
| --stack=*) |
| arguments+=("$1") |
| ;; |
| --syscalls=*) |
| arguments+=("$1") |
| ;; |
| --exclude-syscalls=*) |
| arguments+=("$1") |
| ;; |
| --messages=*) |
| arguments+=("$1") |
| ;; |
| --exclude-messages=*) |
| arguments+=("$1") |
| ;; |
| --trigger=*) |
| arguments+=("$1") |
| ;; |
| --dump-messages) |
| arguments+=("--dump-messages") |
| ;; |
| --verbose=*) |
| arguments+=("$1") |
| ;; |
| --quiet=*) |
| arguments+=("$1") |
| ;; |
| --log-file=*) |
| arguments+=("$1") |
| ;; |
| --remote-pid=*) |
| arguments+=("$1") |
| ;; |
| --remote-name=*) |
| arguments+=("$1") |
| ;; |
| --extra-name=*) |
| arguments+=("$1") |
| ;; |
| run) |
| action="$1" |
| shift |
| break # Remaining flags are passed to fidlcat, with processing below |
| ;; |
| --) |
| shift |
| break # Remaining flags are passed to fidlcat |
| ;; |
| *) |
| echo "Invalid flag $1" |
| exit 1 |
| esac |
| shift |
| done |
| |
| # Infer the package URL from a regex-specified name. |
| package_file="${FUCHSIA_BUILD_DIR}/component_index_metadata" |
| if [[ "${action}" == "run" ]]; then |
| component=$1 |
| components=() |
| all_pkgs="$(cat "${package_file}")" |
| if [[ -n "${all_pkgs}" ]]; then |
| for pkg in ${all_pkgs}; do |
| if [[ "${pkg}" =~ ${component} ]]; then |
| components+=("${pkg}") |
| fi |
| done |
| else |
| # If there aren't any packages in the component_index_metadata file, then |
| # assume the users know what they are doing. fidlcat should complain. |
| components+=("${component}") |
| fi |
| |
| if [[ ${#components[@]} = 0 ]]; then |
| fx-error "Package $component is not known to the current build configuration." |
| fx-error "Check \`fx list-packages\` for the correct name," |
| fx-error "or adjust the build configuration with \`fx set\`." |
| exit 1 |
| elif [[ ${#components[@]} -gt 1 ]]; then |
| fx-error "Ambiguous match: $component matches the following ${#components[@]} packages:" |
| for component in "${components[@]}"; do |
| fx-error " $component" |
| done |
| exit 1 |
| fi |
| component="${components[0]}" |
| shift |
| # We have now removed "run <partial component URL regex>" from the remaining |
| # positional parameters. The following set command replaces them with "run |
| # <full component URL>". |
| set - "$@" "run" "${component}" |
| fi |
| |
| if [[ -z "${port}" ]]; then |
| port=2345 |
| fi |
| |
| ensure-symbol-index-registered || echo "Failed to register ${FUCHSIA_DIR} in symbol-index!" |
| |
| if [[ ${launch_agent} -eq 1 ]]; then |
| if launch_debug_agent "${port}" "" "${agent_out}"; then |
| arguments+=("--connect" "$(get-device-addr-resource):${port}") |
| arguments+=("--fidl-ir-path" @"${FUCHSIA_BUILD_DIR}"/all_fidl_json.txt) |
| arguments+=("$@") |
| |
| if [[ ${use_gdb} -eq 1 ]]; then |
| # Starts gdb. |
| gdb --args ${FUCHSIA_BUILD_DIR}/host_x64/exe.unstripped/fidlcat ${arguments[@]} |
| else |
| # Now that the debug agent is launched, starts fidlcat. |
| "${FUCHSIA_BUILD_DIR}/host-tools/fidlcat" ${arguments[@]} |
| fi |
| |
| # launch_debug_agent starts an agent in the background. Note: killing |
| # the ssh session as below generally won't terminate the agent, but |
| # it prevents us ending up with a zobmie on the host. |
| pids=$(jobs -p) |
| if [[ -n "${pids}" ]]; then |
| kill "${pids}" > /dev/null >&2 |
| wait |
| fi |
| else |
| fx-error "Could not launch debug agent. Exiting. Make sure you're running 'fx serve'." |
| exit 1 |
| fi |
| else |
| arguments+=("--fidl-ir-path" @"${FUCHSIA_BUILD_DIR}"/all_fidl_json.txt) |
| arguments+=("$@") |
| |
| if [[ ${use_gdb} -eq 1 ]]; then |
| # Starts gdb. |
| gdb --args ${FUCHSIA_BUILD_DIR}/host_x64/exe.unstripped/fidlcat ${arguments[@]} |
| else |
| # Now that the debug agent is launched, starts fidlcat. |
| "${FUCHSIA_BUILD_DIR}/host-tools/fidlcat" ${arguments[@]} |
| fi |
| fi |
