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

classic Classic list List threaded Threaded
44 messages Options
123
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

URL:
  <http://savannah.nongnu.org/task/?7068>

                 Summary: lwIP docs: Update, improve, add documentation about
using lwIP
                 Project: lwIP - A Lightweight TCP/IP stack
            Submitted by: jgrubb
            Submitted on: Monday 07/09/2007 at 09:47
                Category: Documentation
         Should Start On: Monday 07/09/2007 at 00:00
   Should be Finished on: Monday 07/09/2007 at 00:00
                Priority: 5 - Normal
                  Status: None
                 Privacy: Public
        Percent Complete: 0%
             Assigned to: None
             Open/Closed: Open
         Discussion Lock: Any
                  Effort: 0.00

    _______________________________________________________

Details:

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.



    _______________________________________________________

File Attachments:


-------------------------------------------------------
Date: Monday 07/09/2007 at 09:47  Name: rx_flow.tex  Size: 13kB   By: jgrubb

<http://savannah.nongnu.org/task/download.php?file_id=13273>
-------------------------------------------------------
Date: Monday 07/09/2007 at 09:47  Name: rx_flow.pdf  Size: 54kB   By: jgrubb

<http://savannah.nongnu.org/task/download.php?file_id=13274>

    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

Follow-up Comment #1, task #7068 (project lwip):

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'.

    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Nachricht geschickt von/durch Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

Follow-up Comment #2, task #7068 (project lwip):

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)
    _______________________________________________________

Additional Item Attachment:



    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message posté via/par Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

Goldschmidt Simon

> 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...
>

Freeze? Now? We should really talk about the new timers before releasing
a new version, since that
breaks compatibility!

Checksum on copy is on the way, so that should make it into a new
release, too.
Ip_frag changes should go in, too.
The rest of the tasks and most of the bugs can be delayed I think.

Once we have the timers, freezing could be a good thing to release a new
version and update
the documentation for it.

Before that, should we 'filter' all bugs & tasks to only process
priorities > 3?


Simon



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2
In reply to this post by David GIRAULT-2

Follow-up Comment #3, task #7068 (project lwip):

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 :)

    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

Follow-up Comment #4, task #7068 (project lwip):

>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.



    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message posté via/par Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

Follow-up Comment #5, task #7068 (project lwip):

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)
    _______________________________________________________

Additional Item Attachment:



    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

Follow-up Comment #6, task #7068 (project lwip):

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)
    _______________________________________________________

Additional Item Attachment:



    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

Follow-up Comment #7, task #7068 (project lwip):

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

    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

Update of task #7068 (project lwip):

                Priority:              5 - Normal => 7 - High              
         Planned Release:                    None => 1.3.0                  


    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

Follow-up Comment #8, task #7068 (project lwip):

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?

    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message posté via/par Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

Follow-up Comment #9, task #7068 (project lwip):

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

    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

Follow-up Comment #10, task #7068 (project lwip):

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.

    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

Follow-up Comment #11, task #7068 (project lwip):

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...


    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message posté via/par Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

Follow-up Comment #12, task #7068 (project lwip):

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?

    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

Follow-up Comment #13, task #7068 (project lwip):

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)
    _______________________________________________________

Additional Item Attachment:



    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

Follow-up Comment #14, task #7068 (project lwip):

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)
    _______________________________________________________

Additional Item Attachment:



    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message posté via/par Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

Follow-up Comment #15, task #7068 (project lwip):

I like your changes, Frederic.

    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

Follow-up Comment #16, task #7068 (project lwip):

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



    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message posté via/par Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

David GIRAULT-2

Follow-up Comment #17, task #7068 (project lwip):

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)
    _______________________________________________________

Additional Item Attachment:



    _______________________________________________________

Reply to this item at:

  <http://savannah.nongnu.org/task/?7068>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.nongnu.org/



_______________________________________________
lwip-devel mailing list
[hidden email]
http://lists.nongnu.org/mailman/listinfo/lwip-devel
123