tasklwIP - A Lightweight TCP/IP stack - Tasks: task #7068, lwIP docs: Update, improve, add...

 
 

You are not allowed to post comments on this tracker with your current authentication level.

task #7068: lwIP docs: Update, improve, add documentation about using lwIP

Submitter:  Jared Grubb <jgrubb>
Submitted:  Mon 09 Jul 2007 04:47:20 PM UTC
   
 
Category:  Documentation Should Start On:  Mon 09 Jul 2007 07:00:00 AM UTC
Should be Finished on:  Mon 09 Jul 2007 07:00:00 AM UTC Priority:  7 - High
Status:  None Privacy:  Public
Assigned to:  None Percent Complete:  0%
Open/Closed:  Closed Planned Release:  1.3.0
Effort:  0.00

Jump to the original submission

Sun 04 Nov 2007 11:43:13 AM UTC, comment #34: 

For this task (unlike the other two), I agree, since the summary is very geeric anyway (it doesn't remind us of something specific todo I mean).

Simon Goldschmidt <goldsimon>
Group administrator
Fri 02 Nov 2007 08:07:53 PM UTC, comment #33: 

Sounds good to me!

Jared Grubb <jgrubb>
Group Member
Fri 02 Nov 2007 06:51:22 PM UTC, comment #32: 

Since now, http://lwip.scribblewiki.com seems to be accessible to most of users, and since most of active developers have an account on it, I propose to close this task to avoid to have multiple place to centralize the documentation. No objections?

Frédéric Bernon <fbernon>
Group Member
Wed 25 Jul 2007 01:09:46 PM UTC, comment #31: 
Frédéric Bernon <fbernon>
Group Member
Fri 20 Jul 2007 03:08:19 PM UTC, comment #30: 

We've been making good progress on the doc project at the Wiki. If you havent looked at it in a few days, check it out. I have started to go through the protocols, starting with ARP:

http://lwip.scribblewiki.com/ARP

I have put up a similar outline on all the protocols. I need your help to describe the "status" of each of these protocols in recent lwIP history. I am proposing that we have one or two lines about each protocol, as it stands in both CVS HEAD and in 1.2. If you are ambitious and want to give more history for 1.1.1, etc, please do!

For example, ARP is marked "STABLE". We could also use language like "Untested", "Incomplete", etc, for various protocols.

Look around the Wiki, and chime in on some of these protocols. If you want to chime in but don't want to learn how to edit the pages, you can email me with your thoughts on the protocols.

Jared Grubb <jgrubb>
Group Member
Wed 18 Jul 2007 03:08:54 PM UTC, comment #29: 


> is it possible with scribblewiki to "extract" files documentation in html if we want to produce any off-line doc?
>is it possible to backup them, restore, etc...
>If Savannah proposed a wiki extension of current site
> (from Kieran) I'd like to still ship a copy in each

release

It is possible to export the pages as XML (which are then in a format to import them into a new MediaWiki, i.e. if Savannah ever got one installed for us).

As far as formats that are printable... This site has information on lots of ways to convert a MediaWiki to another format:
http://meta.wikimedia.org/wiki/Alternative_parsers
But:

  • The problem is we can't use these on the Scribblewiki server because they dont have a way for us to install our own tools. To do that we have to have our own server.
  • One of us could install a MediaWiki on a local machine, export the entire site, import it into a local MediaWiki that is able to do these fancy things. This would be a bit of work, but would (possibly) only need to be done once per release, right?


> Is it possible to limit access to some peoples


I didn't find a free wiki server that lets us do that. Scribblewiki will give us that much control (and maybe even the ability to add that feature I talked about earlier) for $5/month. (I can keep searching... and if we find one, it will be "easy" to move existing content over)

MediaWiki is the engine that runs Wikipedia. There is a way to protect individual pages from anonymous (or even logged in) edits. This would have to be added to EVERY page (which isn't too hard), but it would not protect against an anonymous user creating his own page from scratch (but there would be no links to it from our pages, so it would be effectively "hidden")

> get notifications emails about changes


In a MediaWiki, you can "watch" a page, and then go to your "Watchlist" to see all changes made to those pages. THere is an option that you can set to send you an email when pages on your watchlist change.

> a block of links in the wiki ("outside" the lwIP ones) can be useful, for generic TCP/IP, network, references, C language, etc...


Absolutely. I was also imagining that each protocol's page could have a box of links, to RFC's, etc.

Jared Grubb <jgrubb>
Group Member
Wed 18 Jul 2007 12:28:04 PM UTC, comment #28: 

I think a block of links in the wiki ("outside" the lwIP ones) can be useful, for generic TCP/IP, network, references, C language, etc...

Frédéric Bernon <fbernon>
Group Member
Wed 18 Jul 2007 08:06:44 AM UTC, comment #27: 

About wiki, I think it's good for cooperative edition, but I don't feel that very good if you want to print the doc (to read it on the beach by example... ;). So, question, is it possible with scribblewiki  to "extract" files documentation in html if we want to produce any off-line doc?

Next, to test it (I suppose we evaluate this solution in a first time?), I do some little changes on the wiki (on the Intro text). My question is about "security" of changes. Is it possible to limit access to some peoples like an Savannah, and to get notifications emails about changes? Be example, how do you know "I" change some details (since, I wasn't logged), without having to poll the "change" menu? As you see, I'm not an expert of wiki tools.

Do you have look for maintenance of the files (is it possible to backup them, restore, etc...)?

>(of course we can undo the wiki at any point if you all object or want it somewhere else)


If Savannah proposed a wiki extension of current site (as you said in comment #24), It would be wonderful, but, if they don't, the one you propose is good for me.


Frédéric Bernon <fbernon>
Group Member
Tue 17 Jul 2007 10:58:00 PM UTC, comment #26: 

(of course we can undo the wiki at any point if you all object or want it somewhere else)

Jared Grubb <jgrubb>
Group Member
Tue 17 Jul 2007 10:53:30 PM UTC, comment #25: 

Good news! I finally found a couple free wiki hosting sites. I looked for common features and decent support (i.e., needs to use MediaWiki 1.10), and decided this one seemed to support what we want to do.

http://lwip.scribblewiki.com/

I will be uploading some of the docs already proposed soon.

Jared Grubb <jgrubb>
Group Member
Mon 16 Jul 2007 09:23:15 PM UTC, comment #24: 


> Isn't there some free wiki like free savannah somwhere?


I've submitted a support request. It looks like Savannah was asked this a year ago and it was noted but "low priority".

As far as free wikis out there, I found openserving.com, which may be able to host it. Any other ideas?

Jared Grubb <jgrubb>
Group Member
Mon 16 Jul 2007 08:33:41 PM UTC, comment #23: 


> What would be really cool is if we could use a Wiki. But then we'd need server space somewhere.


Isn't there some free wiki like free savannah somwhere?

Simon Goldschmidt <goldsimon>
Group administrator
Mon 16 Jul 2007 07:43:46 PM UTC, comment #22: 

If we use HTML for our docs, then the changes would have to be submitted via CVS.

What would be really cool is if we could use a Wiki. But then we'd need server space somewhere.

Jared Grubb <jgrubb>
Group Member
Mon 16 Jul 2007 07:39:41 PM UTC, comment #21: 

How do we submit changes/extensions to the docs, do you commit them to CVS?

Simon Goldschmidt <goldsimon>
Group administrator
Mon 16 Jul 2007 01:52:43 AM UTC, comment #20: 

Attached is "Port to OS" for the developer docs:

  • dev-port.html


(file #13351)

Jared Grubb <jgrubb>
Group Member
Sun 15 Jul 2007 04:28:03 PM UTC, comment #19: 

Attached is a draft for the netif management section for application developers. The formatting is a bit awkward until we make a nice-looking CSS for the docs.

  • app-netif.html


(file #13346)

Jared Grubb <jgrubb>
Group Member
Sat 14 Jul 2007 04:59:56 PM UTC, comment #18: 

( I did contact Adam and received permission to use his materials a base for our docs )

Jared Grubb <jgrubb>
Group Member
Sat 14 Jul 2007 03:53:51 PM UTC, comment #17: 

Attached:

  • app-intro.html
  • app-pbuf.html


Much of the content has been graciously ripped from Adam's PDF (goal 1: get something written; goal 2: come back later and do editing) and updated for the current code base.

I cut some images and am working on a CSS file, so the pbuf file may not appear exactly right, but the content will be there.

(file #13340, file #13341)

Jared Grubb <jgrubb>
Group Member
Sat 14 Jul 2007 03:11:45 PM UTC, comment #16: 

About HTTP server sample, I should be good to add the same with socket layer (even if it can be more usual).

Some links useful we often used to work:

http://www.opengroup.org/onlinepubs/007908799/index.html
http://www.faqs.org/rfcs/

There is also http://lists.gnu.org/archive/html/lwip-users/ , useful to reference email from the mailing list


Frédéric Bernon <fbernon>
Group Member
Sat 14 Jul 2007 08:28:25 AM UTC, comment #15: 

I like your changes, Frederic.

Jared Grubb <jgrubb>
Group Member
Sat 14 Jul 2007 08:14:07 AM UTC, comment #14: 

I propose you another "topics" documentation. The difference is mainly in the "application documentation", because I think it's not useful to explain pbuf to a socket users by example, etc... The idea is "read only what you need", but, this is not very different from yours...


(file #13339)

Frédéric Bernon <fbernon>
Group Member
Sat 14 Jul 2007 01:32:45 AM UTC, comment #13: 

Attached is a draft HTML file that will be the top-level document for lwIP documenation. I propose will go in lwip/doc directory.

I borrowed a basic outline from Adam's PDF, and added in other topics that I thought would be helpful. As much as possible, I propose we borrow from the sources we already have (Adam's PDF, the txt files in doc, and various gems from the mailing lists) and create new HTML files in lwip/doc to link to for the topics on the list.

Primary focus is on Application docs, secondary Platform docs, with the lwIP internal stuff coming much later.

(file #13337)

Jared Grubb <jgrubb>
Group Member
Fri 13 Jul 2007 10:09:57 PM UTC, comment #12: 

I marked the doc as "Approved" and now it appears at the bottom of the "Docs" page. How did someone add the categories for bugs/tasks/etc? Should be the same process, no?

Jared Grubb <jgrubb>
Group Member
Fri 13 Jul 2007 10:05:22 PM UTC, comment #11: 

Ok, we can see it, but it's not an easy access. Kieran, is it possible to change this part of the documentation menu? I see that doing a filter on "Category" could work (other don't seems to be supported by Savannah and give php errors), but there is only "None" in the "Category" list...

Frédéric Bernon <fbernon>
Group Member
Fri 13 Jul 2007 06:28:43 PM UTC, comment #10: 

I have attempted to add the CVS PDF you posted to teh "Documentation" tree. Can you see it? You may have to go to "Edit" in order to see the list.

Jared Grubb <jgrubb>
Group Member
Fri 13 Jul 2007 04:24:19 PM UTC, comment #9: 

(another addition, per a note from Frederic, on explaining debugs: http://lists.gnu.org/archive/html/lwip-users/2007-06/msg00027.html)

Jared Grubb <jgrubb>
Group Member
Fri 13 Jul 2007 01:32:35 PM UTC, comment #8: 

There is a "Documentation" part in the web main menu, but with links like "Delays on update", "Markup Reminder", etc... Isn't it possible to use it to post lwIP documentations?

Frédéric Bernon <fbernon>
Group Member
Fri 13 Jul 2007 11:37:25 AM UTC, comment #7: 

If you could check this into the apps directory in the contrib module, that would be great.

Kieran Mansley <kieranm>
Group Member
Thu 12 Jul 2007 05:56:51 PM UTC, comment #6: 

Frederic pointed out a bug in the HTTP code (need to call netconn_delete(newconn) instead of netconn_delete(conn) -- I moved the call out of http_server_serve and forgot to change it)
Attached is fixed version.

(file #13312)

Jared Grubb <jgrubb>
Group Member
Thu 12 Jul 2007 05:35:54 PM UTC, comment #5: 

Attached is an example HTTP server, based on the original in Adam's PDF, but updated to match current API (most notably the call to netbuf_delete!). Of course, I think I did it all right, but someone else should look over this just to make sure.

(file #13310)

Jared Grubb <jgrubb>
Group Member
Tue 10 Jul 2007 05:22:14 PM UTC, comment #4: 


>I remember searching the mailing list to try to figure out the "proper" lwIP init sequence and never getting a complete answer.


It's an usual question. We have already propose to simplify lwIP initialization with a "lwip_init" function, or by extending tcpip_init. But there was some objections about that (see https://savannah.nongnu.org/patch/index.php?5785, but this is not the only one).

>Also, a doc on the lwIP options would be nice.

What!!! opts.h is not clear enought? ;) The two first links in comment #2 give some tips, but it's not a full guidelines...

>lwIP is changing quickly, but even slightly out-of-date docs are better than none. For example, Adam's 6.5-year-old PDF was a great help to me.


Perhaps we could open a task per release, like "lwIP 1.3.0 documentation", where we could update any doc for this release. Adam's PDF is useful for main ideas, but it's really obsolete on some parts.

>I am willing to take on the task to start putting together some docs into the docs/ dir of the CVS tree (with a HTML TOC perhaps). Maybe I can get some good stuff together in time for 1.3 :)


I think the job to document the current release can be start once you will be sure that part you document will no change. That's why I can just tell you to wait a little bit to avoid to document some parts for nothing... But I think that your job will be very useful.


Frédéric Bernon <fbernon>
Group Member
Tue 10 Jul 2007 05:01:07 PM UTC, comment #3: 

I would love to see the flowcharts.

I think collecting all these docs into one place would be a major help. I remember searching the mailing list to try to figure out the "proper" lwIP init sequence and never getting a complete answer. Also, a doc on the lwIP options would be nice.

lwIP is changing quickly, but even slightly out-of-date docs are better than none. For example, Adam's 6.5-year-old PDF was a great help to me.

I am willing to take on the task to start putting together some docs into the docs/ dir of the CVS tree (with a HTML TOC perhaps). Maybe I can get some good stuff together in time for 1.3 :)

Jared Grubb <jgrubb>
Group Member
Tue 10 Jul 2007 07:35:37 AM UTC, comment #2: 

Mumtaz Ahmad had provided to users who ask him his flow charts, and they are a good help. I will ask him if he can post them here.

Here, some others links I post on the mailing list:

http://lists.gnu.org/archive/html/lwip-users/2006-11/msg00007.html // tune some TCP options (read all the thread) http://lists.gnu.org/archive/html/lwip-users/2007-04/msg00056.html // Reduce footprint (read all the thread)

http://savannah.nongnu.org/task/?1549 // See the Simon Goldschmidt's big job to document lwIP functions (I have attach a PDF doxygen doc.)

http://savannah.nongnu.org/task/?6683 // Some tips about lwIP thread safety http://savannah.nongnu.org/patch/index.php?5960 // Some tips about lwIP thread safety (more recent)

The problem is that the current release is very "alive". So, it's difficult to have an updated documentation. That's why I'm in flavor to "freeze" a release in some weeks, since there is lot of changes since 1.2.0...


(file #13279)

Frédéric Bernon <fbernon>
Group Member
Tue 10 Jul 2007 06:55:56 AM UTC, comment #1: 

The PDF is a good start!

I think the example code and example ports + good documentation on porting (and the sys_arch) is very important to users beginning with lwIP. The state machines are also very useful, but it's more an 'internal' documentation, not for the 'user'.

Simon Goldschmidt <goldsimon>
Group administrator
Mon 09 Jul 2007 04:47:20 PM UTC, original submission:  

As a newcomer to lwIP, the docs are MUCH better than the competition out there, but more documentation on how to use lwIP would be useful. The learning curve is not bad, but it could be improved. I see the following areas of improvement:

  • Example code (e.g., HTTP server code needs updated)
  • Architectural notes (e.g., the doc attached)
  • Implementation note (e.g., sys_arch should explain a bit more about sys_timeouts)
  • Update/expand the PDF Adam wrote, if he'll let us


Example:
I have attached a draft TeX/PDF I made this weekend. I had trouble keeping straight where thread context changes happened and what was done where. This document is a flow chart for the path an incoming frame/packet takes through the stack. It's not polished, but it's a good start and is in LaTeX, so is "easily" updated and maintained.

Jared Grubb <jgrubb>
Group Member

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attached Files
file #13351:  dev-port.html added by jgrubb (14KiB - text/html)
file #13346:  app-netif.html added by jgrubb (5KiB - text/html)
file #13340:  app-intro.html added by jgrubb (3KiB - text/html - First go's at the application docs)
file #13341:  app-pbuf.html added by jgrubb (9KiB - text/html - First go's at the application docs)
file #13339:  index.html added by fbernon (3KiB - text/html)
file #13337:  index.html added by jgrubb (2KiB - text/html)
file #13312:  httpserver.c added by jgrubb (2KiB - text/plain)
file #13310:  httpserver.c added by jgrubb (2KiB - text/plain)
file #13279:  lwip-doc.CVS_HEAD.pdf added by fbernon (137KiB - application/pdf)
file #13273:  rx_flow.tex added by jgrubb (13KiB - application/octet-stream)
file #13274:  rx_flow.pdf added by jgrubb (54KiB - application/pdf)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by kieranm (Posted a comment)
  • -email is unavailable- added by fbernon (Updated the item)
  • -email is unavailable- added by goldsimon (Posted a comment)
  • -email is unavailable- added by jgrubb (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

     

    Follow 14 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2007-11-04 fbernon Open/ClosedOpen Closed
    2007-07-16 jgrubb Attached File- Added dev-port.html, #13351
    2007-07-15 jgrubb Attached File- Added app-netif.html, #13346
    2007-07-14 jgrubb Attached File- Added app-intro.html, #13340
        Attached File- Added app-pbuf.html, #13341
    2007-07-14 fbernon Attached File- Added index.html, #13339
    2007-07-14 jgrubb Attached File- Added index.html, #13337
    2007-07-13 kieranm Priority5 - Normal 7 - High
        Planned ReleaseNone 1.3.0
    2007-07-12 jgrubb Attached File- Added httpserver.c, #13312
    2007-07-12 jgrubb Attached File- Added httpserver.c, #13310
    2007-07-10 fbernon Attached File- Added lwip-doc.CVS_HEAD.pdf, #13279
    2007-07-09 jgrubb Attached File- Added rx_flow.tex, #13273
        Attached File- Added rx_flow.pdf, #13274

    Back to the top

    Powered by Savane 3.13-4448.
    Corresponding source code