Fix IEEE 802.15.4 address handling and raw transmit error propagation (closes 596)

[potto216]

Overview

This PR fixes three issues in the libtock-rs IEEE 802.15.4 API and closes #596. The issues fixed are:

1. set_address_short() and set_pan() incorrectly added 1 to values before passing them to the Tock driver.
2. The getter response decoding narrowed values to u16 before subtracting the offset added by the driver.
3. transmit_frame_raw() ignored errors reported through the transmission-complete upcall.

This work follows the discussion Why do Tock's MAC and physical IEEE 802.15.4 capsule drivers add 1 to their CommandReturn::success_u32 return values?.

Other IEEE 802.15.4 changes are outside the scope of this PR and will be addressed separately.

Address and PAN setters

The Tock IEEE 802.15.4 drivers expect short addresses and PAN IDs to be passed without modification:

• SET_SHORT_ADDR passes arg1 as u16 directly to set_address().
• SET_PAN passes arg1 as u16 directly to set_pan().

However, libtock-rs previously added 1 before invoking these commands:

short_addr as u32 + 1
pan as u32 + 1

This shifted every configured value and caused 0xffff to wrap to zero when the driver narrowed it to u16.

This PR removes the incorrect additions and passes both values to the driver as-is.

Address and PAN getters

Unlike the setter commands, the Tock drivers add 1 when returning a short address or PAN ID:

• GET_SHORT_ADDR
• GET_PAN

libtock-rs must therefore subtract 1 when decoding these responses. The subtraction must happen while the value is still a u32:

.map(|value| (value - 1) as u16)

Casting before subtracting is incorrect for 0xffff. The driver encodes this value as 0x1_0000, which requires 17 bits. Narrowing it first produces zero, after which subtracting 1 can overflow.

Raw transmission errors

transmit_frame_raw() previously returned Ok(()) whenever the transmission-complete upcall ran, regardless of the status reported by that upcall.

This PR checks the callback status and:

• Returns Ok(()) when the status is zero.
• Converts a nonzero status into an ErrorCode.
• Falls back to ErrorCode::Fail if the status is not a recognized error code.

Fake driver and tests

The fake IEEE 802.15.4 driver now matches the Tock drivers by adding 1 to values returned by GET_SHORT_ADDR and GET_PAN.

The configuration tests now exercise round trips for:

• Zero: 0x0000
• One: 0x0001
• Representative intermediate values
• The maximum 16-bit value: 0xffff

These cases verify both the setter behavior and correct decoding of the getter responses.

One code discrepancy to fix before publishing: the current local diff changes get_address_short() to subtract before narrowing, but get_pan() still contains:

.map(|pan| pan as u16 - 1)

To match this description and handle 0xffff, it should be:

.map(|pan| (pan - 1) as u16)

AI Usage

I used OpenAI Codex to help with the fix and Google Gemni to review the patch. I reviewed all committed code.

[jrvanwhy]

Looks good from a libtock-rs perspective. I'll let someone from the Network WG (or at least whom is familiar with the 802.15.4 syscall driver) make sure the change makes sense W.R.T. that API.

If no-one else looks at it within a week, ping me and I'll merge this.

[tyler-potyondy]

Looks good to go! Thanks for fixing this @potto216!

Checked the api changes against libtock-c's (which has been much more heavily tested) and this matches.

[tyler-potyondy]

Out of curiosity, @potto216 do you know why this was 2137?

[potto216]

@tyler-potyondy Interesting question and I do not. I could not find another use of that value as an error or return code in libtock-rs, libtock-c, or tock. Also, I didn't see any reference to it in the commit with the change (cde91be). And the documentation on the subscribe didn't suggest anything (below)
Subscribe Number: 1

• Description: Callback when a frame transmission completes.
• Argument 1: Status code (success or error).
• Argument 2: acked flag (0/1) indicating whether the frame was acked.
• Argument 3: Unused.
• Returns: Ok(()).

I only ran into it when my tests failed after following Codex's advice in transmit_frame_raw to not just always return ok for after yielding
https://github.com/tock/libtock-rs/pull/597/changes#diff-9836a6938b05d997dc1c24e564ec5f7d167ab928a283344a0c9e96b7ca277340R195

[jrvanwhy]

I'm going to hazard a guess that this is either a copy-paste error, or something from a now-outdated design.