百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
H

humility

> 编程语言
开源

Hubris 调试器

585 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

Hubris 调试器

Humility

Humility is the debugger for Hubris.

Guiding principles

Production disposition

Hubris is the artifact that actually runs, and it must be allowed to be optimized in terms of size, space, and run-time; in as much as contortions are required for debuggability, they should be borne by Humility, not Hubris. As a concrete example of this, Humility operates exclusively on release builds of Hubris, relying on (unloaded) DWARF information in the binaries to make sense of the system.

Hubris-specific

Humility is Hubris-specific: it is not trying to be a generic in situ debugger, but rather specifically focused on debugging Hubris-based systems. Humility is therefore willing to encode Hubris-specific concepts like archives and tasks.

Microcontroller-specific

Debuggers must cut through abstractions, which often requires knowledge of underlying implementation detail. For Humility, this means being willing to take advantage of microcontroller-specific debug facilities where applicable. While Hubris may make decisions in the name of greater portability, Humility will generally make decisions to maximize debuggability, even where these facilities are highly specific to a particular MCU.

Device-specific

Humility is unafraid to offer device-specific functionality where that functionality is useful for system debuggability. (For example, humility i2c functions as an I2C analyzer.) That said, all device interaction uses Hubris as a proxy to actually communicate with the devices themselves (e.g., HIF); Humility does not seek to create second I/O path.

Pragmatic

Humility seeks to be useful, and therefore seeks to offer all manners of debugging: in situ, postmortem, dynamic instrumentation, static instrumentation, etc.

Operation

Humility operates by specifying a subcommand. There are options that are Humility-wide (that is, applying to every subcommand), as well as options that are specific to particular subcommands.

Probe

Humility needs to have some way of extracting information and/or controlling the microcontroller running Hubris. This is done through some variant of a debug probe, a separate microcontroller that speaks to debug-specific functionality on the target microcontroller.

For most evaluation boards, this debug probe is available on the board, and is connected to a host via USB, e.g. ST's STLink/V2 on the STM32F407 Discovery or the LPC-Link2 present on the LPCXpresso55S69. (On the Gemini board, there are two SWD headers, one for the LPC55S28 and the other for the STM32H753.)

While Humility allows for direct attachment to an on-chip debugger, doing so precludes other connections (from, for example, OpenOCD), making it too disruptive to development workflows. To allow for easier development workflows, Humility also has the option to attach via OpenOCD.

The debug probe to use is specified to Humility via the -p option (long form --probe) or the HUMILITY_PROBE environment variable, which can have the following values:

  • auto (default): Automatically determine how to attach to the microcontroller. If there is no probe found, this will default to archive.

  • usb: Attach directly via USB to a debug probe. When multiple probes are plugged in via USB, a probe index must be specified as a suffix (e.g., usb-0, usb-1, etc.) To determine which probe is which, examine the serial number in the output of humility probe.

  • vid:pid[:serial]: In some cases, the automatic algorithm may either find the wrong thing, or timeout attempting to search for non-existent probes. In these cases, it can help to explicitly set the vendor ID (VID) and product ID (PID) of the debug probe, which should be colon-delimited, e.g., 0483:374e. (Determining the VID and PID of an attached probe is platform-specific; on Linux one can use the lsusb command.) In cases where there are multiple probes with the same VID and PID, the serial number of the probe (as reported via humility probe or found in the iSerialNumber field of the USB device descriptor) can be postpended, also delimited by a colon, e.g. 0483:374e:004000343137510939383538.

  • ocd: Attach via OpenOCD, which is presumed to have the TCL interface available on localhost on port 6666 (its default).

  • jlink: Attach via Segger JLink, which is presumed to have the GDB interface available on localhost on port 2331 (its default). Note that when semihosting is being used by Hubris, the Segger JLink GDB server will become confused when Humility attaches to it -- and subsequent calls to semihosting will cause a halt. A subsequent Humility invocation will resume the target (directing semihosting output correctly to the running GDB instance), but subsequent semihosting output will again cause a halt. To recover from this condition, send an explicit ^C to the running GDB and continue from the resulting stop.

  • archive: Do not attach to a probe at all, but rather use the specified Hubris archive as the target. Those commands that operate only by reading flash (e.g., humility map) can operate in this mode, but those that operate by reading RAM (e.g., humility tasks) will fail. Commands that operate on either (e.g., humility readmem or humility readvar) will succeed or fail depending on their input.

Archive

Many Humility commands require the complete Hubris archive. This is a ZIP archive created by the build process, and includes all binaries as well as the app.toml file used to configure the Hubris archive. The archive can be found in the target for Hubris, and will end with (.zip), e.g.: /path/to/hurbis/target/demo-stm32h753-nucleo/dist/default/build-demo-stm32h753-nucleo.zip. The Hubris archive is specified via the -a option or the HUMILITY_ARCHIVE environment variable.

