Register WRITE Reply Behavior for Slow Routines

[Poofjunior]

• Proposed
• Prototype: Not Started
• Implementation: Not Started
• Specification: Not Started

Summary

Make explicit that the Harp Protocol does not specify whether a device WRITE reply occurs before or after the write's intended behavior has taken effect. Suggest example reply design patterns for uses cases where WRITE messages trigger (1) behavior that happens instantaneously vs (2) behavior that takes a long-period of time to complete.

Motivation

As is, Harp protocol does not specify when a register write reply should be issued. For behaviors that take a negligible amount of time, issuing a reply before or after the write's value has triggered the desired behavior is irrelevant. But for WRITEs that trigger behavior that will take a non-negligible time to complete, a WRITE reply does not make explicit whether the device has started or finished executing the desired behavior.

Detailed Design

The Harp protocol should mention this edge case in describing the behavior of WRITE replies that cannot be handled instantaneously and take a non-negligible time to complete.

The current spec lets developers issues device WRITE replies to indicate either the task start or the task end.

In cases where both the start and end convey meaningful information to the end-user, the spec should suggest: issue a WRITE reply message upon task-start and a follow-up EVENT message upon task completion.

Drawbacks

Leaving this unspecified without suggesting a design pattern makes the spec more difficult to adopt externally as this case will show up in more complicated real-world device use cases.

Alternatives

The current spec leaves this unspecified and does not mention how to handle this case.

Unresolved Questions

• In the device yaml, should we create an optional field per-register indicating whether a register write reply indicates the start or end of a task?

[bruno-f-cruz]

I agree with this. We have discussed this before and it should be added under "best practices".
I would say that the "unspoken standard" of having a 1:1 match between write request and reply simplifies a lot of control and analysis. Having every other side-effect conveyed via Event messages makes sense to me.