Hubris 调试器
Humility is the debugger for Hubris.
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.
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.
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.
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.
Humility seeks to be useful, and therefore seeks to offer all manners of debugging: in situ, postmortem, dynamic instrumentation, static instrumentation, etc.
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.
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.
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.
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.
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.
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.
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:
{
"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.
{
"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:
{
"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.)
暂无开放 Issues,或尚未同步最近议题。