counters: add --ipcs command for showing IPC counters by interface

README.md

@@ -382,6 +382,146 @@ thermal
            6 FanAdded
 ```
 
+##### IPC counters
+
+The `--ipc` argument shows IPC client counters generated automatically by
+`idol`, showing the total request count for a given IPC and per-client-task
+breakdowns. For example:`
+
+```console
+$ humility -d ./hubris.core.0 counters --ipc`
+humility: attached to dump
+drv_gimlet_hf_api::__HOSTFLASH_CLIENT_COUNTERS
+ fn HostFlash::get_mux() .............................................. 6 calls
+    clients:
+    task host_sp_comms (0 restarts) .................... = 0 ........... = 6 ok
+
+ fn HostFlash::set_mux() .............................................. 2 calls
+    clients:
+    task gimlet_seq (0 restarts) ....................... + 0 ........... + 1 ok
+    task host_sp_comms (0 restarts) .................... + 0 ........... + 1 ok
+                                                         ---             ---
+    totals:                                              = 0 err         = 2 ok
+
+ fn HostFlash::get_dev() .............................................. 1 calls
+    clients:
+    task host_sp_comms (0 restarts) .................... = 0 ........... = 1 ok
+
+
+drv_gimlet_seq_api::__SEQUENCER_CLIENT_COUNTERS
+ fn Sequencer::get_state() ......................................... 2017 calls
+    clients:
+    task thermal (0 restarts) .......................... + 0 ........ + 1386 ok
+    task power (0 restarts) ............................ + 0 ......... + 626 ok
+    task host_sp_comms (0 restarts) .................... + 0 ........... + 5 ok
+                                                         ---          ------
+    totals:                                              = 0 err      = 2017 ok
+...
+```
+
+When displaying counters by IPC, substring filtering is performed on the
+counters variable, but *not* on the client task name. This allows filtering
+the output based on the IPC interface. For example:
+
+```console
+$ humility -d ./hubris.core.0 counters --ipc sensors
+humility: attached to dump
+task_sensor_api::__SENSOR_CLIENT_COUNTERS
+fn Sensor::post() ................................................ 76717 calls
+   clients:
+   task power (0 restarts) ............................ + 0 ....... + 50300 ok
+   task thermal (0 restarts) .......................... + 0 ....... + 26417 ok
+                                                        ---         -------
+   totals:                                              = 0 err     = 76717 ok
+
+fn Sensor::get_reading() ......................................... 19804 calls
+   clients:
+   task thermal (0 restarts) ...................................... = 18101 ok
+   - Err(NotPresent) ............................... + 1701 ..................
+   - Err(DeviceError) ................................. + 2 ..................
+                                                     ------         -------
+   totals:                                           = 1703 err     = 18101 ok
+
+fn Sensor::nodata() ............................................... 6225 calls
+   clients:
+   task power (0 restarts) ............................ + 0 ........ + 3536 ok
+   task thermal (0 restarts) .......................... + 0 ........ + 2689 ok
+                                                        ---          ------
+   totals:                                              = 0 err      = 6225 ok
+
+```
+
+Instead, to show only the IPC counters _recorded_ by specific client tasks,
+use the `--client` argument, which will filter the output counters to those
+recorded in tasks whose names match the provided strings. For example, to
+show only IPC counters recorded by the `gimlet_seq` task, use:
+
+```console
+$ humility -d ./hubris.core.0 counters --ipc --client gimlet_seq
+humility: attached to dump
+drv_gimlet_hf_api::__HOSTFLASH_CLIENT_COUNTERS
+ fn HostFlash::set_mux() .............................................. 1 calls
+    clients:
+    task gimlet_seq (0 restarts) ....................... = 0 ........... = 1 ok
+
+
+drv_spi_api::__SPI_CLIENT_COUNTERS
+ fn Spi::exchange() ............................................... 67580 calls
+    clients:
+    task gimlet_seq (0 restarts) ....................... = 0 ....... = 67580 ok
+
+ fn Spi::write() .................................................... 530 calls
+    clients:
+    task gimlet_seq (0 restarts) ....................... = 0 ......... = 530 ok
+
+ fn Spi::lock() ....................................................... 4 calls
+    clients:
+    task gimlet_seq (0 restarts) ....................... = 0 ........... = 4 ok
+
+ fn Spi::release() .................................................... 1 calls
+    clients:
+    task gimlet_seq (0 restarts) ....................... = 0 ........... = 1 ok
+
+
+drv_stm32xx_sys_api::__SYS_CLIENT_COUNTERS
+ fn Sys::gpio_read_input() ........................................ 16796 calls
+    clients:
+    task gimlet_seq (0 restarts) ....................... = 0 ....... = 16796 ok
+
+ fn Sys::gpio_set_reset() ............................................ 15 calls
+    clients:
+    task gimlet_seq (0 restarts) ....................... = 0 .......... = 15 ok
+
+ fn Sys::gpio_configure_raw() ........................................ 14 calls
+    clients:
+    task gimlet_seq (0 restarts) ....................... = 0 .......... = 14 ok
+
+
+task_jefe_api::__JEFE_CLIENT_COUNTERS
+ fn Jefe::set_state() ................................................. 5 calls
+    clients:
+    task gimlet_seq (0 restarts) ....................... = 0 ........... = 5 ok
+
+
+task_packrat_api::__PACKRAT_CLIENT_COUNTERS
+ fn Packrat::set_spd_eeprom() ........................................ 32 calls
+    clients:
+    task gimlet_seq (0 restarts) ....................... = 0 .......... = 32 ok
+
+ fn Packrat::set_mac_address_block() .................................. 1 calls
+    clients:
+    task gimlet_seq (0 restarts) ....................... = 0 ........... = 1 ok
+
+ fn Packrat::set_identity() ........................................... 1 calls
+    clients:
+    task gimlet_seq (0 restarts) ....................... = 0 ........... = 1 ok
+```
+
+Multiple `--client` arguments may be provided, to show IPCs from any of a
+set of client tasks.
+
+`--client` may be combined with a filter matching counter variable names, to
+show only the calls to specific IPC interfaces from specific tasks.
 
 
 ### `humility dashboard`

cmd/counters/Cargo.toml

@@ -6,7 +6,9 @@ description = "display event counters"
 
 [dependencies]
 anyhow = { workspace = true }
+colored = { workspace = true }
 clap = { workspace = true }
+indexmap = { workspace = true }
 
 humility = { workspace = true }
 humility-doppel = { workspace = true }