Clarify register behavior on special cases

[aacuevas]

On the controller address map there are some registers that are either read-only (all the specification parameters or the *_CLK_HZ registers) and others that trigger an action and have no defined read value (OP_SOFT_RESET or OP_ACQ_CNT_RESET). Also, there are non-define and reserved addresses.

Since the low-level configuration channel does not have any way to inform of a failure, but on the other hand it is only intended for low-level access by the host (i.e.: by the API and not the user application s) I think we should clarify their behavior in the following way:

• Writing to a read-only register does nothing
• Reading from a trigger/write-only/invalid address is undefined (some random value will appear, has no meaning)

[aacuevas]

I have just noticed that for OP_SOFT_RESET in particular the spec says

This register is set to 0x00000000 by the controller upon entering the reset state.

However, this in practice means that reading from this register will always be 0.
OP_ACQ_CNT_RESET does not mention anything about a read, but the behavior would be the same.

Personally, I would just leave them as undefined reads. Again, this is a low-level communication channel to the controller, not the devices, that will only be used by a low-level API, and undefined reads or non-action writes are common behaviors for low level access to many hardware devices.

[jonnew]

With respect to the first comment, yes, I agree. This interface is part of an API's internal implementation and needs to be simple and fast.

With respect to the second comment, I have a feeling this was written to indicate that the user is not responsible for doing the following

oni_set_opt(ctx, OP_SOFT_RESET, 1);
oni_set_opt(ctx, OP_SOFT_RESET, 0);

in order to get a soft reset. That said, what you said is ultimately true and if we want to be more formal, we should only state what is required to get a soft reset behavior, which is writing 1 to the OP_SOFT_RESET. There are an infinite number of invalid actions that could follow, its not our job to state not to do each of them. Thus, this should be removed. However, we should add the access level (R, W, R/W, Reserved) for each of the registers in the Controller Address Space.