Google Git
Sign in
cos / mirrors / cros / chromiumos / platform2 / 1cbefaa36bb6030e223039c81838bc317c1d7995 / . / mist
tree: 819df31f145c1b256b5a9753dc4fc2f6681f020c [path history] [tgz]
  1. proto/
  2. 51-mist.rules
  3. BUILD.gn
  4. config_loader.cc
  5. config_loader.h
  6. config_loader_test.cc
  7. context.cc
  8. context.h
  9. default.conf
  10. event_dispatcher.cc
  11. event_dispatcher.h
  12. event_dispatcher_test.cc
  13. main.cc
  14. metrics.cc
  15. metrics.h
  16. mist.cc
  17. mist.h
  18. mock_config_loader.h
  19. mock_context.cc
  20. mock_context.h
  21. mock_usb_device_event_observer.h
  22. OWNERS
  23. README.md
  24. usb_bulk_transfer.cc
  25. usb_bulk_transfer.h
  26. usb_config_descriptor.cc
  27. usb_config_descriptor.h
  28. usb_config_descriptor_test.cc
  29. usb_constants.cc
  30. usb_constants.h
  31. usb_constants_test.cc
  32. usb_device.cc
  33. usb_device.h
  34. usb_device_descriptor.cc
  35. usb_device_descriptor.h
  36. usb_device_descriptor_test.cc
  37. usb_device_event_notifier.cc
  38. usb_device_event_notifier.h
  39. usb_device_event_notifier_test.cc
  40. usb_device_event_observer.h
  41. usb_endpoint_descriptor.cc
  42. usb_endpoint_descriptor.h
  43. usb_endpoint_descriptor_test.cc
  44. usb_error.cc
  45. usb_error.h
  46. usb_error_test.cc
  47. usb_interface.cc
  48. usb_interface.h
  49. usb_interface_descriptor.cc
  50. usb_interface_descriptor.h
  51. usb_interface_descriptor_test.cc
  52. usb_manager.cc
  53. usb_manager.h
  54. usb_modem_one_shot_switcher.cc
  55. usb_modem_one_shot_switcher.h
  56. usb_modem_switch_context.cc
  57. usb_modem_switch_context.h
  58. usb_modem_switch_context_test.cc
  59. usb_modem_switch_operation.cc
  60. usb_modem_switch_operation.h
  61. usb_modem_switcher.cc
  62. usb_modem_switcher.h
  63. usb_transfer.cc
  64. usb_transfer.h
  65. usb_transfer_test.cc
mist/README.md

mist: Modem Interface Switching Tool

Overview

mist is a Chromium OS utility for switching USB cellular dongles into the modem mode. A cellular dongle may implement multiple functions and the function exposed by its initial USB configuration may not be a modem. We need to switch the device into a modem before it can be detected and managed by ModemManager to provide cellular connectivity.

mist is activated by udev events. When udev detects a supported dongle, it invokes mist to switch the dongle into the modem mode. The mode switching operation invokes the following:

  • Open the USB device associated with the dongle. If the device has a USB configuration that exposes a MBIM interface, select that configuration and complete the switch operation. Otherwise, find and claim the mass storage interface of the device.
  • Initiate a bulk output transfer of a (or multiple) special USB message(s) to the mass storage endpoint of the device.
  • On some devices, a bulk input transfer from the mass storage endpoint of the device is expected after completing each bulk output transfer.
  • Once the transfer of the last message completes, the device is expected to disconnect from the USB bus and then reconnect to the bus after it has been switched to the modem mode. The device may change its USB vendor ID and product ID (mostly the latter) after the switch operation.

Device Detection

mist relies on udev to detect when a dongle is plugged into the system. A udev rules file, /lib/udev/rules.d/51-mist.rules, is used to identify a supported dongle based on its USB vendor ID and product ID before and after mode switching. Upon detecting a supported dongle in the non-modem mode, udev launches a mist process to switch the dongle into modem, and also tags the dongle as MIST_SUPPORTED_DEVICE=1, which allows cros-disks to filter out the mass storage exposed by the dongle.

After udev launches the mist process, mist daemonizes itself so that it can use libudev to monitor the status of the mode switching via udev events. After the special USB messages are sent to the mass storage interface of the dongle, the dongle detaches itself from USB, which results in a udev remove event. After the dongle switches into the modem mode, it reattaches to USB, which results in a udev add event.

Configuration File

mist uses a protobuf-based configuration file, /usr/share/mist/default.conf, to specify information about the supported dongles. The configuration file specifies a list of supported dongles and the following information associated with each dongle:

  • Initial USB vendor and product ID of the modem when it is in the mass storage mode.
  • A list of possible final USB vendor and product IDs of the modem after it has switched to the modem mode.
  • A list of USB messages, in form of hexadecimal strings, to send to the mass storage interface of the modem in order to switch the modem to the modem mode.
  • An optional flag to indicate whether a response is expected from the mass storage interface after sending each USB message to the interface.
  • An optional initial delay, in milliseconds, that mist should wait before starting the modem switch operation.

USB Communications

mist uses libusb 1.x API to retrieve the USB descriptors of the dongle and initiate bulk transfers to the mass storage interface of the dongle. It thus needs to have read and write access to the USB device associated with the dongle.