sysfstree 0.1.11
sysfstree displayes gadget usb information from the ConfigFS and SysFS
License: MIT
Keywords: configfs,sysfs,pi,usb,gadget

# SysFSTree

*sysfstree* implements a generator function that will recursively iterate a file system, typically /sys, retrieving
the contents of the files, and displaying the path names and data in a fashion similar to the tree(1) command.

A small python module for generating annotated tree(1) style output for /sys items.

This can be used by other modules to generate system specific tools that allow
for showing system specific information.

Calling sequence:

    import sysfstree

    sysfs = sysfstree(root, maxlevel, include, exclude):
    for l in sysfs._tree(p, os.listdir(p), "", -1):
        print("%s" % (l))

Where:
- *root* is the top level path to start at
- *maxlevel* is the maximum depth to recurse to
- *include* is a list of requested includes at each recursion level
- *exclude* is a list of requested excludes at each recursion level

The include and exclude use shell matching (fnmatch).

## Examples

The sysfstree_raspbian Python package uses this module to display information
about various various Raspbian specific areas in /sys. For example:

    # sysfstree_raspbian --gadget
    [/sys/kernel/config/usb_gadget]
    ┗━[g1]
        ┣━[os_desc]
        ┃   ┣━qw_sign:
        ┃   ┣━b_vendor_code: 0x00
        ┃   ┗━use: 0
        ┣━[strings]
        ┃   ┗━[0x409]
        ┃       ┣━serialnumber: 0123456789
        ┃       ┣━product: Bar Gadget
        ┃       ┗━manufacturer: Foo Inc.
        ┣━[configs]
        ┃   ┗━[The only one.1]
        ┃       ┣━ecm.usb0 -> /sys/kernel/config/usb_gadget/g1/functions/ecm.usb0
        ┃       ┣━acm.GS1 -> /sys/kernel/config/usb_gadget/g1/functions/acm.usb1
        ┃       ┣━acm.GS0 -> /sys/kernel/config/usb_gadget/g1/functions/acm.usb0
        ┃       ┣━[strings]
        ┃       ┃   ┗━[0x409]
        ┃       ┃       ┗━configuration: CDC 2xACM+ECM
        ┃       ┣━bmAttributes: 0x80
        ┃       ┗━MaxPower: 2
        ┣━[functions]
        ┃   ┣━[ecm.usb0]
        ┃   ┃   ┣━ifname: usb0
        ┃   ┃   ┣━qmult: 5
        ┃   ┃   ┣━host_addr: b6:5f:5e:fe:f1:50
        ┃   ┃   ┗━dev_addr: ce:68:2d:82:a1:a9
        ┃   ┣━[acm.usb1]
        ┃   ┃   ┗━port_num: 1
        ┃   ┗━[acm.usb0]
        ┃       ┗━port_num: 0
        ┣━UDC: fe980000.usb
        ┣━bcdUSB: 0x0200
        ┣━bcdDevice: 0x0001
        ┣━idProduct: 0x0104
        ┣━idVendor: 0x1d6b
        ┣━bMaxPacketSize0: 0x40
        ┣━bDeviceProtocol: 0x00
        ┣━bDeviceSubClass: 0x00
        ┗━bDeviceClass: 0x00


    # sysfstree_raspbian --soc-udc
    [/sys/devices/platform/soc]
    ┣━[fe980000.usb]
    ┃   ┣━[udc]
    ┃   ┃   ┗━[fe980000.usb]
    ┃   ┃       ┣━device -> /sys/devices/platform/soc/fe980000.usb
    ┃   ┃       ┣━subsystem -> /sys/class/udc
    ┃   ┃       ┣━[power]
    ┃   ┃       ┃   ┣━runtime_suspended_time: 0
    ┃   ┃       ┃   ┣━runtime_active_time: 0
    ┃   ┃       ┃   ┣━control: auto
    ┃   ┃       ┃   ┗━runtime_status: unsupported
    ┃   ┃       ┣━current_speed: UNKNOWN
    ┃   ┃       ┣━is_selfpowered: 0
    ┃   ┃       ┣━b_hnp_enable: 0
    ┃   ┃       ┣━is_otg: 1
    ┃   ┃       ┣━function: g1
    ┃   ┃       ┣━state: not attached
    ┃   ┃       ┣━a_hnp_support: 0
    ┃   ┃       ┣━uevent: DRIVER=configfs-gadget
    ┃   ┃       ┃       : USB_UDC_NAME=fe980000.usb
    ┃   ┃       ┃       : USB_UDC_DRIVER=g1
    ┃   ┃       ┣━is_a_peripheral: 0
    ┃   ┃       ┣━a_alt_hnp_support: 0
    ┃   ┃       ┣━maximum_speed: high-speed


That was generated by:

    import sysfstree
        sysfs = sysfstree("/sys/kernel/config/usb_gadget")
        for l in sysfs._tree(p, os.listdir(p), "", -1):
                print("%s" % (l))

    import sysfstree
        sysfs = sysfstree("/sys/kernel/config/usb_gadget")
        for l in sysfs._tree(p, os.listdir(p), "", -1):
                print("%s" % (l))


## Gadget

sysfstree was originally implemented to help work with Gadget USB configuration. It has several
options for displaying gadget configuration.

Current configuration:
--usb_gadget - /sys/kernel/config/usb_gadget
--udc - /sys/class/udc/fe980000.usb
--soc - /sys/devices/platform/soc/fe980000.usb/gadget

Show gadget configuration:
--gadget - /sys/kernel/config/usb_gadget

Show loaded modules:
- /sys/module/usbf_f*
- /sys/module/udc_core
- /sys/module/dwc2
- /sys/module/libcomposite

## Gadget Function Modules available

--usb_f - /lib/modules/$(uname --kernel-release)/kernel/drivers/usb/gadget/function/usb_f_*


## Examples
```
# sysfstree_raspbian --soc-udc
[/sys/devices/platform/soc]
┣━[fe980000.usb]
┃   ┣━[udc]
┃   ┃   ┗━[fe980000.usb]
┃   ┃       ┣━device -> /sys/devices/platform/soc/fe980000.usb
┃   ┃       ┣━subsystem -> /sys/class/udc
┃   ┃       ┣━[power]
┃   ┃       ┃   ┣━runtime_suspended_time: 0
┃   ┃       ┃   ┣━runtime_active_time: 0
┃   ┃       ┃   ┣━control: auto
┃   ┃       ┃   ┗━runtime_status: unsupported
┃   ┃       ┣━current_speed: UNKNOWN
┃   ┃       ┣━is_selfpowered: 0
┃   ┃       ┣━b_hnp_enable: 0
┃   ┃       ┣━is_otg: 1
┃   ┃       ┣━function: g1
┃   ┃       ┣━state: not attached
┃   ┃       ┣━a_hnp_support: 0
┃   ┃       ┣━uevent: DRIVER=configfs-gadget
┃   ┃       ┃       : USB_UDC_NAME=fe980000.usb
┃   ┃       ┃       : USB_UDC_DRIVER=g1
┃   ┃       ┣━is_a_peripheral: 0
┃   ┃       ┣━a_alt_hnp_support: 0
┃   ┃       ┣━maximum_speed: high-speed
```


## Running Tests

sysfstree currently only has doctests.

Run tests with nose::

    nosetests --with-doctest src/sysfstree

Run tests with doctest::

    python -m doctest -v src/sysfstree/__init__.py

## Author
Stuart.Lynne@belcarra.com
Copyright (c) 2020 Belcarra Technologies (2005) Corp.