[Toybox] Proposal: Add ucsicontrol (USB Type-C UCSI utility) to toybox

M, Madhu madhu.m at intel.com
Thu Sep 3 16:34:04 UTC 2026


Hi Rob,

Thanks for the detailed review. I have addressed the points you raised in the latest ucsicontrol(ucsicontrol.patch) update.

The changes include:
Expanded the help text with a description of UCSI, the OPM/PPM relationship, connector status, PDOs, alternate modes, role swaps, and connector reset.
Removed the redundant --help entry from the command help.
Made the documented command names match the parser, using names such as get_capability, get_connector_status, and connector_reset.
Clarified that connector numbers are zero-based and that get_capability reports the available connector count.
Added a reference to the Intel UCSI specification:
https://www.intel.com/content/dam/www/public/us/en/documents/technical-specs/usb-type-c-connector-system-software-interface-spec.pdf
Removed redundant single-use constants and simplified the cable speed and cable type output.
Removed the access() checks before xopen(), allowing Toybox to report the failing path directly.
Added validation for the updated source and generated a patch with a change log.

The patch is included as ucsicontrol.patch, and the detailed change log is in UCSICONTROL_CHANGES.md.

Regarding the role swaps: a power role swap changes which side provides VBUS and which side consumes it. A data role swap changes which side acts as the USB host, DFP, or device, UFP. USB data is carried in both directions, but the host/device roles still determine enumeration and control responsibilities, so these are separate swaps.

I have tested and attached logs - ucsicontrol_cmd_logs.txt

Pls let me know further feedback!

Regards,
Madhu M

-----Original Message-----
From: Rob Landley <rob at landley.net> 
Sent: 30 August 2026 22:42
To: M, Madhu <madhu.m at intel.com>; toybox <toybox at lists.landley.net>
Subject: Re: [Toybox] Proposal: Add ucsicontrol (USB Type-C UCSI utility) to toybox

On 8/29/26 07:50, M, Madhu wrote:
> Hi Rob,
> 
> Thanks for the follow-up. Let me address both points in detail:

I did a couple of minor tweaks (commit c63fa170b468).

Seems like read_resp()/hex_to_int() are open coding readall() (from
lib/lib.c) and sscanf(), but I don't have an example of its input data...

I'm tempted to inline the #defined constants that only get used once
because:

   #define UCSI_CABLE_PASSIVE 0
   ...
   printf("  PassiveCable: %d\n", cable_type == UCSI_CABLE_PASSIVE);

vs
   printf("  PassiveCable: %d\n", cable_type == 0);

doesn't really seem to be adding anything? (If it came from a header that's one thing, but #defining something for ourselves...)

I expect this tool already has a defined format you're being compatible with, but why:

   printf("bmSpeedSupported: 0x%x\n", speed);
   printf("  Bits/s: %d\n", speed_unit == UCSI_CABLE_SPEED_BITS);
   printf("  Kb/s: %d\n", speed_unit == UCSI_CABLE_SPEED_KBPS);
   printf("  Mb/s: %d\n", speed_unit == UCSI_CABLE_SPEED_MBPS);
   printf("  Gb/s: %d\n", speed_unit == UCSI_CABLE_SPEED_GBPS);

Instead of just:

   printf("bmSpeedSupported: 0x%x %cb/s", speed, " KMG"[speed_unit]);

> 1. What is ucsicontrol?
> ucsicontrol is a user space command-line tool that talks to the kernel's UCSI (USB Type-C Connector System Software Interface) driver. It lets you query and control USB Type-C / USB Power Delivery (PD) state directly from the OS — without needing external hardware like a PD analyzer, oscilloscope, or Type-C breakout board.

Hmmm, I should fluff out the --help text with some of that info. (And you probably don't need a note about needing to be root if TOYFLAG_NEEDROOT will say "Not root" and exit if you try to run it as
non-root.)

Why is the --help text documenting --help (you successfully figured out how to invoke the help text to get here, and it's in toybox --help anyway because it's standard for all commands)...

