Re: [LSF/MM TOPIC] mm documentation

[Mike Rapoport <rppt@linux.vnet.ibm.com>]

On Wed, Jan 31, 2018 at 10:00:37AM +0100, Michal Hocko wrote:
> 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.

I don't think anybody is saying "we have mm documentation", at least in the
sense "mm is well documented".

One of my points was that bringing some order to the existing bits of the
documentation is an important step forward and it does not contradict
necessity to add documentation you and Matthew described here.

> -- 
> Michal Hocko
> SUSE Labs
> 
> --
> To unsubscribe, send a message with 'unsubscribe linux-mm' in
> the body to majordomo@kvack.org.  For more info on Linux MM,
> see: http://www.linux-mm.org/ .
> Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>
> 

-- 
Sincerely yours,
Mike.

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>