[DOC] Document stability requirements on userspace buffers

[travisdowns]

This is half a request for documentaiton and half a question.

I am unusre of the stability requirements/guarantees around the buffers for io_uring submitted writes. For example, if I send a buffer write down for write, and before it completes I modify some part of the buffer, at an arbitrarily alignmnet, do I have any guarantees at all? For example, is the unmodified part of the buffer guaranteed to be correctly written (as seen by a subsequent read)? Is each byte of the modified part guaranteed to have either the original or new value (on a byte-per-byte basis, it's obvious the entire region won't be consistently old or new in general), or could it have a totally garbage value? Can doing this but the kernel storage layer in an inconsistent state (i.e., where a block has the "wrong" value if you even after multiple writes of the correct value, e.g., because internally there is a checksum<->block value mismatch).

[isilence]

It's pretty much what was answered on the block list but with even more cogs in the middle and wider variety of file types. It depends on the hardware, drivers, and the file in question, so the general answer is that you don't have guarantees. I'd also share the "please don't do that" sentiment.

[travisdowns]

Thanks @isilence , much appreciated.

Is this something that should be documented and is liburing an appropriate place to do it?

[isilence]

Yeah, it'd be great to add a note that as a general rule buffers must remain unchanged until writing requests (write, send, etc.) using them complete.

[axboe]

I think it should/could be documented somewhere, but I really don't think liburing is the right place to do it - this has nothing to do with io_uring or liburing, it's really more of a storage in general concept. Modifying inflight buffers with O_DIRECT will potentially burn you the same way whether it's io_uring, aio, or even plain sync write(2). I'll close this one.

[travisdowns]

this has nothing to do with io_uring or liburing, it's really more of a storage in general concept. Modifying inflight buffers with O_DIRECT will potentially burn you the same way whether it's io_uring, aio, or even plain sync write(2).

Right, but my thought was that io_uring is the maybe the only library that people are interfacing with directly so the requirements on use, even if they come from the lower layer, might well be documented at the io_uring layer, so that the user don't need to go all the way down the stack to the device to understand the requirements (as most of the other lower level details are effectively hidden).

Good point about write(2), I guess it's actually the same problem there, so fair not to document it here.

Thanks for your time!