Ah, you bypassed toybox's option parsing and are doing it all yourself, which is fine except --help and --version are parsed by main.c (you need TOYFLAG_NOHELP to disable that, or to switch off CONFIG_TOYBOX_HELP_DASHDASH in the global options section of menuconfig) so that shouldn't be a thing a command has to do itself...

(Yes I'm aware the standalone build isn't reliably enabling the --help text, it's a bug, it's on my todo list...)

> UCSI is defined in its own standalone specification — the "USB Type-C Connector System Software Interface (UCSI) Specification" published by Intel.

If there's a stable URL for it I'd like to put a "See https://blah" line right after the copyright notice in the source.

> It defines how the OS communicates with the platform's embedded PPM (Platform Policy Manager) — usually firmware in the EC or a PD controller chip. Each physical Type-C port is exposed as a connector, and each connector's PD controller is the LPM (Local Policy Manager).
> The tool operates in user space, communicating through debugfs interfaces with the kernel's OPM (Operating System Policy Manager), which in turn manages communication with the platform's PPM and underlying hardware controllers.
> 
> What you can inspect / do:
> Capability
> Description
> Capability
> Type-C port capabilities
> Connector status
> Whether a cable/device is attached, connected partner type Power role 
> Source (providing power) vs Sink (consuming) Data role DFP (host) vs 
> UFP (device) Orientation / plug flip Which CC line is active (CC1/CC2) 
> PDOs Advertised source/sink power profiles (voltage/current) RDO The 
> negotiated request (which PDO was selected, current level) Alternate 
> modes DisplayPort / Thunderbolt alt-mode SVIDs and status Cable info 
> Whether it's an e-marked cable, its capabilities

Probably good to fluff out the descriptions like that in the help text. 
(I didn't know what most of it did, and "--get_pdos  Get PDOS" isn't really adding information. Possibly it needs get/set sections the way "toybox --help grep" or "toybox --help ls" have help sections.)

> Role swap
> Trigger PR_SWAP (power) / DR_SWAP (data) in software

So... telling an on-the-go device to charge instead of discharge? (You know what roles getting swapped means, but I don't. Isn't data bidirectional already? You can swap power _without_ swapping who is a host and who is a gadget from a packet-sending perspective?)

> Reset
> Issue a connector/PPM reset to recover a stuck port
> 
> Typical commands:BASH
> ucsicontrol get-capability               # PPM capabilities
> ucsicontrol get-connector-capability 1   # Per-connector capability
> ucsicontrol get-connector-status 1       # Live status (attach, roles, orientation)
> ucsicontrol get-pdos 1                   # Advertised power profiles
> ucsicontrol get-alternate-modes 1        # Cable/partner alternate modes
> ucsicontrol set-uor 1 ...               # USB Operation Role swap
> ucsicontrol set-pdr 1 ...               # Power Direction Role swap
> ucsicontrol connector-reset 1           # Reset a stuck connector

The --help says those are --use_undercores names not unprefixed-dashes names.

It uses a lot of <conn_num> but doesn't say where you get that from, or how you figure out which connection (connector?) number corresponds to which device. (Is this from lsusb maybe?)

> 2. Power On/Off USB Port — Not Possible with ucsicontrol:
> I want to clarify that ucsicontrol cannot power on/off a USB port.

Alas. Oh well.

> It is specifically designed to interface with the UCSI layer, which manages Type-C connector state, USB Power Delivery (PD) negotiation, alternate modes, and connector/PPM resets. Power cycling a USB port (cutting VBUS to a connected device) is a hardware-level operation controlled by the platform's power management or a USB hub controller — not by UCSI. Tools like uhubctl are designed for that purpose on supported hardware.

https://github.com/mvp/uhubctl

Good to know, thanks.

> 3. Testing — Short-Term Approach (Real Hardware):
> ucsicontrol communicates via the kernel's UCSI debugfs interface, introduced in Linux kernel 6.5 (drivers/usb/typec/ucsi/debugfs.c). It allows direct injection and testing of UCSI commands from userspace.
> 
> 📝 Note: The latest Ubuntu and Android releases ship with Linux kernel 7.0, which includes full UCSI debugfs support. ucsicontrol has been completely tested and verified on both Ubuntu OS and Android OS, confirming it works reliably on these modern platforms out of the box.
> Prerequisites:
> 
>    *   Linux kernel ≥ 6.5 (latest Ubuntu and Android ship with kernel 7.0)

