add: split PacketResponseNG status to status and reason

CHANGELOG.md

@@ -3,6 +3,7 @@ All notable changes to this project will be documented in this file.
 This project uses the changelog in accordance with [keepchangelog](http://keepachangelog.com/). Please use this to write notable changes, which is not the same as git commit log...
 
 ## [unreleased][unreleased]
+- Changed split PacketResponseNG status into status and reason(@douniwan5788)
 - Print LUA and Python versions in `hw version` command (@jmichelp)
 - Updated LUA to v5.4.7 which adds utf-8 support (@jmichelp)
 - Changed `lf search` - it now tries to read and decode paxton id (@iceman1001)

armsrc/cmd.c

@@ -72,7 +72,7 @@ int reply_old(uint64_t cmd, uint64_t arg0, uint64_t arg1, uint64_t arg2, const v
     return PM3_SUCCESS;
 }
 
-static int reply_ng_internal(uint16_t cmd, int16_t status, const uint8_t *data, size_t len, bool ng) {
+static int reply_ng_internal(uint16_t cmd, int8_t status, uint8_t reason, const uint8_t *data, size_t len, bool ng) {
     PacketResponseNGRaw txBufferNG;
     size_t txBufferNGLen;
 
@@ -80,6 +80,7 @@ static int reply_ng_internal(uint16_t cmd, int16_t status, const uint8_t *data,
     txBufferNG.pre.magic = RESPONSENG_PREAMBLE_MAGIC;
     txBufferNG.pre.cmd = cmd;
     txBufferNG.pre.status = status;
+    txBufferNG.pre.reason = reason;
     txBufferNG.pre.ng = ng;
     if (len > PM3_CMD_DATA_SIZE) {
         len = PM3_CMD_DATA_SIZE;
@@ -136,12 +137,12 @@ static int reply_ng_internal(uint16_t cmd, int16_t status, const uint8_t *data,
     return PM3_SUCCESS;
 }
 
-int reply_ng(uint16_t cmd, int16_t status, const uint8_t *data, size_t len) {
+int reply_ng(uint16_t cmd, int8_t status, const uint8_t *data, size_t len) {
-    return reply_ng_internal(cmd, status, data, len, true);
+    return reply_ng_internal(cmd, status, -1, data, len, true);
 }
 
 int reply_mix(uint64_t cmd, uint64_t arg0, uint64_t arg1, uint64_t arg2, const void *data, size_t len) {
-    int16_t status = PM3_SUCCESS;
+    int8_t status = PM3_SUCCESS;
     uint64_t arg[3] = {arg0, arg1, arg2};
     if (len > PM3_CMD_DATA_SIZE - sizeof(arg)) {
         len = PM3_CMD_DATA_SIZE - sizeof(arg);
@@ -153,7 +154,11 @@ int reply_mix(uint64_t cmd, uint64_t arg0, uint64_t arg1, uint64_t arg2, const v
         memcpy(cmddata + sizeof(arg), data, (int)len);
     }
 
-    return reply_ng_internal((cmd & 0xFFFF), status, cmddata, len + sizeof(arg), false);
+    return reply_ng_internal((cmd & 0xFFFF), status, -1, cmddata, len + sizeof(arg), false);
+}
+
+int reply_reason(uint16_t cmd, int8_t status, int8_t reason, const uint8_t *data, size_t len) {
+    return reply_ng_internal(cmd, status, reason, data, len, true);
 }
 
 static int receive_ng_internal(PacketCommandNG *rx, uint32_t read_ng(uint8_t *data, size_t len), bool usb, bool fpc) {

armsrc/cmd.h

@@ -28,8 +28,9 @@ extern bool g_reply_via_fpc;
 extern bool g_reply_via_usb;
 
 int reply_old(uint64_t cmd, uint64_t arg0, uint64_t arg1, uint64_t arg2, const void *data, size_t len);
-int reply_ng(uint16_t cmd, int16_t status, const uint8_t *data, size_t len);
+int reply_ng(uint16_t cmd, int8_t status, const uint8_t *data, size_t len);
 int reply_mix(uint64_t cmd, uint64_t arg0, uint64_t arg1, uint64_t arg2, const void *data, size_t len);
+int reply_reason(uint16_t cmd, int8_t status, int8_t reason, const uint8_t *data, size_t len);
 int receive_ng(PacketCommandNG *rx);
 
 #endif // _PROXMARK_CMD_H_

armsrc/thinfilm.c

@@ -140,7 +140,7 @@ void SimulateThinFilm(uint8_t *data, size_t len) {
 
     uint16_t hf_baseline = ReadReaderField();
 
-    int16_t status = PM3_SUCCESS;
+    int8_t status = PM3_SUCCESS;
     CodeThinfilmAsTag(data, len);
 
     tosend_t *ts = get_tosend();

client/src/comms.c

@@ -481,6 +481,7 @@ __attribute__((force_align_arg_pointer))
                 uint16_t length = rx_raw.pre.length;
                 rx.ng = rx_raw.pre.ng;
                 rx.status = rx_raw.pre.status;
+                rx.reason = rx_raw.pre.reason;
                 rx.cmd = rx_raw.pre.cmd;
 
                 if (rx.magic == RESPONSENG_PREAMBLE_MAGIC) { // New style NG reply

client/src/scripting.c

@@ -371,6 +371,9 @@ static int l_WaitForResponseTimeout(lua_State *L) {
     memcpy(foo + n, &resp.status, sizeof(resp.status));
     n += sizeof(resp.status);
 
+    memcpy(foo + n, &resp.reason, sizeof(resp.reason));
+    n += sizeof(resp.reason);
+
     memcpy(foo + n, &resp.crc, sizeof(resp.crc));
     n += sizeof(resp.crc);
 

doc/new_frame_format.md

@@ -70,8 +70,9 @@ For responses from the Proxmark3:
 
     uint32_t magic;
     uint16_t length : 15;
-    bool ng : 1;
+    bool     ng : 1;
-    int16_t  status;
+    int8_t   status;
+    int8_t   reason;
     uint16_t cmd;
     uint8_t  data[length];
     uint16_t crc;
@@ -80,6 +81,7 @@ For responses from the Proxmark3:
 * `length`: length of the variable payload, 0 if none, max 512 (PM3_CMD_DATA_SIZE) for now.
 * `ng`:     flag to tell if the data is following the new format (ng) or the old one, see transition notes below
 * `status`: a field to send back the status of the command execution
+* `reason`: details about what the status indicates for the specified command
 * `cmd`:    as previously, on 16b as it's enough
 * `data`:   variable length payload
 * `crc`:    either an actual CRC (crc14a) or a Magic placeholder (`b3`)
@@ -130,7 +132,8 @@ After the full transition, we might remove the fields `oldarg` and `ng`.
         uint16_t cmd;
         uint16_t length;
         uint32_t magic;      //  NG
-        int16_t  status;     //  NG
+        int8_t   status;     //  NG
+        int8_t   reason;     //  NG
         uint16_t crc;        //  NG
         uint64_t oldarg[3];  //  OLD
         union {
@@ -177,9 +180,10 @@ Old handlers will still find their stuff in `PacketCommandNG.oldarg` field.
 
 (`common/cmd.c`)
 
-    int16_t reply_ng(uint16_t cmd, int16_t status, uint8_t *data, size_t len)
+    int reply_old(uint64_t cmd, uint64_t arg0, uint64_t arg1, uint64_t arg2, const void *data, size_t len);
-    int16_t reply_old(uint64_t cmd, uint64_t arg0, uint64_t arg1, uint64_t arg2, void *data, size_t len)
+    int reply_ng(uint16_t cmd, int8_t status, const uint8_t *data, size_t len);
-    int16_t reply_mix(uint64_t cmd, uint64_t arg0, uint64_t arg1, uint64_t arg2, void *data, size_t len)
+    int reply_mix(uint64_t cmd, uint64_t arg0, uint64_t arg1, uint64_t arg2, const void *data, size_t len);
+    int reply_reason(uint16_t cmd, int8_t status, int8_t reason, const uint8_t *data, size_t len);
 
 So replies should make the transition from `reply_old` to `reply_ng` to benefit from smaller frames (and client reception adjusted accordingly of course).  
 `reply_mix` is a transition fct: it uses the same API as reply_old but benefits somehow from variable length frames. It occupies at least 24b of data for the oldargs and real data is therefore limited to PM3_CMD_DATA_SIZE - 24. Besides the size limitation, the client command doesn't know if this was an OLD frame or a MIX frame, it gets its oldargs and data as usual.

include/pm3_cmd.h

@@ -84,8 +84,9 @@ typedef struct {
 typedef struct {
     uint32_t magic;
     uint16_t length : 15;  // length of the variable part, 0 if none.
-    bool ng : 1;
+    bool     ng : 1;
-    int16_t  status;
+    int8_t   status;
+    int8_t   reason;
     uint16_t cmd;
 } PACKED PacketResponseNGPreamble;
 
@@ -101,7 +102,8 @@ typedef struct {
     uint16_t cmd;
     uint16_t length;
     uint32_t magic;      //  NG
-    int16_t  status;     //  NG
+    int8_t   status;     //  NG
+    int8_t   reason;     //  NG
     uint16_t crc;        //  NG
     uint64_t oldarg[3];  //  OLD
     union {
@@ -869,6 +871,9 @@ typedef struct {
 // Regular quit
 #define PM3_SQUIT            -100
 
+// reserved for future protocol change
+#define PM3_RESERVED         -128
+
 // LF
 #define LF_FREQ2DIV(f) ((int)(((12000.0 + (f)/2.0)/(f))-1))
 #define LF_DIVISOR_125 LF_FREQ2DIV(125)