oxidecomputer / oxidecomputer/humility

humility ringbuf should have parseable output

Open
#465 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
584
Forks
63
Avg merge
3h
Merged PRs (30d)
2

Description

The humility ringbuf command prints a log of essentially human-readable ring buffer records; e.g.,

humility: ring buffer drv_gimlet_seq_server::__RINGBUF in gimlet_seq:
 NDX LINE      GEN    COUNT PAYLOAD
  13 1222        1        1 V3P3SysA0VOut(Volts(0.15234375))
  14  373        1        1 A2
  15  535        1        1 SpdDimmsFound(0x10)
  16  648        1        1 SetState(A2, A0, 0x710)
  17 1222        1        1 V3P3SysA0VOut(Volts(0.06640625))
  18  652        1        1 PGStatus { b_pg: 0x0, c_pg: 0x0, nic: 0x0 }
...

Sometimes we want to perform programmatic analysis on the ring buffer contents of a dump or live system. It would help to have a machine-readable version of this data. It could look something like this:

[
    {
        "task": "gimlet_seq",
        "name": "drv_gimlet_seq_server::__RINGBUF",
        "entries": [
             { "ndx": 13, "line": 1222, "gen": 1, "count": 1,
               "payload": {
                   "t": "V3P3SysA0VOut",
                   "v": {
                       "t": "Volts",
                       "v": 0.15234375
                   }
               }
             },
             { "ndx": 14, "line": 373, "gen": 1, "count": 1,
               "payload": {
                   "v": "A2"
               }
             }
        ]
    },
    {
        "task": "power",
        "name": "drv_i2c_devices::adm1272::__RINGBUF",
        "entries": [
            { "ndx": 0, "line": 106, "gen": 1, "count": 1,
              "payload": {
                 "t": "Config",
                 "v": {
                    "t": "CommandData",
                    "v": 16183
                 }
              }
            },
            { "ndx": 0, "line": 106, "gen": 1, "count": 1,
              "payload": {
                 "t": "WriteConfig",
                 "v": {
                    "t": "CommandData",
                    "v": 16191
                 }
              }
            }
        ]
    }
]

There are some more complex values in other ring buffers; e.g., Rx(UdpMetadata { addr: Ipv6(Ipv6Address([ 0xfe, 0x80, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0xaa, 0x40, 0x25, 0xff, 0xfe, 0x5, 0x26, 0x2 ])), port: 0xffd8, size: 0xa, vid: 0x302 }). I think it should, hopefully, still be easy enough to render these in some regular JSON form; e.g.,

{
    "t": "Rx",
    "v": {
        "t": "UdpMetadata",
        "v": {
            "addr": {
                "t": "Ipv6",
                "v": {
                    "t": "Ipv6Address",
                    "v": [ 254, 128, 0, 0, 0, 0, 0, 0,
                           170, 64, 37, 255, 254, 5, 38, 2 ]
                }
            },
            "port": 65496,
            "size": 10,
            "vid": 770
        }
    }
}

You could imagine also having some basic improved formats for things we can easily render like IPv6 addresses; e.g.,

{
    "t": "Rx",
    "v": {
        "t": "UdpMetadata",
        "v": {
            "addr": "fe80::aa40:25ff:fe05:2602",
            "port": 65496,
            "size": 10,
            "vid": 770
        }
    }
}

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the humility ringbuf command entry point and inspect how its human-readable records are assembled and formatted. Define a machine-readable output shape that covers the task, ring-buffer metadata, nested payloads, and complex values shown in the issue, then verify the command produces valid JSON matching those examples.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.