{"id":13819135,"url":"https://github.com/ARM-software/gator","last_synced_at":"2025-05-16T04:32:42.535Z","repository":{"id":23390846,"uuid":"26752594","full_name":"ARM-software/gator","owner":"ARM-software","description":"Sources for Arm Streamline's gator daemon, part of Arm Mobile Studio suite of performance analysis tools","archived":false,"fork":false,"pushed_at":"2024-07-16T08:28:15.000Z","size":4428,"stargazers_count":133,"open_issues_count":6,"forks_count":67,"subscribers_count":33,"default_branch":"main","last_synced_at":"2024-08-05T08:07:47.079Z","etag":null,"topics":["android","arm","arm64","game-development","linux","performance","performance-analysis","profiling"],"latest_commit_sha":null,"homepage":"https://www.arm.com/products/development-tools/graphics/arm-mobile-studio","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ARM-software.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"Contributing.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-11-17T10:55:26.000Z","updated_at":"2024-07-16T08:28:17.000Z","dependencies_parsed_at":"2024-01-13T16:20:43.619Z","dependency_job_id":"3addb3c7-586d-4385-9af4-5ae20af08e32","html_url":"https://github.com/ARM-software/gator","commit_stats":{"total_commits":87,"total_committers":13,"mean_commits":"6.6923076923076925","dds":0.6091954022988506,"last_synced_commit":"c44388e517e40edca6a2ac9a8f4d0a0ca596ffd1"},"previous_names":[],"tags_count":59,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARM-software%2Fgator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARM-software%2Fgator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARM-software%2Fgator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARM-software%2Fgator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ARM-software","download_url":"https://codeload.github.com/ARM-software/gator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225405541,"owners_count":17469366,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","arm","arm64","game-development","linux","performance","performance-analysis","profiling"],"created_at":"2024-08-04T08:00:40.917Z","updated_at":"2024-11-19T18:31:16.880Z","avatar_url":"https://github.com/ARM-software.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"# Gator daemon, barman embedded agent, and related tools\n\nThe source code for `barman`, `gatord`, and related tools.\n\nThe `barman` subdirectory contains the sources for the barman embedded agent which\ncan be used to collect performance data within an embedded environment as per the\n[Arm Streamline Target Setup Guide for Bare-metal Applications].\n\nThe rest of this document refers to `gatord` and related tools.\n\n## License\n\n* `daemon`, and `notify` are provided under GPL-2.0-only. See\n  [daemon/COPYING], and [notify/COPYING] respectively.\n* `annotate`, `barman` and `streamline_me.py` are provided under the BSD-3-Clause\n  license. See [annotate/LICENSE].\n\nThis project contains code from other projects listed below. The original license\ntext is included in those source files.\n\n* `libsensors` source code in [daemon/libsensors] licensed under LGPL-2.1-or-later\n* `perf_event.h` from Linux userspace kernel headers in [daemon/k] licensed\n  under GPL-2.0-only WITH Linux-syscall-note\n\nThe pre-built `gatord` shipped with Streamline uses [musl]. For musl license\ninformation see the COPYRIGHT file shipped with Streamline, or\n\u003chttps://git.musl-libc.org/cgit/musl/tree/COPYRIGHT\u003e\n\n## Contributing\n\nContributions are accepted under the same license as the associated subproject with\ndeveloper sign-off as described in [Contributing].\n\n## Purpose\n\nInstructions on setting up Arm Streamline on the target.\n\nA target agent (gator) is required to run on the Arm Linux target in order for Arm\nStreamline to operate. Gator requires Linux kernel version 3.4 or later.\n\n## Introduction\n\nA Linux development environment with cross compiling tools is most likely required,\ndepending on what is already created and provided.\n\nPlease see [release notes] for information about changes in this release.\n\n## Kernel configuration\n\nGator uses the Linux Perf API (perf_event_open) for most of its data collection.\nAdditionally it will use ftrace tracepoints and some other common features such as\ndebugfs/sysfs.\n\nMost users will not need to make any changes to their kernel configuration (and in\nmany cases they cannot) as most recent Android devices and Linux distributions\ncorrectly configure their kernel with the required options.\n\nIf you are a system integrator, or compiling your own kernel, refer to the section\n[Kernel configuration options].\n\n## Use the pre-built gator daemon\n\nStreamline provides pre-built binaries for aarch64 and armv7a-hardfloat Linux and Android.\nThis gator daemon should work in most cases so building the gator daemon is\nonly required if a non-standard configuration is required.\n\nTo improve portablility gatord is statically compiled against musl libc from\nhttp://www.musl-libc.org/download.html instead of glibc. The gator daemon will work\ncorrectly with either glibc or musl.\n\n## Building the gator daemon\n\nBuilding gatord has the following requirements:\n\n- C++17 supporting compiler.\n- CMake (3.16 or later).\n- GCC or Clang compiler able to target the appropriate target architecture.\n- GCC or Clang compiler able to target the host architecture if cross compiling.\n- For Android, the Android NDK (LTS r21e, r23b are tested and known to work).\n- A Linux build environment (other CMake compatible enironments may work but are not\n  tested).\n- Additionally, vcpkg depends on various unix tools being installed.\n-- A minimal build environment for linux can be achieved on Ubuntu 20.04\n   with: `sudo apt-get install ninja-build cmake gcc g++ g++-aarch64-linux-gnu curl zip unzip tar pkg-config git`\n\n### For Android targets\n\nThe most convenient option is to use the provided `build-android.sh` script.\n\n```\n./build-android.sh -h\n```\n\nPrints a summary of the available configuration options.\n\nIn most cases it should be possible to run:\n\n```\n./build-android.sh\n```\n\nwhich will compile gatord for Android targetting aarch64 devices.\n\nUsing the configuration options, it is possible to change the minimum SDK level,\narchitecture, CMake binary to use, CMake generator, build directory, NDK path.\n\n### For Linux targets\n\nFor simple configurations, the most convenient option is to use the provided\n`build-linux.sh` script. This allows selection of one of a few predefined configurations:\n\n * Building using the host native Clang toolchain.\n * Building using the host native GCC toolchain.\n * Building using GCC targetting aarch64 or armv7a against the glibc or musl based libc.\n\n```\n./build-linux.sh -h\n```\n\nPrints a summary of the available configuration options.\n\nWhen natively compiling it should be possible to run:\n\n```\n./build-linux.sh\n```\n\nOtherwise the typical use is to pass a profile option using `-p`.\n\n### Running CMake manually\n\nSince the build is CMake based, it is possible to invoke cmake directly.\nThis option requires some understanding of [vcpkg] and [cmake] tools.\n\nPlease note, the section on [telemetry that vcpkg collects by default]. The provided\n`build-android.sh` and `build-linux.sh` scripts disable this by default.\n\nIt is possible to build with out using [vcpkg] at all, by passing `-DENABLE_VCPKG=OFF`\nto the cmake build, *but* it will be necessary to provide precompiled versions of\nany dependencies.\n\n## Running gator\n\n### As a root user\n\n- Copy gatord into the target's filesystem.\n- Ensure gatord has execute permissions:\n  `chmod +x gatord`\n- The daemon must be run with root privileges:\n  `sudo su`\n  `gatord \u0026`\n\nThis configuration requires Linux 3.4 or later with a correctly configured kernel.\n\n### As a non-root user\n\n- Copy gatord into the target's filesystem.\n- Ensure gatord has execute permissions:\n  `chmod +x gatord`\n- Run the daemon:\n  `./gatord \u0026`\n\nThis configuration provides a reduced set of software only CPU counters such as\nCPU utilization and process statistics, as well as Mali hardware counters on\nsupported Mali platforms.\n\n## Perf PMU support\n\nTo check the perf PMUs support by your kernel, run\n`ls /sys/bus/event_source/devices/`\nIf you see something like `ARMv7_Cortex_A##` this indicates A## support. If you\nsee `CCI_400` this indicates CCI-400 support. If you see `ccn`, it indicates\nCCN support.\n\n## CCN\n\nCCN requires a perf driver to work. The necessary perf driver has been merged into\nLinux 3.17 but can be backported to previous versions (see\nhttps://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/diff/?id=a33b0daab73a0e08cc04459dd44b0121a8e8f81b\nand later bugfixes)\n\n## Compiling an application or shared library\n\nRecommended compiler settings:\n- `-g`: Debug information, such as line numbers, needed for best analysis results.\n- `-fno-inline`: Speed improvement when processing the image files and most\n  accurate analysis results.\n- `-fno-omit-frame-pointer`: Arm EABI frame pointers allow recording of the\n  call stack with each sample taken when in Arm state (i.e. not `-mthumb`).\n- `-marm`: This option is required for ARMv7 and earlier if your compiler is\n  configured with `--with-mode=thumb`, otherwise call stack unwinding will not\n  work.\n\nFor Android ART, passing `--no-strip-symbols` to dex2oat will result in\nfunction names but not line numbers to be included in the dex files. This can be\ndone by running `setprop dalvik.vm.dex2oat-flags --no-strip-symbols`\non the device and then regenerating the dex files.\n\n## Polling /dev, /sys and /proc files\n\nGator supports reading arbitrary `/dev`, `/sys` and `/proc` files 10 times a\nsecond. It will either interpret the file contents as a number or use a POSIX\nextended regex to extract the number, see `events-Filesystem.xml` for\nexamples.\n\n## Kernel configuration options\n\nThe following options are required for correct functioning of Gator.\n\nmenuconfig options (depending on the kernel version, the location of these\nconfiguration settings within menuconfig may differ)\n\n- General Setup\n  - Timers subsystem\n    - [*] High Resolution Timer Support (enables CONFIG_HIGH_RES_TIMERS)\n  - Kernel Performance Events And Counters\n    - [*] Kernel performance events and counters (enables CONFIG_PERF_EVENTS)\n  - [*] Profiling Support (enables CONFIG_PROFILING)\n- Kernel Features\n  - [*] Use local timer interrupts (only required for SMP and for version before Linux 3.12, enables CONFIG_LOCAL_TIMERS)\n  - [*] Enable hardware performance counter support for perf events (enables CONFIG_HW_PERF_EVENTS)\n- CPU Power Management\n  - CPU Frequency scaling\n    - [*] CPU Frequency scaling (enables CONFIG_CPU_FREQ)\n- Kernel hacking\n  - [*] Compile the kernel with debug info (optional, enables CONFIG_DEBUG_INFO)\n  - [*] Tracers\n    - [*] Trace process context switches and events (#)\n\n(#) The \"Trace process context switches and events\" is not the only option that enables tracing (CONFIG_GENERIC_TRACER or CONFIG_TRACING as well as CONFIG_CONTEXT_SWITCH_TRACER) and may not be visible in menuconfig as an option if other trace configurations are enabled. Other trace configurations being enabled is sufficient to turn on tracing.\n\nThe configuration options:\n- CONFIG_MODULES and MODULE_UNLOAD (not needed if the gator driver is built into the kernel)\n- CONFIG_GENERIC_TRACER or CONFIG_TRACING\n- CONFIG_CONTEXT_SWITCH_TRACER\n- CONFIG_PROFILING\n- CONFIG_HIGH_RES_TIMERS\n- CONFIG_LOCAL_TIMERS (for SMP systems and kernel versions before 3.12)\n- CONFIG_PERF_EVENTS and CONFIG_HW_PERF_EVENTS (kernel versions 3.0 and greater)\n- CONFIG_DEBUG_INFO (optional, used for analyzing the kernel)\n- CONFIG_CPU_FREQ (optional, provides frequency setting of the CPU)\n\nThese may be verified on a running system using `/proc/config.gz`\n(if this file exists) by running `zcat /proc/config.gz | grep \u003coption\u003e`.\nFor example, confirming that CONFIG_PROFILING is enabled\n```\n\u003e zcat /proc/config.gz | grep CONFIG_PROFILING\nCONFIG_PROFILING=y\n```\n\nIf a device tree is used it must include the pmu bindings, see\nDocumentation/devicetree/bindings/arm/pmu.txt for details.\n\n## Bugs\n\nKernels with `CONFIG_CPU_PM` enabled may produce invalid results on kernel\nversions prior to 4.6. The problem manifests as counters not showing any data, large\nspikes and non-sensible values for counters (e.g. Cycle Counter reading as *very*\nhigh).\nThis issue stems from the fact that the kernel PMU driver does not save/restore\nstate when the CPU is powered down/up. This issue is fixed in 4.6 so to resolve the\nissue either upgrade to a later kernel, or apply the fix to an older kernel.\nThe patch for 4.6 that resolves the issue is found here\nhttps://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=da4e4f18afe0f3729d68f3785c5802f786d36e34 -\nthis patch has been tested as applying cleanly to 4.4 kernel and it may be\npossible to back port it to other versions as well.\nUsers of this patch may also need to apply\nhttps://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=cbcc72e037b8a3eb1fad3c1ae22021df21c97a51\nas well.\n\nThere is a bug in some Linux kernels where an Oops may occur when a core is\nofflined (user space gator only). The fix was merged into mainline in 3.14-rc5, see\nhttp://git.kernel.org/tip/e3703f8cdfcf39c25c4338c3ad8e68891cca3731, and has been\nbackported to older kernels (3.4.83, 3.10.33, 3.12.14 and 3.13.6).\n\n`CPU PMU: CPUx reading wrong counter -1` in dmesg. To work around,\nupdate to the latest Linux kernel.\n\nScheduler switch resolutions are on exact millisecond boundaries.\nTo work around, update to the latest Linux kernel.\n\nThere is a bug in some Linux kernels where perf misidentifies the CPU type. To see\nif you are affected by this, run` ls /sys/bus/event_source/devices/` and\nverify the listed processor type matches what is expected. For example, an A9 should\nshow the following.\n```\n# ls /sys/bus/event_source/devices/\nARMv7_Cortex_A9  breakpoint  software  tracepoint\n```\nTo work around the issue try upgrading to a later kernel.\n\nOn some versions of Android, annotations may not work unless SELinux is disabled by\nrunning\n`# setenforce 0`\n\nSome targets do not correctly emit uevents when cores go on/offline. This will cause\nCPU Activity with user space gator to be either 0% or 100% on a given core and the\nHeat Map may show a large number of unresolved processes. There is no user accessible\nworkaround. To test for this run\n`# ./gatord -d | grep uevent`\nWhen cores go on/offline with user space gator something similar to the following\nshould be emitted\n```\nINFO: read(UEvent.cpp:61): uevent: offline@/devices/system/cpu/cpu1\nINFO: read(UEvent.cpp:61): uevent: online@/devices/system/cpu/cpu1\n```\nThe cores that are on/offline can be checked by running\n`# cat /sys/devices/system/cpu/cpu*/online`\nThis issue affects a given target if the on/offline cores shown by the cat command\nchange but no cpu uevent is emitted.\n\nOn some older versions of Android, the following issue may occur when starting\ngatord when using ndk-build\n```\n# ./gatord\n[1] + Stopped (signal)        ./gatord\n#\n[1]   Segmentation fault      ./gatord\n#\n```\nStarting with Android-L only position independent executables (pie) are supported,\nbut some older versions of Android do not support them. To avoid this issue, modify\nAndroid.mk and remove the references to pie.\n\n## Profiling the kernel (optional)\n\nCONFIG_DEBUG_INFO must be enabled, see \"Kernel configuration\" section above.\n\nUse vmlinux as the image for debug symbols in Streamline.\n\nDrivers may be profiled using this method by statically linking the driver into the\nkernel image or adding the driver as an image to Streamline.\n\n[Arm Streamline Target Setup Guide for Bare-metal Applications]: https://developer.arm.com/documentation/101815/latest\n[Contributing]: Contributing.md\n[annotate/LICENSE]: annotate/LICENSE\n[cmake]: https://cmake.org/\n[daemon/COPYING]: daemon/COPYING\n[daemon/k]: daemon/k\n[daemon/libsensors]: daemon/libsensors\n[daemon/mxml]: daemon/mxml\n[musl]: http://www.musl-libc.org/download.html\n[notify/COPYING]: notify/COPYING\n[release notes]: release-notes.md\n[vcpkg]: https://github.com/microsoft/vcpkg\n[telemetry that vcpkg collects by default]: https://github.com/microsoft/vcpkg#telemetry\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FARM-software%2Fgator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FARM-software%2Fgator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FARM-software%2Fgator/lists"}