On 11/2/20 10:52 PM, Ahmed S. Darwish wrote:
On Mon, Nov 02, 2020 at 06:20:45PM -0800, John Hubbard wrote:
On 11/2/20 4:41 PM, Ahmed S. Darwish wrote:
On Mon, Nov 02, 2020 at 08:25:32PM -0400, Jason Gunthorpe wrote:
On Tue, Nov 03, 2020 at 01:17:12AM +0100, Ahmed S. Darwish wrote:
Please stick with the official exported API: raw_write_seqcount_begin().
How did you know this was 'offical exported API' ??
All the official exported seqlock.h APIs are marked with verbose
kernel-doc annotations on top. The rest are internal...
OK, but no one here was able to deduce that, probably because there is not
enough consistency throughout the kernel to be able to assume such things--even
though your seqlock project is internally consistent. It's just not *quite*
enough communication.
I think if we added the following it would be very nice:
The problem is, I've already documented seqlock.h to death.... There are
more comments than code in there, and there is "seqlock.rst" under
Documentation/ to further describe the big picture.
There comes a point where you decide what level of documentation to add,
and what level to skip.
Because in the end, you don't want to confuse "Joe, the general driver
developer" with too much details that's not relevant to their task at
hand. (I work in the Embedded domain, and I've seen so much ugly code
from embedded drivers/SoC developers already, sorry)
See for example my reply to Linus, where any talk about the lockdep-free
and barrier-free parts of the API was explicitly not mentioned in
seqlock.rst. This was done on purpose: 1) you want to keep the generic
case simple, but the special case do-able, 2) you want to encourage
people to use the standard entry/exit points as much as possible.
Well, OK, I'll leave it alone. This was not a normal case for the documentation,
anyway. We are using seqcount-ing in a little bit different way than usual,
so I guess an email thread like this is actually the proper way to work it out.
Just wanted to be sure that we didn't miss an opportunity to clarify anything
that needed clarifying it. Thanks for the detailed responses throughout!
thanks,
--
John Hubbard
NVIDIA
