[doc, spi_device] Document limitations/feature usage

[rivos-eblot]

Description

While implementing QEMU emulation of SPI device, I noticed several grey areas in the documentation, which does not provide enough information on how to use the READ commands:

1. It seems the address that goes along any standard SPI data flash READ commands (such as 0x3 and 0xb) has some strong limitations which are not really visible in the documentation. In order for the SPI device IP to handle these commands:
   a. The address of first READ command should be 0x0 or less than the value defined READ_THRESHOLD register for the readbuf_watermark to be signaled, or less than the read buffer size (1KiB) for the readbuf_flip to be signalled. Any value with MSB address bits (>9) in the READ address will result in the SPI device to never trigger these signals, which means the FW will never be notified of these events, and the remote SPI host to keep reading the data initially copied into the READ buffer
   b. Subsequent READ commands should not create gap in the address range, for similar reasons.
   I think the documentation of the supported use cases could be improved, which is to read data from 0..N-1 bytes in one or more subsequent READ commands with a linear addressing and no gap.
   There is no way the Ibex core could handle a READ command and fill the read buffer with data referenced from the specified READ address. It does mean either that the LSB part of the address cannot be used nonetheless. While it is possible to deduct parts of what's supported and is not from the actual documentation, I believe it is not as straightforward as it could be.
   Maybe the IP could be updated so that in case the READ address is deemed invalid, the flig/watermark is still triggered but an error flag is set, as the current implementation silently delivers invalid data, while the FW never receive any interrupt to update the read buffer and/or track the progress of the on-going transfer. This kind of error is hard to track down, especially with the doc grey area around the supported addresses.

2. The LAST_READ_ADDR register is hardly usable without a very specific context, since there is no way for the Ibex FW to know when a transaction is over/completed, i.e. when the /CS signal is released. It can poll this register (when?) and detects that some changes occured, but it may miss some changes. Maybe an evolution of the SPI device IP could be to add an interrupt line that would trigger on /CS release. It could be useful for general purpose (host command completion), not only for accessing LAST_READ_ADDR.

3. Some documentation sections seem to be tied to specifc use cases which are not really documented, such as "W must not write to this CSR unless it knows the upstream host is inactive and expects initial values for the next transaction" / "However, SW may overwrite the requested value, so long as the SPI host is held inactive.". As there is no real way to know whether the SPI host is active or not, I would assume it refers to a specific protocol between the SPI device and the remote SPI host, but it is open to interpretation without a specific context, rather than a "dummy" implementation of a SPI device. The context in which the SPI device is designed to operate would help to understand how the SPI device needs to be driven.