coreboot/util/uio_usbdebug
Patrick Georgi 1afe286367 util: Add SPDX header, replacing boiler plate where applicable
In a few cases a license was added: Stuff coming from Linux is
"GPL-2.0" (not GPL-2.0-only!), build-release is by me and got the
usual GPL-2.0-only treatment. uio_usbdebug and spkmodem had their
licenses propagate to all their files.

Change-Id: Ia5712bbaa417cb9e937834512351fcc0acfa16be
Signed-off-by: Patrick Georgi <pgeorgi@google.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/41202
Reviewed-by: Angel Pons <th3fanbus@gmail.com>
Reviewed-by: HAOUAS Elyes <ehaouas@noos.fr>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2020-05-11 17:11:59 +00:00
..
console treewide: Remove "this file is part of" lines 2020-05-11 17:11:40 +00:00
drivers/usb util/: Replace GPLv2 boiler plate with SPDX header 2020-05-09 21:22:08 +00:00
include/device util/: Replace GPLv2 boiler plate with SPDX header 2020-05-09 21:22:08 +00:00
lib util: Add SPDX header, replacing boiler plate where applicable 2020-05-11 17:11:59 +00:00
linux util: Add SPDX header, replacing boiler plate where applicable 2020-05-11 17:11:59 +00:00
Makefile util: Add SPDX header, replacing boiler plate where applicable 2020-05-11 17:11:59 +00:00
README uio_usbdebug: User-space-i/o framework for usbdebug 2015-03-19 19:19:42 +01:00
description.md util: Add description.md to each util 2018-07-26 13:26:50 +00:00
uio_usbdebug.c util/: Replace GPLv2 boiler plate with SPDX header 2020-05-09 21:22:08 +00:00
uio_usbdebug_intel.c treewide: Remove "this file is part of" lines 2020-05-11 17:11:40 +00:00

README

uio_usbdebug - Run coreboot's usbdebug driver in userspace
==========================================================


## Purpose

uio_usbdebug enables you to debug coreboot's usbdebug driver inside a
running operating system (only Linux at this time). This comes very
handy if you're hacking the usbdebug driver and don't have any other
debug output from coreboot itself.


## State

Currently only Intel chipsets are supported. Support for other chipsets
should be straightforward (normally just some port-enable code has to
be implemented).

The Linux kernel driver (see linux/uio_ehci_pci.c) has only one PCI ID
hardcoded (for ICH7). The whole setup has been developed and tested on
a ThinkPad T60.

### Files

uio_usbdebug.c       -	The userspace part of the uio interface.

uio_usbdebug_intel.c -	Port enable code for Intel chipsets.

linux/uio_ehci_pci.c -	Kernel part of the uio interface.

console/printk.c     -	A do_printk() implementation so you can see debug
			output with CONFIG_DEBUG_USBDEBUG enabled.

device/*.c lib/*.c   -	Some stubs for (hopefully) unneeded functions for
			proper linking.


## Usage

### Preparations

The MMIO space has to be a whole 4K page in size and alignment to be
mapped into userspace. This is very uncommon, so you'll most probably
have to remap the MMIO space. The Linux kernel does that for you with
the `pci=resource_alignment=<pci address>` kernel parameter (e.g.
`pci=resource_alignment=0:1d.7` for ICH7).

If your PCI device isn't listed in the kernel driver yet, you might want
to add it to the `ehci_pci_ids` table in `linux/uio_ehci_pci.c` (or do
some module alias magic if you know how to).

### Build / Install

Somehow like this:

$ # Configure coreboot for your board and enable CONFIG_USBDEBUG
$ make menuconfig
$ cd util/uio_usbdebug/
$ make -Clinux/
$ sudo make -Clinux/ install
$ make

### Run

$ # Unload Linux' EHCI driver (high-speed devices will stop working)
$ sudo modprobe -r ehci-pci
$ # Load the uio driver
$ sudo modprobe uio-ehci-pci
$ # Find your uio device
$ ls /sys/module/uio_ehci_pci/drivers/*/*/uio/
uio0
$ # Run uio_usbdebug on this device
$ sudo ./uio_usbdebug /dev/uio0

Sadly, uio_usbdebug has to be run with root privileges since there are
port-80 writes in the usbdebug driver.