Hi, Previously I've always tried to document things in mac80211, and recently I posted a list of driver requirements. Now when digging through the HT code, I cannot even document driver requirements because it's not really clear even to me what they are---and I just refactored the code. But it's not just HT, also the new rate control API is probably not documented well enough (nbd has promised clarification though) and possibly more I can't think of right now (like the unimplemented mesh security, ...) I think the process has gotten out of hand. It might be good for you, but I can't be cleaning up mac80211 forever, this needs to stop at the original code we "inherited", new code needs to be documented better. I've also seen promises for documentation to be posted after the patches go in, but so far those have been empty promises. I take all the blame here for naively believing such promises would be followed up on, trusting people too much and accepting code without fully understanding it. Why did I even get this role? Therefore, I'm inclined to require (if I get to have any influence on this) all significant code contributions to mac80211, especially if they affect the driver API, to be _preceded_ by design documentation. Such documentation would consist of the documentation that will become part of the mac80211 header file (driver and rate control API), an explanation of why the driver API needs to be changed, how it affects existing drivers, which standard it is based on and why we need to implement it. Additionally, it should cover thoughts about how this affects the various modes mac80211 can operate in (AP, STA, IBSS, MESH, WDS, ...); if it's not implemented for all modes it should come with an explanation of how such implementations would be possible in the future should they become necessary. I'm not sure how to actually collect this documentation, parts of it (like the "how to implement feature X we have in STA mode for AP mode") certainly should be part of the kernel tree, other things need not be. Comments? johannes
Attachment:
signature.asc
Description: This is a digitally signed message part
