On Wed, 21 Sep 2016 17:03:24 -0700 Tom Herbert <tom@xxxxxxxxxxxxxxx> wrote: > On Tue, Sep 20, 2016 at 2:08 AM, Jesper Dangaard Brouer > <brouer@xxxxxxxxxx> wrote: > > Hi all, > > > > As promised, I've started documenting the XDP eXpress Data Path): > > > > [1] https://prototype-kernel.readthedocs.io/en/latest/networking/XDP/index.html > > > > IMHO the documentation have reached a stage where it is useful for the > > XDP project, BUT I request collaboration on improving the documentation > > from all. (Native English speakers are encouraged to send grammar fixes ;-)) > > > Hi Jesper, > > Thanks for taking the initiative on the this, The document reads more > like a design doc than description right now, that's probably okay > since we could use a design doc. Yes, I fully agree. I want to state very clearly, this document is not an attempt to hijack the XDP project and control the "spec". This is an attempt to collaborate. We discuss things on the mailing list, each with our own vision of the project, and most times we reach an agreement. But nobody document this agreement. Month later, we make implementation choices that goes against these agreements, because we simply forgot. If someone remembers, we have to reiterate the same arguments again (like it just happened with the XDP_ABORTED action, my mistake). And can anybody remember the consensus around VLANs, it never got implemented that way... I had to start the doc project somewhere, so I dumped my own vision into the docs, and what I could remember from upstream discussions. I need collaboration from others to adjust and "fix" my vision of the project, into something that becomes a common ground we all can agree on. If some part of the docs provoke you, good, then you have a reason to correct and fix it. I'll do my best to keep an very open-mind about any changes. This should be a very "live" document. > Under "Important to understand" there are some disclaimers that XDP > does not implement qdiscs or BQL and fairness otherwise. This is true > for it's own traffic, but it does not (or at least should not) affect > these mechanisms or normal stack traffic running simultaneously. I > think we've made assumptions about fairness between XDP and non-XDP > queues, we probably want to clarify fairness (and also validate > whatever assumptions we've made with testing). I love people pointing out mistakes in the documentation. I want update this ASAP when people point it out. I'll even do the work of integrating and committing these changes, for people too lazy to git clone the repo themselves. For you section Tom, I fully agree, but I don't know how to formulate and adjust this in the text. For people that want to edit the docs, notice the link "Edit on GitHub" which takes you directly to the file you need to edit... > > You wouldn't believe it: But this pretty looking documentation actually > > follows the new Kernel documentation format. It is actually just > > ".rst" text files stored in my github repository under kernel/Documentation [2] > > > > [2] https://github.com/netoptimizer/prototype-kernel/tree/master/kernel/Documentation > > > > Thus, just git clone my repository and started editing and send me > > patches (or github pull requests). Like: > > > > $ git clone https://github.com/netoptimizer/prototype-kernel > > $ cd prototype-kernel/kernel/Documentation/ > > $ make html > > $ firefox _build/html/index.html & > > > > This new documentation format combines the best of two worlds, pretty > > online browser documentation with almost plain text files, and changes > > being tracked via git commits [3] (and auto git hooks to generate the > > readthedocs.org page). You got to love it! :-) > > > > -- > > Best regards, > > Jesper Dangaard Brouer > > MSc.CS, Principal Kernel Engineer at Red Hat > > Author of http://www.iptv-analyzer.org > > LinkedIn: http://www.linkedin.com/in/brouer > > > > [3] https://github.com/netoptimizer/prototype-kernel/commits/master -- Best regards, Jesper Dangaard Brouer MSc.CS, Principal Kernel Engineer at Red Hat Author of http://www.iptv-analyzer.org LinkedIn: http://www.linkedin.com/in/brouer -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