In the Humility examples in this documentation, unless otherwise specified, the archive will be assumed to be set via -a or HUMILITY_ARCHIVE.

Dump

Many Humility commands are able to operate postmortem on a Hubris dump, an ELF core file generated by the humility dump command. Dumps are offered in lieu of a probe and an archive and specified via the -d option (long form --dump) or the HUMILITY_DUMP environment variable.

Network

On Hubris systems that are so equipped, Humility can operate over a network in lieu of a dump or probe. When operating over a network, the archive must always be provided via -a, as well as the IP address of the target via -i (long form --ip) or the HUMILITY_IP environment variable. Note that not all commands can operate over the network, including (but not limited to) any command that stops the target or reads memory directly.

Environment

On machines that have several different connected Hubris targets, Humility can become thorny to manage. To aid this, Humility allows for environments: JSON files that define how targets can be reached and auxiliary operations that can be performed upon them. The environment file is specified via either the --environment argument or via the HUMILITY_ENVIRONMENT environment variable; a specific target within the environment is specified via the --target argument or via the HUMILITY_TARGET environment variable.

Environment file structure

The environment file contains a JSON object in which each key represents a target. The members of each target object must include probe and archive, which have the same meaning as the probe and archive as provided via the command line. For example:

json
{
    "lucky": {
        "probe": "0483:374e:002A00174741500520383733",
        "archive": "/gimlet/hubris/archives/lucky/build-gimlet.zip"
    },
    "sweaty": {
        "probe": "0483:374e:000D00184741500520383733",
        "archive": "/gimlet/hubris/archives/sweaty/build-gimlet.zip"
    },
    "grimey": {
        "probe": "0483:374e:003400185553500820393256",
        "archive": "/gimlet/hubris/archives/grimey/build-gimlet.zip"
    }
}

Some targets may require multiple archives. These can be specified by name. The archive to be used must be specified with the --archive-name option to humility.

json
{
    "lucky": {
        "probe": "0483:374e:002A00174741500520383733",
        "archive": {
            imagea: "/gimlet/hubris/archives/lucky/build-a-gimlet.zip",
            imageb: "/gimlet/hubris/archives/lucky/build-b-gimlet.zip"
        }
    },
}

The above definition -- when provided via --environment or HUMILITY_ENVIRONMENT -- would allow one to (say) run humility --target grimey tasks or humility --target lucky --image-name imagea tasks. In addition to probe and archive, one may also specify associated commands in a cmds object that contains a mapping of names to commands to execute. For example:

json
{
    "grimey": {
        "probe": "0483:374e:003400185553500820393256",
        "archive": "/gimlet/hubris/archives/grimey/build-gimlet.zip"
        "cmds": {
            "console": "/bin/sh -c \"grabserial.sh $(findtty.sh grimey)\"",
            "power": {
                "on": "power.sh --on grimey",
                "off": "power.sh --off grimey",
                "status": "power.sh --status grimey",
            }
        }
    }
}

These commands can be in principle accessed by any debugging command, but the humility exec command in particular allows one to execute a command against a specified target. (In the above example, one could execute humility --target grimey exec power.on.)

Commands

  • humility auxflash: manipulate auxiliary flash
  • humility caboose: read from the caboose
  • humility console-proxy: SP/host console uart proxy
  • humility counters: display event counters
  • humility dashboard: dashboard for Hubris sensor data
  • humility debugmailbox: interact with the debug mailbox on the LPC55
  • humility diagnose: analyze a system to detect common problems
  • humility discover: listen for compatible SPs on a network
  • humility doc: print command documentation
  • humility dump: generate Hubris dump
  • humility ereport: ereport examination
  • humility exec: execute command within context of an environment
  • humility extract: extract all or part of a Hubris archive
  • humility flash: flash archive onto attached device
  • humility gimlet: Gimlet-specific diagnostic commands
  • humility gpio: GPIO pin manipulation
  • humility hash: Access to the HASH block
  • humility hiffy: manipulate HIF execution
  • humility host: Pretty-printing of host state
  • humility hydrate: Rehydrate a bare memory dump
  • humility i2c: scan for and read I2C devices
  • humility ibc: interface to the BMR491 power regulator
  • humility jefe: influence jefe externally
  • humility lpc55gpio: LPC55 GPIO pin manipulation
  • humility lsusb: List all USB devices visible to Humility
  • humility manifest: print archive manifest
  • humility map: print memory map, with association of regions to tasks
  • humility monorail: Management network control and debugging
  • humility mwocp: Murata power shelf operations
  • humility net: Management network device-side control and debugging
  • humility pmbus: scan for and read PMBus devices
  • humility power: show power-related information
  • humility powershelf: inspect powershelf over the management network

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Rust

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言