Add documentation on how to debug the app

doc/bitcoin.md

@@ -8,7 +8,7 @@ The protocol documentation for version from 2.0.0 and before 2.1.0 is [here](./v
 
 ### APDUs
 
-The messaging format of the app is compatible with the [APDU protocol](https://developers.ledger.com/docs/nano-app/application-structure/#apdu-interpretation-loop). The `P1` field is reserved for future use and must be set to `0` in all messages. The `P2` field is used as a protocol version identifier; the current version is `1`, while version `0` is still supported. No other value must be used.
+The messaging format of the app is compatible with the [APDU protocol](https://developers.ledger.com/docs/device-app/explanation/io#apdu-interpretation-loop). The `P1` field is reserved for future use and must be set to `0` in all messages. The `P2` field is used as a protocol version identifier; the current version is `1`, while version `0` is still supported. No other value must be used.
 
 The main commands use `CLA = 0xE1`, unlike the legacy Bitcoin application that used `CLA = 0xE0`.
 

doc/debugging.md

@@ -0,0 +1,23 @@
+This page contains some information for developers on how to debug failures of the commands of the Ledger Bitcoin app.
+
+# Status Words
+
+Failures in the app's commands are always reported by a corresponding Status Word; see [bitcoin.md](bitcoin.md#status-words) for the currently defined Status Words. Client libraries generally return structured versions of the same Status Words.
+
+The Status Word is contained in the last 2 bytes of the APDU Response, interpreted as a big-endian 16-bit constant.
+
+# Error codes
+
+In addition to the Status Word, some errors provide further details as an _error code_, contained in the first two bytes of the _data_ portion of the reply.
+
+Integrations can ignore the error codes and should not rely on them in production (as they are not guaranteed to be consistent across versions of the app); however, they can provide valuable debugging information for developers working on an integration.
+
+You can see the list of the currently defined error codes in [error_codes.h](../src/error_codes.h).
+
+# Running on Speculos with semihosting
+
+When running the bitcoin app on the [speculos](https://github.com/LedgerHQ/speculos) emulator, additional debugging information can be printed on the command line (on the same terminal where speculos is running) by defining the `DEBUG=10` constant when running the `make` command. See the [ledger-app-builder](https://github.com/LedgerHQ/ledger-app-builder?tab=readme-ov-file#compile-your-app-in-the-container) for instructions on how to build the app for speculos.
+
+Binaries produced in this way _will_ crash if sideloading on a real device.
+
+Note: `DEBUG=10` is a feature of the Bitcoin app, and is not used in other Ledger apps.

doc/v0/bitcoin.md

@@ -6,7 +6,7 @@ This page described the _deprecated_ version 0 of the protocol, as implemented i
 
 ### APDUs
 
-The messaging format of the app is compatible with the [APDU protocol](https://developers.ledger.com/docs/nano-app/application-structure/#apdu-interpretation-loop). The `P1` and `P2` fields are reserved for future use and must be set to `0` in all messages.
+The messaging format of the app is compatible with the [APDU protocol](https://developers.ledger.com/docs/device-app/explanation/io#apdu-interpretation-loop). The `P1` and `P2` fields are reserved for future use and must be set to `0` in all messages.
 
 The main commands use `CLA = 0xE1`, unlike the legacy Bitcoin application that used `CLA = 0xE0`.