On Tue 30-01-18 18:38:38, Matthew Wilcox wrote: > On Tue, Jan 30, 2018 at 04:28:50PM +0200, Mike Rapoport wrote: > > On Tue, Jan 30, 2018 at 02:41:41PM +0100, Michal Hocko wrote: > > > It is good to hear that at least something has a documentation coverage. > > > I was asking mostly because I _think_ that the API documentation is far > > > from the top priority. > > > > API documentations is important for kernel developers who are not deeply > > involved with mm. When one develops a device driver, knowing how to > > allocate and free memory is essential. And, while *malloc are included in > > kernel-api.rst, CMA and HMM documentation is not visible. > > > > > We are seriously lacking any highlevel one which describes the design and > > > subsytems interaction. > > > > I should have describe it better, but by "creating a new structure for mm > > documentation" I've also meant adding high level description. > > We should be really clear what kind of documentation we're trying to create. > > There are four distinct types of documentation which would be useful: > > - How, when and why to use the various function calls and their > parameters from the perspective of a user outside the mm/ hierarchy. > Device driver authors, filesystem authors and others of their ilk. > - The overall philosophy and structure of the mm directory, what it does, > why it does it, perhaps even outlines of abandoned approaches. > - What functionality the mm subsystem requires from others. For example, > what does the mm rely on from the CPU architectures (and maybe it would > make sense to also include services the mm layer provides to arches in > this section, like setting up sparsemem). yes > - How to tweak the various knobs that the mm subsystem provides. > Maybe this is all adequately documented elsewhere already. This would be Documentation/sysctl/vm.txt which is one that is at least close to be complete. > Perhaps others can think of other types of documentation which would > be useful. - design documentation of various parts of the MM - reclaim, memory hotplug, memcg, page allocator, memory models, THP, rmap code (you name it) > That shouldn't detract from my main point, which is that > saying "Now we have mm documentation" is laudable, but not enough. Absolutely agreed. -- Michal Hocko SUSE Labs -- To unsubscribe, send a message with 'unsubscribe linux-mm' in the body to majordomo@xxxxxxxxx. For more info on Linux MM, see: http://www.linux-mm.org/ . Don't email: <a href=mailto:"dont@xxxxxxxxx";> email@xxxxxxxxx </a>
