doc/md/Installation_Instructions/usb-enumeration-and-flash.md

   1 <a id="Top"></a>
   2
   3 # Getting to stable COM ports
   4
   5 aka, Why I stopped using a PM3Easy without flash.
   6
   7 ## Table of Contents
   8 - [Getting to stable COM ports](#getting-to-stable-com-ports)
   9   - [Table of Contents](#table-of-contents)
  10   - [TLDR](#tldr)
  11   - [Three types of USB enumeration](#three-types-of-usb-enumeration)
  12     - [`Anonymous` devices](#anonymous-devices)
  13     - [`Sticky` devices](#sticky-devices)
  14     - [`Collision` devices](#collision-devices)
  15   - [What type of device is the PM3?](#what-type-of-device-is-the-pm3)
  16     - [Finding a hardware-based unique serial number](#finding-a-hardware-based-unique-serial-number)
  17     - [Two firmwares on one device?](#two-firmwares-on-one-device)
  18   - [Safer method to test and enable `FLASH` on PM3Easy](#safer-method-to-test-and-enable-flash-on-pm3easy)
  19   - [Conclusion](#conclusion)
  20
  21 ## TLDR
  22 ^[Top](#top)
  23
  24 If your device has the extra external flash, and you
  25 enable `PLATFORM_EXTRAS=FLASH` for the main firmware,
  26 you should flash the the bootloader ***at least once***
  27 with a flash-enabled bootloader build.
  28
  29 (e.g., `./pm3-flash-all` or `./pm3-flash-bootrom`)
  30
  31 ## Three types of USB enumeration
  32 ^[Top](#top)
  33
  34 Shorthand notation:
  35 1. No unique serial number reported == `Anonymous`
  36 2. Unique serial number reported == `Sticky`
  37 3. Fake unique serial number reported == `Collision`
  38
  39 When a USB device enumerates on the USB bus (and is thus
  40 discoverable and usable by the operating system), one of
  41 the optional bits of information that can be provided is
  42 a serial number.  The specification requires that, if such
  43 a serial number is provided, it must be unique for that
  44 type (VID/PID) of device.
  45
  46 ### `Anonymous` devices
  47 ^[Top](#top)
  48
  49 On Windows, when a device does ***not*** report a unique
  50 serial number, to uniquely identify the device, Windows
  51 adds information from the topology of the USB bus to
  52 make the device's ID unique.
  53
  54 This means that a device without a unique serial number
  55 will have a first ID when plugged into one USB port, and
  56 be seen as a totally different device when plugged into
  57 a second USB port.  If there are one or more USB hubs in
  58 between, the entire "path" from the PC to the device is
  59 included ... so plugging such device into each port on
  60 an eight-port hub would result in eight different devices
  61 being seen by Windows. (only one being "active" at a
  62 time, of course.)
  63
  64 ### `Sticky` devices
  65 ^[Top](#top)
  66
  67 In contrast, when a device reports a unique serial number,
  68 Windows (and presumably other operating systems) will
  69 use that serial number to uniquely identify the device.
  70 As a result, device-specific settings will "follow" the
  71 device even when it's plugged into a different USB port.
  72
  73 ### `Collision` devices
  74 ^[Top](#top)
  75
  76 There is a third situation, where the device pretends
  77 to have a unique serial number, but actually every
  78 device of that type reports the same serial number.
  79 This is a violation of the USB specification, but
  80 it does happen.
  81
  82 In this case, when only one of that type of device
  83 is ever connected to a given computer, it acts like
  84 a "Sticky" device.
  85
  86 However, as soon as a second of these devices is plugged
  87 in, the operating system discovers it was lied to...
  88 the unique serial number is a lie.  This means the OS
  89 cannot rely on the serial number to uniquely name the
  90 device.  On older OSes, this could cause the kernel to
  91 crash.  Even on newer OSes, the name collision can cause
  92 delays while the collision is detected and resolved.
  93 On Windows, this could add delays from when the second
  94 device is plugged in, until the second device is usable.
  95
  96 ## What type of device is the PM3?
  97 ^[Top](#top)
  98
  99 This is not a simple question, and has changed over time.
 100
 101 ### Finding a hardware-based unique serial number
 102 ^[Top](#top)
 103
 104 The Proxmark3 CPU and FPGA devices do not have a unique
 105 hardware serial number available.  As a result, until
 106 February 2023, all the Proxmark3 devices should have
 107 reported no serial number.  However, an easter egg was
 108 used as the serial number.  As a result, rather than
 109 being of type `Anonymous`, all Proxmark3 devices were
 110 actually of the `Collision` type.  This was no problem
 111 for single-device users, but anyone connecting more than
 112 one Proxmark3 to a computer would have seen, in the
 113 best case, delays in enumeration (>10 seconds at times).
 114
 115 Since February 2023, code was added to retrieve a unique
 116 serial number from the external flash chip, and use that
 117 as the proxmark's USB serial number also.
 118 (See PR [#1914](https://github.com/RfidResearchGroup/proxmark3/pull/1914).)
 119
 120 For the RDV4, the unique serial number feature was
 121 enabled by default, because all RDV4 shipped with
 122 external flash chips.
 123
 124 However, enabling this on PM3Easy devices requires editing
 125 `Makefile.platform` to include the line
 126 `PLATFORM_EXTRAS=FLASH`. This is ***NOT*** enabled by
 127 default for PM3Easy, mostly because the implementor did not
 128 have hardware to verify it would fail gracefully when
 129 the flash was not present.
 130
 131
 132 ### Two firmwares on one device?
 133 ^[Top](#top)
 134
 135 Whether a Proxmark3 device enumerates with a true unique
 136 serial number or a non-unique serial number (`Collision`)
 137 depends on whether the firmware was built with the
 138 `FLASH` feature enabled.
 139
 140 Actually, there's one more layer of complexity:
 141 the bootloader and the main firmware are separate
 142 executable entities.  Therefore, the bootloader might
 143 have been built without `FLASH` feature enabled, and
 144 therefore enumerate as the `Collision` type device
 145 with the fake serial number, while the main firmware
 146 may have been built with the `FLASH` feature enabled,
 147 and thus report the true unique serial number.
 148
 149 ## Safer method to test and enable `FLASH` on PM3Easy
 150 ^[Top](#top)
 151
 152 Many users won't know if their PM3Easy has the external
 153 flash chip.  For example, if the PM3Easy firmware was
 154 not built with this feature defined, the bootloader and
 155 firmware shipped on the device might be of `Collision`
 156 type.  However, enabling the `FLASH` feature when the
 157 device doesn't have the extra flash chip may prevent
 158 the device from booting.
 159
 160 The good news is that the bootloader can be left
 161 unmodified, while the main firmware is flashed with
 162 a version with the `FLASH` feature enabled.  This allows
 163 to verify that the flash chip exists and provides the
 164 unique serial number (or hangs) without removing the
 165 ability to get into the bootloader.  Then, only when
 166 the serial number's existence is confirmed, the bootloader
 167 can be updated to include the proper serial number also.
 168
 169 Here's some steps that do just that.
 170
 171 1. Clone / build / update the device with the latest
 172    Proxmark3 firmware.  This ensures a "known good"
 173    configuration and update process exists.  Get this
 174    working first.
 175 2. Edit `Makefile.platform` to include the line
 176     `PLATFORM_EXTRAS=FLASH`.  This will enable the
 177    features in the proxmark firmware that use the flash
 178    memory, including using the flash's unique serial number
 179    during USB enumeration.
 180 3. Re-build everything:
 181    `make clean && make -j`
 182 4. Flash ONLY the main firmware image:
 183    `./pm3-flash-fullimage`
 184    This ensures the bootloader remains in "known good"
 185    state, in case there is an incompatibility.
 186 5. Let the device come up normally, and connect to
 187    the device with the proxmark client:  `./pm3`
 188 6. Verify the device sees the firmware, and has detected
 189    a reasonable serial number: `hw status`
 190    The output should include something similar to:
 191 ```text
 192 [#] Flash memory
 193 [#]   Baudrate................ 24 MHz
 194 [#]   Init.................... OK
 195 [#]   Unique ID (be).......... 0x1032547698BADCFE
 196 ```
 197 7. If the device failed to boot, the above command did
 198    not report anything about flash memory, or the listed
 199    Unique ID is all `0` or `F`, then your device might
 200    not have the extra flash memory.  In this case, revert
 201    the changes to `Makefile.platform`, rebuild, and re-flash
 202    the main firmware image to restore to the "known good"
 203    state.
 204 8. Otherwise, if you do see the flash information and a
 205    reasonable serial number, then you could choose to
 206    update the bootloader (which was already built with
 207    the `FLASH` feature): `./pm3-flash-bootrom`.
 208
 209
 210 ## Conclusion
 211
 212 Updating the bootloader incorrectly can make it more
 213 difficult to recover the device (e.g., requires JTAG).
 214 However, by updating only the main firmware first,
 215 you can reduce this risk, while still enabling the
 216 flash-based features in your PM3Easy by verifying the
 217 functionality works for at least the main firmware first.
 218
 219