Troubleshooting
===============

This section lists common problems and possible solutions.
If you experience other problems or would like to add a solution for a problem
feel free to open an issue in our
`Github project <https://github.com/linux-automation/usbsdmux/issues>`__
or send us an email to info@linux-automation.com.

Permission denied when accessing the USB-SD-Mux
-----------------------------------------------

**Problem:** When using the control software a `PermissionError: Permission
denied` is raised.

In the following example a user tries to access the ``sg``-device
without the appropriate permissions:

.. code:: shell

   chris@dauntless:~$ usbsdmux /dev/sg0 get
   Traceback (most recent call last):
     File "/tmp/usbsdmux/venv/bin/usbsdmux", line 10, in <module>
       sys.exit(main())
     File "/tmp/usbsdmux/…/usbsdmux/__main__.py", line 77, in main
     File "/tmp/usbsdmux/…/usbsdmux/usbsdmux.py", line 55, in get_mode
     File "/tmp/usbsdmux/…/usbsdmux/pca9536.py", line 73, in read_register
     File "/tmp/usbsdmux/…/usbsdmux/usb2642i2c.py", line 425, in write_read_to
     File "/tmp/usbsdmux/…/usbsdmux/usb2642i2c.py", line 337, in _call_IOCTL
   PermissionError: [Errno 13] Permission denied: '/dev/sg0'

The user has no sufficient permissions to access the device node for ``/dev/sg0``.

To fix this issue either run the tool as `root` (e.g. using ``sudo``) or use
``udev`` to grant access to the device to your user.
The see Chapter :ref:`Using as non-root user<non-root-use>` for setup
instructions.

Access to the SD card fails with timeouts or read errors
--------------------------------------------------------

**Problem:** Using the USB-SD-Mux introduces an additional load and additional
disturbances for the micro SD card of your :term:`DUT`.
This can lead to problems like read errors and timeouts.

There are multiple workarounds for this issue:

1) Many users have reported that using a slow micro SD card yields better results
   than using a fast micro SD card.
2) Sometimes only ROM-Code (or integrated firmware) has trouble using the micro SD card
   inside the USB-SD-Mux. If this is the case, depending on your use-case, you may be
   able to load your bootloader from another media (like NAND-Flash or an eMMC) and
   afterwards access the SD card from inside this bootloader.
3) Depending on your setup you are maybe able to change drive-strength or the
   output-impedance matching of the used pins.
   This can help to access the micro SD card inside the USB-SD-Mux.
4) Depending on your setup you may be able to reduce the maximum clock frequency
   used.