Hmmm... my laptop's kernel is too old. I should poke at the orange pi boards...

>    *   Kernel built with CONFIG_DEBUG_FS=y and CONFIG_TYPEC_UCSI=y
>    *   A system with a UCSI-capable Type-C controller (most modern Intel platforms with Thunderbolt/USB4 qualify)
> Steps to test on real hardware:
> BASH
> # 1. Check if debugfs is mounted
> mount | grep debugfs
> 
> # 2. If not mounted, mount it manually sudo mount -t debugfs none 
> /sys/kernel/debug

The reason I do xopen("/sys/kernel/debug/usb/ucsi", O_RDWR) instead of:

   char *base = "/sys/kernel/debug/usb/ucsi";
   char cmd_path[PATH_MAX] = {0}, resp_path[PATH_MAX] = {0};

   // The UCSI debugfs "command" and "response" files must both be present.
   if (find_ucsi_files(base, cmd_path, resp_path) ||
       access(cmd_path, F_OK) || access(resp_path, F_OK))
     error_exit("UCSI debugfs not present: no command/response file under %s",
       base);

Is that the error message would be

   ucsicontrol: /sys/kernel/debug/usb/ucsi: No such file or directory

Which lets you know where/what the problem is. (And doesn't need a temporary variable to hold the string so I can reuse it for the error
message: the function does it for me.)

Similarly, you're doing access() checks right before you do an xopen() which will complain with path if it can't...

(I'd be happy to change it all myself, but I'm afraid of breaking stuff I can't test. The above commit I did, objdump -d on the binary before/after were identical so I can't have broken anything.)

> # 3. Verify the UCSI debugfs interface is present ls 
> /sys/kernel/debug/usb/ucsi/ # Expected output: port1/ port2/ (one 
> directory per Type-C connector)
> 
> # 4. Run ucsicontrol commands
> ucsicontrol get-capability
> ucsicontrol get-connector-status 1
> ucsicontrol get-pdos 1

You can use that format of commands if you want, there's no need for the --longopts one if that's not what you're used to. (One of the advantages of the command still being in pending: no need to worry about compatibility with the existing version.)

Also... your command_main() isn't looping, it's only handling one input.

     Usage: ucsicontrol [OPTIONS]

That implies zero or more options. It looks like one option is mandatory (outputs help text otherwise, I would have thought it would list available devices you could run the other commands on), and if you give more than one option the rest seem to be silently ignored. (Handling only one is fine, but an error at the end if there's unhandled arguments might be good.)

I did another small tweak.

> The /sys/kernel/debug/usb/ucsi/ path must be present and mounted in the filesystem — it is exposed by the UCSI kernel driver and provides the raw UCSI command/response interface that ucsicontrol reads from and writes to.
> 
> 4. Long-Term / QEMU Testing:
> I'll investigate whether a virtual/dummy UCSI kernel module can be 
> created to simulate a UCSI PPM and expose the same debugfs interface under QEMU — this would be the ideal path for automated regression testing (make test_ucsicontrol). I'll update you once I have more concrete progress on this.

Thank you.

> Please let me know if you have any questions!
> 
> Regards, Madhu M

The above is what I had time for today.

Rob
-------------- next part --------------
A non-text attachment was scrubbed...
Name: ucsicontrol.patch
Type: application/octet-stream
Size: 16046 bytes
Desc: ucsicontrol.patch
URL: <http://lists.landley.net/pipermail/toybox/attachments/20260903/0fcc0335/attachment-0002.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: UCSICONTROL_CHANGES.md
Type: application/octet-stream
Size: 6269 bytes
Desc: UCSICONTROL_CHANGES.md
URL: <http://lists.landley.net/pipermail/toybox/attachments/20260903/0fcc0335/attachment-0003.obj>
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: ucsicontrol_cmd_logs.txt
URL: <http://lists.landley.net/pipermail/toybox/attachments/20260903/0fcc0335/attachment-0001.txt>


More information about the Toybox mailing list