Re: The NuttX Handbook

[Nathan Hartman]

On Tue, Apr 25, 2023 at 3:12 PM Brennan Ashton 
wrote:

> On Tue, Apr 25, 2023, 7:45 PM Tomek CEDRO  wrote:
>
> > On Tue, Apr 25, 2023 at 8:14 PM Gregory Nutt wrote:
> > > Tomasz Cedro now owns nuttx.com and nuttx.org.
> >
> > Yes the domains are for the project use, just let me know how you want
> > them configured, at this point they redirect to the main project site
> > :-)
> >
> > I was thinking about maybe some showcases of the projects and products
> > made with NuttX at nuttx.com? That could present solid real world
> > applications and gather more interest around the project?
> >
>
> Why would we not use the real project website for this?  I think it is
> correct that they should just redirect to the Apache NuttX domain.
>
> The framework for the website supports blog articles but no one has ever
> added one.
> They would be added here
> https://github.com/apache/nuttx-website/tree/master/_posts the CI will
> then
> run generate the artifacts and publish as needed.
>
> Let's try to have less places where there are things not more. So far
> everything I have heard can be done with what we already have is just a
> matter of people creating content, not adding more tools, sites, etc... We
> also have to be mindful of official project work being hosted within the
> Apache organization.
>
> --Brennan


Big +1 to this from me! Let's try to make the information people need
easier to find. :-)

Cheers
Nathan

Re: SAMA5 secure fuse controller driver

[Tomek CEDRO]

On Tue, Apr 25, 2023 at 9:17 PM Gregory Nutt wrote:
> Searching for C files with "fuse" in the number under arch/, I find
> drivers for the ESP32,  ESP32S2, ESP32S3, ESP32C3, BL602, and RTL8720C
>
> Other MCUs have have fuse header files, but no C drivers.
>
> There are alias like OTP (i.MXRT).  PIC32s all have fuses in DEVCFG.   I
> am sure that other MCUs have things like fuses as well using various
> other names.
>
> But I don't think that there is any particular need to be similar to
> other implementations.  There is no common fuse interface.

I have noted down the enhancement request for Common eFuse Interface :-)

https://github.com/apache/nuttx/issues/9097

-- 
CeDeROM, SQ7MHZ, http://www.tomek.cedro.info

Re: SAMA5 secure fuse controller driver

[Gregory Nutt]

On 4/25/2023 12:32 PM, Tim Hardisty wrote:

The SAMA5 support has no driver for the secure fuse peripheral. Kconfig allows 
you to “enable” it but there’s no underlying code.

Before I go ahead and create a character driver for this, is the omission for a 
“good” reason?

The driver would handle the relatively straightforward management of 
programming the fuses, as well as obviously allowing you to read values. If 
another arch has anything similar please point me in its direction so I can 
create one that’s similar.

Thanks,

TimJTi.


Searching for C files with "fuse" in the number under arch/, I find 
drivers for the ESP32,  ESP32S2, ESP32S3, ESP32C3, BL602, and RTL8720C


Other MCUs have have fuse header files, but no C drivers.

There are alias like OTP (i.MXRT).  PIC32s all have fuses in DEVCFG.   I 
am sure that other MCUs have things like fuses as well using various 
other names.


But I don't think that there is any particular need to be similar to 
other implementations.  There is no common fuse interface.

Re: The NuttX Handbook

[Brennan Ashton]

On Tue, Apr 25, 2023, 7:45 PM Tomek CEDRO  wrote:

> On Tue, Apr 25, 2023 at 8:14 PM Gregory Nutt wrote:
> > Tomasz Cedro now owns nuttx.com and nuttx.org.
>
> Yes the domains are for the project use, just let me know how you want
> them configured, at this point they redirect to the main project site
> :-)
>
> I was thinking about maybe some showcases of the projects and products
> made with NuttX at nuttx.com? That could present solid real world
> applications and gather more interest around the project?
>

Why would we not use the real project website for this?  I think it is
correct that they should just redirect to the Apache NuttX domain.

The framework for the website supports blog articles but no one has ever
added one.
They would be added here
https://github.com/apache/nuttx-website/tree/master/_posts the CI will then
run generate the artifacts and publish as needed.

Let's try to have less places where there are things not more. So far
everything I have heard can be done with what we already have is just a
matter of people creating content, not adding more tools, sites, etc... We
also have to be mindful of official project work being hosted within the
Apache organization.

--Brennan

Re: The NuttX Handbook

[Tomek CEDRO]

On Tue, Apr 25, 2023 at 8:14 PM Gregory Nutt wrote:
> Tomasz Cedro now owns nuttx.com and nuttx.org.

Yes the domains are for the project use, just let me know how you want
them configured, at this point they redirect to the main project site
:-)

I was thinking about maybe some showcases of the projects and products
made with NuttX at nuttx.com? That could present solid real world
applications and gather more interest around the project?


> One use of nuttx.org
> might be to use it to provide such a open, collaborative Wiki.  A
> gitbook might be better option.

Whatever tool works best :-) If we have online html access and can
perform some automation to gather everything we need in a single PDF
then its also cool :-) I must admit I have no experience with GitBook
o_O

The question remains on the tools selection (what platform to use),
integration with the source tree (if necessary), administration,
updates, backups, and moderation.. maybe GitHub is not that bad as
there is already some sort of users filtering, content moderation /
review / approval, integration of the documentation with the source
code, automation with CI, and no administration problems.

Documentation stored in a git repository along with the source code
may produce higher quality results and its seems a common approach.
Forums and wikis are good to talk, but they tend to get outdated
fast.. and gets lots of spam bots, shitstorms, and other things that
are not really on point with the project. Also it would distract
communications from the mailing list. Central points are good to keep
things coherent and in-sync.

But if the GitBook is verified Free and Open-Source tool that would
allow easier and faster editing, export to html and pdf, then why not?

Is it possible to create a dedicated github repository that could host
GitBook files and provide a frontend at given URL?

Was this considered before? :-)


>  Apparently Brennan Ashton created on
> https://cwiki.apache.org/confluence/display/NUTTX/Nuttxbook but the
> links there all get 404 error.

I could not find that project by GitLab search engine either. This is
the biggest danger of "external" resources they tend to disappear at
some point. This is probably the reason why current documentation is
kept with the source code in one place..?


--
CeDeROM, SQ7MHZ, http://www.tomek.cedro.info

SAMA5 secure fuse controller driver

[Tim Hardisty]

The SAMA5 support has no driver for the secure fuse peripheral. Kconfig allows 
you to “enable” it but there’s no underlying code.

Before I go ahead and create a character driver for this, is the omission for a 
“good” reason?

The driver would handle the relatively straightforward management of 
programming the fuses, as well as obviously allowing you to read values. If 
another arch has anything similar please point me in its direction so I can 
create one that’s similar.

Thanks,

TimJTi.

Re: The NuttX Handbook

[Brennan Ashton]

On Tue, Apr 25, 2023, 7:14 PM Gregory Nutt  wrote:

> On 4/25/2023 11:38 AM, Nathan Hartman wrote:
>
>  > I like the idea of keeping documentation in sync with the code(as much
> as
>  > possible given our volunteer-based project).
>
> I wouldn't make a plan that depends on that.  Engineers are notoriously
> bad at maintaining documentation.  And international projects like this
> one also have language issues.
>
> I presume that English is the language for NuttX documentation?  In the
> past we did have partial ports of the DocuWiki to Portuguese and
> Turkish, but I think English has been the primary language.
>
> The majority of NuttX contributors may not be fluent in English. They
> may speak only their native language or may have limitations in their
> English skills.  You can see this in the complete absence of comments in
> sections of code.
>
> So (1) you can never be assured that code is even close to
> self-documenting and (2) you have to assume the burden of any
> documentation effort will fall on the native English speakers and those
> with very good English-as-a-second-language skills.
>
>  > Regarding the CWIKI, suppose we want to document something in
> particular.
>  > The CWIKI can be a good place for several people to put it together with
>  > realtime collaboration without having to deal with GitHub PRs and
> whatever,
>  > and when it gets close to ready, it can be migrated into Documentation.
>  > This is what we've been doing with the Release Notes and it seems to
> work
>  > well.
>
> AFAIK no one contributes to the CWIKI.  I have always wanted to have
> community-based documentation development like you could get with a
> Wiki.  There were several contributors to the old DocuWiki but I would
> not consider it successful in this regard either.
>
> As I recall, it is not a simple matter for a non-committer in the
> community to get access to Confluence in order to modify the Wiki. Is
> that correct?
>

You have to make an Apache account now because the amount of spam the wiki
was seeing was too high. Unless we want to get in the moderation business I
expect to see a lot of that on any wiki these days (I even had to turn off
comments on my captcha protected blog no one reads). If anyone does
have something they want to add to the wiki that we are not porting to the
repo I'm happy to help get them setup. It has been useful as mentioned for
adhoc things like getting the release notes together.

--Brennan

>

Re: The NuttX Handbook

[Gregory Nutt]

On 4/25/2023 11:38 AM, Nathan Hartman wrote:

> I like the idea of keeping documentation in sync with the code(as much as
> possible given our volunteer-based project).

I wouldn't make a plan that depends on that.  Engineers are notoriously 
bad at maintaining documentation.  And international projects like this 
one also have language issues.


I presume that English is the language for NuttX documentation?  In the 
past we did have partial ports of the DocuWiki to Portuguese and 
Turkish, but I think English has been the primary language.


The majority of NuttX contributors may not be fluent in English. They 
may speak only their native language or may have limitations in their 
English skills.  You can see this in the complete absence of comments in 
sections of code.


So (1) you can never be assured that code is even close to 
self-documenting and (2) you have to assume the burden of any 
documentation effort will fall on the native English speakers and those 
with very good English-as-a-second-language skills.


> Regarding the CWIKI, suppose we want to document something in particular.
> The CWIKI can be a good place for several people to put it together with
> realtime collaboration without having to deal with GitHub PRs and 
whatever,

> and when it gets close to ready, it can be migrated into Documentation.
> This is what we've been doing with the Release Notes and it seems to work
> well.

AFAIK no one contributes to the CWIKI.  I have always wanted to have 
community-based documentation development like you could get with a 
Wiki.  There were several contributors to the old DocuWiki but I would 
not consider it successful in this regard either.


As I recall, it is not a simple matter for a non-committer in the 
community to get access to Confluence in order to modify the Wiki. Is 
that correct?


Tomasz Cedro now owns nuttx.com and nuttx.org.  One use of nuttx.org 
might be to use it to provide such a open, collaborative Wiki.  A 
gitbook might be better option.  Apparently Brennan Ashton created on 
https://cwiki.apache.org/confluence/display/NUTTX/Nuttxbook but the 
links there all get 404 error.

Re: The NuttX Handbook

[Tomek CEDRO]

On Tue, Apr 25, 2023 at 7:38 PM Nathan Hartman wrote:
> On Tue, Apr 25, 2023 at 1:10 PM Tomek CEDRO wrote:
> > (..)
> > After some consideration a "safer" approach may be more desirable for now:
> >
> > 1. Migrate all documentation to a separate Documentation/ as it is
> > currently done, so we do not lose any content from
> > MediaWiki/README/CWIKI, we can add additional content that we need,
> > the documentation form is shaped to a satisfactory state, automation
> > is verified, nice references, tables of contents, sections, etc.
> > People will have solid documentation all the time and we cause no mess
> > and we can see how the work on doc goes in reality :-)
>
>
> Suggestion: The "separate" Documentation could be simply an "Unfinished" or
> "WorkInProgress" subdirectory inside Documentation. Just dump everything in
> there as quickly as possible and then gradually fixup and move sections to
> the right places.

Yes, having this kind archive would be cool. As for now I do not know
where are the archived documents and so I would mostly focus on simple
formatting fixes of the current documentation, while more important
things are still waiting to show up in the documentation :-)

Then we could move small parts piece by piece into the rst
Documentation from a single place, this way we could clearly see what
had been done and what is still left todo, but I prefer that Gurus
decide on this one :-)


> And then this:
>
> 2. When we have a well shaped "separate" documentation then it may be
> > the time to consider merging it with the source code, but not before,
> > if desired at all?
>
> doesn't require moving things from some other system into git. It will just
> become a rename within the repo.
> What do you think?

In future, when the documentation migration is ready, comments/remarks
put directly in the source code with Sphinx formatting could only
contain that specific file descriptions, nothing more, and then could
be gathered all together and attached to the Handbook in a form of a
dedicated section API Reference or similar attached to the "general"
documentation from the Documentation/ directory. So the final HTML/PDF
would contain "general" documentation (from the Documentation/) and
the "technical meat" (from all of the src/). I don't know how to do it
at this time but I saw this possible (i.e. Kivy) :-)


> I like the idea of keeping documentation in sync with the code(as much as
> possible given our volunteer-based project).

I can see now that merging the documentation itself is quite of a
challenge, so documenting the source code itself probably should be
left as future task. Small measurable steps towards big dreams :-)


> At the very least, documentation will be included in our release artifacts,
> so people will have docs "offline" when they download releases. I think
> that's a good thing.

Thank you Nathan, I also like the release-x.y.tar.gz and
release-x.y.pdf approach, maybe we can make it happen :-) :-)


> Regarding the CWIKI, suppose we want to document something in particular.
> The CWIKI can be a good place for several people to put it together with
> realtime collaboration without having to deal with GitHub PRs and whatever,
> and when it gets close to ready, it can be migrated into Documentation.
> This is what we've been doing with the Release Notes and it seems to work
> well.

Exactly, as access to wiki is restricted to PMC members (?) I think
only organization stuff should be put there, like notes, remarks,
scratchpads, task list, maybe some roadmap, and then, when necessary,
moved to documentation, I also work that way :-)


-- 
CeDeROM, SQ7MHZ, http://www.tomek.cedro.info

Re: The NuttX Handbook

[Tomek CEDRO]

On Tue, Apr 25, 2023 at 7:26 PM Brennan Ashton wrote:
> Eh I don't think we should pull the docs apart. Its a pain to manage
> especially with sphinx if we start sprinkling the docs all over the place.
> it's also hard in my opinion to write clear cohesive docs thare do not get
> highly repetitive if each section lives in isolation.

One remark :-P I saw nice documentation with Sphinx that had dedicated
doc/ place for general stuff like top level index examples tutorials
etc, and also Sphinx documented source code files that then consisted
to API Reference, so this is possible, just an idea for the future :-)

-- 
CeDeROM, SQ7MHZ, http://www.tomek.cedro.info

Re: The NuttX Handbook

[Nathan Hartman]

On Tue, Apr 25, 2023 at 1:10 PM Tomek CEDRO  wrote:

> On Tue, Apr 25, 2023 at 5:47 PM Brennan Ashton wrote:
> > On Tue, Apr 25, 2023, 3:18 PM Gregory Nutt wrote:
> > > My experience with using Deoxygen on large, projects has been
> > > disastrous.  People don't always maintain the tags to the documentation
> > > was wrong and so the auto-generated  documentation was not
> > > trust-worthy.  So you always end up looking at the code anyway.  There
> > > is nothing in the auto-generated code that is not in the the files so
> > > there is no real value added (there would be if you could trust it).
> > >
> > > Also, minor errors in the tags cause a lot of CI failures.  A couple
> per
> > > week.
> > >
> > > I suppose if documentation tags were added to all files and were all of
> > > the highest quality, it would be a good thing.   That that would be an
> > > enormous job and ongoing maintained of the documentation tags would be
> a
> > > problem:  Most people won't change them or put in useless, low value
> > > tags.  Much like PR comments. Or comments and documentation in general.
> > >
> > > If we could do it right, then +1 with a significant commitment of time
> > > and effort.  If we would do only a half-assed job, then -1.
> >
> > I _very_ much agree. I have very rarely found doxygen to be useful and
> > usually just results in unhelpful boilerplate to make the tool happy and
> > generates some html that no one will ever look at again.   It is usually
> > much better when someone spends the time to actually document the
> > interfaces and the why behind them (like man pages) we already have a
> > section in the docs for interfaces and it would be great as people extend
> > and adapt them to continue keeping these up to date.
>
> Okay, Doxygen is the past.. currently Sphinx is the way to go, no
> doubts, just an (not really convenient) example to keep doc in sync
> with src and that can be quite PITA :-)
>
>
> After some consideration a "safer" approach may be more desirable for now:
>
> 1. Migrate all documentation to a separate Documentation/ as it is
> currently done, so we do not lose any content from
> MediaWiki/README/CWIKI, we can add additional content that we need,
> the documentation form is shaped to a satisfactory state, automation
> is verified, nice references, tables of contents, sections, etc.
> People will have solid documentation all the time and we cause no mess
> and we can see how the work on doc goes in reality :-)


Suggestion: The "separate" Documentation could be simply an "Unfinished" or
"WorkInProgress" subdirectory inside Documentation. Just dump everything in
there as quickly as possible and then gradually fixup and move sections to
the right places.

And then this:

2. When we have a well shaped "separate" documentation then it may be
> the time to consider merging it with the source code, but not before,
> if desired at all?


doesn't require moving things from some other system into git. It will just
become a rename within the repo.

What do you think?


I like the idea of keeping documentation in sync with the code(as much as
possible given our volunteer-based project).

The biggest pro for keeping doc within src is to stay in sync, maybe
> to also have self documented source code. But there are also dangers
> here, like messing up the whole unfinished doc and the source code!!
> It would be wise to list all pros and cons and then after some time
> make some decisions but not necessarily right now.. :-)


At the very least, documentation will be included in our release artifacts,
so people will have docs "offline" when they download releases. I think
that's a good thing.

Pros:
> 1. It would be more coherent to keep doc inside src files and this
> will result in better doc-in-sync-with-src.
> 2. Source code will have documentation "inside".
> 3. Sphinx has a better syntax than Doxygen so less ci / format / tag
> errors may occur.
> 4. Working examples are available as reference point
> (https://github.com/kivy/kivy/tree/master/doc,
> https://github.com/kivy/kivy/blob/master/kivy/config.py).
>
>
> Cons:
> 2. It can (and probably will) mess up current doc _and_ src!!
> 2. Separation of documentation from the source code will enable easy
> switch to other documentation system rather than rewrite of all source
> code.
> 3. This is even more work than migrating docs from wiki.
> 4. This will make source files bigger (any impact on
> (pre)process/build time or something?).
> 5. The "separate" documentation is already out there just needs
> reformatting (wiki -> rst).
>
>
> > Additionally from this discussion I have opened two tickets from this
> > thread.
> >
> > * Generate and publish the PDF alongside the html docs
> > https://github.com/apache/nuttx/issues/9095
> > * A tracking ticket to unify more of the docs.
> > https://github.com/apache/nuttx/issues/9094
> >
> > I will start in on both once I return from holiday and have time in front
> > of a real computer again.
>
> I 

Re: The NuttX Handbook

[Tomek CEDRO]

On Tue, Apr 25, 2023 at 7:26 PM Brennan Ashton wrote:
> On Tue, Apr 25, 2023, 6:10 PM Tomek CEDRO wrote:
> (..)
> > After some consideration a "safer" approach may be more desirable for now:
> >
> > 1. Migrate all documentation to a separate Documentation/ as it is
> > currently done, so we do not lose any content from
> > MediaWiki/README/CWIKI, we can add additional content that we need,
> > the documentation form is shaped to a satisfactory state, automation
> > is verified, nice references, tables of contents, sections, etc.
> > People will have solid documentation all the time and we cause no mess
> > and we can see how the work on doc goes in reality :-)
> >
> > 2. When we have a well shaped "separate" documentation then it may be
> > the time to consider merging it with the source code, but not before,
> > if desired at all?
> >
> > What do you think?
>
> Eh I don't think we should pull the docs apart. Its a pain to manage
> especially with sphinx if we start sprinkling the docs all over the place.
> it's also hard in my opinion to write clear cohesive docs thare do not get
> highly repetitive if each section lives in isolation.  This unified style
> is also what we seen in projects like Zephr and Linux
> https://github.com/torvalds/linux/tree/master/Documentation
> https://github.com/zephyrproject-rtos/zephyr/tree/main/doc
>
> All this said, there is no reason to not also write clear comments in the
> code, especially code that may be incomplete, complex, hiding dragons or
> otherwise confusing.

Roger! So the doc stays separated from the src :-)

-- 
CeDeROM, SQ7MHZ, http://www.tomek.cedro.info

Re: NuttX BLE. Pairing with a device

[Alan C. Assis]

On 4/25/23, Brennan Ashton  wrote:
>
> I should probably have added this in more detail to the docs, but see the
> testing section of the PR where I added it. I think it shows exactly what
> you are trying to do
>
> https://github.com/apache/nuttx/pull/1655
>

Petro is right, we need to improve the "bt bnep0 scan get" command to
include a human readable device name.

It is very difficult to figure out which device we want to connect to.

Another nice improvement will be listing devices by their RSSI, this
way nearby devices tend to appear first in the listing.

BR,

Alan

Re: NuttX BLE. Pairing with a device

[Tomek CEDRO]

On Tue, Apr 25, 2023 at 6:54 PM Petro Karashchenko wrote:
> Is this going to work on OSX? Or Linux only is verified?

XCode has PacketLogger utility that should help :-)

Also you will see additional information when pressing Buetooth icon
with Alt key pressed :-)

Some folks recommend Ubertooth One from Great Scott Gadgets (creator
of HackRF One) with Wiershark.. but I am not sure if it will capture
latest BT 5.x traffic. On FreeBSD I did not manage to capture BT5.0
with SDR, nor nRF52840, nor internal hci snooping, only older BT
transmissions and also with some trouble, so I gave up. I once had
access to Ellisys hardware sniffer that was so easy to use but its
initial price and the price of updates can cause headache :-)

-- 
CeDeROM, SQ7MHZ, http://www.tomek.cedro.info

Re: NuttX BLE. Pairing with a device

[Petro Karashchenko]

Ok. Thank you.
I was able to monitor traffic from Ubuntu bluetooth port and found out that
my device sends advertising reports not frequently, so I did a few more
tries with duplicates on NuttX ESP32 and finally was able to identify the
needed string. So what is the next step? How to pair with the device?

Best regards,
Petro

вт, 25 квіт. 2023 р. о 20:05 Brennan Ashton 
пише:

> Unfortunately this is coupled to the Linux kernel Bluetooth stack since it
> is relying on the User Channel of the hcisocket which let's your
> application (NuttX in this case) have a virtual HCI device and temporarily
> provide it largely isolated control over it (you cannot scan from the host
> anymore for example).
> There is a good description of this feature in the patch that introduced
> it. https://marc.info/?l=linux-bluetooth=137757846631034=2
>
> On Tue, Apr 25, 2023, 5:54 PM Petro Karashchenko <
> petro.karashche...@gmail.com> wrote:
>
> > Is this going to work on OSX? Or Linux only is verified?
> >
> > вт, 25 квіт. 2023 р. о 19:45 Brennan Ashton 
> > пише:
> >
> > > On Tue, Apr 25, 2023, 5:41 PM Brennan Ashton <
> bash...@brennanashton.com>
> > > wrote:
> > >
> > > >
> > > > On Tue, Apr 25, 2023, 5:36 PM Petro Karashchenko <
> > > > petro.karashche...@gmail.com> wrote:
> > > >
> > > >> Hello,
> > > >>
> > > >> I'm starting to experiment with NuttX BLE support. I have a device
> > that
> > > I
> > > >> can successfully pair with my phone and I would like to try pairing
> it
> > > >> with
> > > >> the NuttX based device. I chose ESP32 for my experiments. For now I
> > > >> enabled
> > > >> (and fixed) esp32-devkitc:ble configuration, but that is basically
> > > all...
> > > >> I
> > > >> do not have much knowledge in bluetooth, but definitely want to
> master
> > > it.
> > > >> When I'm pairing from my phone I see the device name in the list of
> > > >> scanned
> > > >> devices, so the device advertises some human readable string in
> data.
> > > Then
> > > >> I'm running "bt bnep0 scan start" -> "bt bnep0 scan stop" -> "bt
> bnep0
> > > >> scan
> > > >> get" on my ESP32 and expecting to see some of the same human
> readable
> > > >> string in the printed output as I do not known the MAC address of my
> > > >> device, but there is not such data sequence in "bt bnep0 scan get"
> > > output.
> > > >> I would appreciate some guidance for the BLE dummy like me, so I can
> > > move
> > > >> forward a bit.
> > > >>
> > > >> Best regards,
> > > >> Petro
> > > >>
> > > >
> > > >
> > > > I have not touched it in a bit, but I found the sim support I added
> > with
> > > > the hci socket made debugging the Bluetooth stack a lot easier
> because
> > I
> > > > could use Wireshark/btmon on the actual host machine to show all the
> > hci
> > > > traffic to and from the NuttX stack transparently.  I highly
> recommend
> > > > trying that to verify there is not anything fundamentally broken.
> > > >
> > > > --Brennan
> > > >
> > >
> > > I should probably have added this in more detail to the docs, but see
> the
> > > testing section of the PR where I added it. I think it shows exactly
> what
> > > you are trying to do
> > >
> > > https://github.com/apache/nuttx/pull/1655
> > >
> > >
> > > --Brennan
> > >
> >
>

Re: The NuttX Handbook

[Nathan Hartman]

On Tue, Apr 25, 2023 at 9:59 AM Gregory Nutt  wrote:

> Sorry, I know I am way to anal retentive:
> > In the past, documentation was partly in README files in various
> > directories in the repo, partly on the NuttX website which was running on
> > MediaWiki.
> It was actually DocuWiki and was the landing page for the old nuttx.org
> website (not that it matters)



Ah, I stand corrected!

Thank you,
Nathan

Re: The NuttX Handbook

[Brennan Ashton]

On Tue, Apr 25, 2023, 6:10 PM Tomek CEDRO  wrote:

> On Tue, Apr 25, 2023 at 5:47 PM Brennan Ashton wrote:
> > On Tue, Apr 25, 2023, 3:18 PM Gregory Nutt wrote:
> > > My experience with using Deoxygen on large, projects has been
> > > disastrous.  People don't always maintain the tags to the documentation
> > > was wrong and so the auto-generated  documentation was not
> > > trust-worthy.  So you always end up looking at the code anyway.  There
> > > is nothing in the auto-generated code that is not in the the files so
> > > there is no real value added (there would be if you could trust it).
> > >
> > > Also, minor errors in the tags cause a lot of CI failures.  A couple
> per
> > > week.
> > >
> > > I suppose if documentation tags were added to all files and were all of
> > > the highest quality, it would be a good thing.   That that would be an
> > > enormous job and ongoing maintained of the documentation tags would be
> a
> > > problem:  Most people won't change them or put in useless, low value
> > > tags.  Much like PR comments. Or comments and documentation in general.
> > >
> > > If we could do it right, then +1 with a significant commitment of time
> > > and effort.  If we would do only a half-assed job, then -1.
> >
> > I _very_ much agree. I have very rarely found doxygen to be useful and
> > usually just results in unhelpful boilerplate to make the tool happy and
> > generates some html that no one will ever look at again.   It is usually
> > much better when someone spends the time to actually document the
> > interfaces and the why behind them (like man pages) we already have a
> > section in the docs for interfaces and it would be great as people extend
> > and adapt them to continue keeping these up to date.
>
> Okay, Doxygen is the past.. currently Sphinx is the way to go, no
> doubts, just an (not really convenient) example to keep doc in sync
> with src and that can be quite PITA :-)
>
>
> After some consideration a "safer" approach may be more desirable for now:
>
> 1. Migrate all documentation to a separate Documentation/ as it is
> currently done, so we do not lose any content from
> MediaWiki/README/CWIKI, we can add additional content that we need,
> the documentation form is shaped to a satisfactory state, automation
> is verified, nice references, tables of contents, sections, etc.
> People will have solid documentation all the time and we cause no mess
> and we can see how the work on doc goes in reality :-)
>
> 2. When we have a well shaped "separate" documentation then it may be
> the time to consider merging it with the source code, but not before,
> if desired at all?
>
> What do you think?
>

Eh I don't think we should pull the docs apart. Its a pain to manage
especially with sphinx if we start sprinkling the docs all over the place.
it's also hard in my opinion to write clear cohesive docs thare do not get
highly repetitive if each section lives in isolation.  This unified style
is also what we seen in projects like Zephr and Linux
https://github.com/torvalds/linux/tree/master/Documentation
https://github.com/zephyrproject-rtos/zephyr/tree/main/doc

All this said, there is no reason to not also write clear comments in the
code, especially code that may be incomplete, complex, hiding dragons or
otherwise confusing.

--Brennan

>

Re: The NuttX Handbook

[Tomek CEDRO]

On Tue, Apr 25, 2023 at 5:47 PM Brennan Ashton wrote:
> On Tue, Apr 25, 2023, 3:18 PM Gregory Nutt wrote:
> > My experience with using Deoxygen on large, projects has been
> > disastrous.  People don't always maintain the tags to the documentation
> > was wrong and so the auto-generated  documentation was not
> > trust-worthy.  So you always end up looking at the code anyway.  There
> > is nothing in the auto-generated code that is not in the the files so
> > there is no real value added (there would be if you could trust it).
> >
> > Also, minor errors in the tags cause a lot of CI failures.  A couple per
> > week.
> >
> > I suppose if documentation tags were added to all files and were all of
> > the highest quality, it would be a good thing.   That that would be an
> > enormous job and ongoing maintained of the documentation tags would be a
> > problem:  Most people won't change them or put in useless, low value
> > tags.  Much like PR comments. Or comments and documentation in general.
> >
> > If we could do it right, then +1 with a significant commitment of time
> > and effort.  If we would do only a half-assed job, then -1.
>
> I _very_ much agree. I have very rarely found doxygen to be useful and
> usually just results in unhelpful boilerplate to make the tool happy and
> generates some html that no one will ever look at again.   It is usually
> much better when someone spends the time to actually document the
> interfaces and the why behind them (like man pages) we already have a
> section in the docs for interfaces and it would be great as people extend
> and adapt them to continue keeping these up to date.

Okay, Doxygen is the past.. currently Sphinx is the way to go, no
doubts, just an (not really convenient) example to keep doc in sync
with src and that can be quite PITA :-)


After some consideration a "safer" approach may be more desirable for now:

1. Migrate all documentation to a separate Documentation/ as it is
currently done, so we do not lose any content from
MediaWiki/README/CWIKI, we can add additional content that we need,
the documentation form is shaped to a satisfactory state, automation
is verified, nice references, tables of contents, sections, etc.
People will have solid documentation all the time and we cause no mess
and we can see how the work on doc goes in reality :-)

2. When we have a well shaped "separate" documentation then it may be
the time to consider merging it with the source code, but not before,
if desired at all?

What do you think?


The biggest pro for keeping doc within src is to stay in sync, maybe
to also have self documented source code. But there are also dangers
here, like messing up the whole unfinished doc and the source code!!
It would be wise to list all pros and cons and then after some time
make some decisions but not necessarily right now.. :-)

Pros:
1. It would be more coherent to keep doc inside src files and this
will result in better doc-in-sync-with-src.
2. Source code will have documentation "inside".
3. Sphinx has a better syntax than Doxygen so less ci / format / tag
errors may occur.
4. Working examples are available as reference point
(https://github.com/kivy/kivy/tree/master/doc,
https://github.com/kivy/kivy/blob/master/kivy/config.py).


Cons:
2. It can (and probably will) mess up current doc _and_ src!!
2. Separation of documentation from the source code will enable easy
switch to other documentation system rather than rewrite of all source
code.
3. This is even more work than migrating docs from wiki.
4. This will make source files bigger (any impact on
(pre)process/build time or something?).
5. The "separate" documentation is already out there just needs
reformatting (wiki -> rst).


> Additionally from this discussion I have opened two tickets from this
> thread.
>
> * Generate and publish the PDF alongside the html docs
> https://github.com/apache/nuttx/issues/9095
> * A tracking ticket to unify more of the docs.
> https://github.com/apache/nuttx/issues/9094
>
> I will start in on both once I return from holiday and have time in front
> of a real computer again.

I am in, already subscribed! Full work power should arise around
July.. I will send some testing PR in the meantime.  Thanks!! :-)

-- 
CeDeROM, SQ7MHZ, http://www.tomek.cedro.info

Re: NuttX BLE. Pairing with a device

[Brennan Ashton]

Unfortunately this is coupled to the Linux kernel Bluetooth stack since it
is relying on the User Channel of the hcisocket which let's your
application (NuttX in this case) have a virtual HCI device and temporarily
provide it largely isolated control over it (you cannot scan from the host
anymore for example).
There is a good description of this feature in the patch that introduced
it. https://marc.info/?l=linux-bluetooth=137757846631034=2

On Tue, Apr 25, 2023, 5:54 PM Petro Karashchenko <
petro.karashche...@gmail.com> wrote:

> Is this going to work on OSX? Or Linux only is verified?
>
> вт, 25 квіт. 2023 р. о 19:45 Brennan Ashton 
> пише:
>
> > On Tue, Apr 25, 2023, 5:41 PM Brennan Ashton 
> > wrote:
> >
> > >
> > > On Tue, Apr 25, 2023, 5:36 PM Petro Karashchenko <
> > > petro.karashche...@gmail.com> wrote:
> > >
> > >> Hello,
> > >>
> > >> I'm starting to experiment with NuttX BLE support. I have a device
> that
> > I
> > >> can successfully pair with my phone and I would like to try pairing it
> > >> with
> > >> the NuttX based device. I chose ESP32 for my experiments. For now I
> > >> enabled
> > >> (and fixed) esp32-devkitc:ble configuration, but that is basically
> > all...
> > >> I
> > >> do not have much knowledge in bluetooth, but definitely want to master
> > it.
> > >> When I'm pairing from my phone I see the device name in the list of
> > >> scanned
> > >> devices, so the device advertises some human readable string in data.
> > Then
> > >> I'm running "bt bnep0 scan start" -> "bt bnep0 scan stop" -> "bt bnep0
> > >> scan
> > >> get" on my ESP32 and expecting to see some of the same human readable
> > >> string in the printed output as I do not known the MAC address of my
> > >> device, but there is not such data sequence in "bt bnep0 scan get"
> > output.
> > >> I would appreciate some guidance for the BLE dummy like me, so I can
> > move
> > >> forward a bit.
> > >>
> > >> Best regards,
> > >> Petro
> > >>
> > >
> > >
> > > I have not touched it in a bit, but I found the sim support I added
> with
> > > the hci socket made debugging the Bluetooth stack a lot easier because
> I
> > > could use Wireshark/btmon on the actual host machine to show all the
> hci
> > > traffic to and from the NuttX stack transparently.  I highly recommend
> > > trying that to verify there is not anything fundamentally broken.
> > >
> > > --Brennan
> > >
> >
> > I should probably have added this in more detail to the docs, but see the
> > testing section of the PR where I added it. I think it shows exactly what
> > you are trying to do
> >
> > https://github.com/apache/nuttx/pull/1655
> >
> >
> > --Brennan
> >
>

Re: NuttX BLE. Pairing with a device

[Petro Karashchenko]

Is this going to work on OSX? Or Linux only is verified?

вт, 25 квіт. 2023 р. о 19:45 Brennan Ashton 
пише:

> On Tue, Apr 25, 2023, 5:41 PM Brennan Ashton 
> wrote:
>
> >
> > On Tue, Apr 25, 2023, 5:36 PM Petro Karashchenko <
> > petro.karashche...@gmail.com> wrote:
> >
> >> Hello,
> >>
> >> I'm starting to experiment with NuttX BLE support. I have a device that
> I
> >> can successfully pair with my phone and I would like to try pairing it
> >> with
> >> the NuttX based device. I chose ESP32 for my experiments. For now I
> >> enabled
> >> (and fixed) esp32-devkitc:ble configuration, but that is basically
> all...
> >> I
> >> do not have much knowledge in bluetooth, but definitely want to master
> it.
> >> When I'm pairing from my phone I see the device name in the list of
> >> scanned
> >> devices, so the device advertises some human readable string in data.
> Then
> >> I'm running "bt bnep0 scan start" -> "bt bnep0 scan stop" -> "bt bnep0
> >> scan
> >> get" on my ESP32 and expecting to see some of the same human readable
> >> string in the printed output as I do not known the MAC address of my
> >> device, but there is not such data sequence in "bt bnep0 scan get"
> output.
> >> I would appreciate some guidance for the BLE dummy like me, so I can
> move
> >> forward a bit.
> >>
> >> Best regards,
> >> Petro
> >>
> >
> >
> > I have not touched it in a bit, but I found the sim support I added with
> > the hci socket made debugging the Bluetooth stack a lot easier because I
> > could use Wireshark/btmon on the actual host machine to show all the hci
> > traffic to and from the NuttX stack transparently.  I highly recommend
> > trying that to verify there is not anything fundamentally broken.
> >
> > --Brennan
> >
>
> I should probably have added this in more detail to the docs, but see the
> testing section of the PR where I added it. I think it shows exactly what
> you are trying to do
>
> https://github.com/apache/nuttx/pull/1655
>
>
> --Brennan
>

Re: NuttX BLE. Pairing with a device

[Brennan Ashton]

On Tue, Apr 25, 2023, 5:41 PM Brennan Ashton 
wrote:

>
> On Tue, Apr 25, 2023, 5:36 PM Petro Karashchenko <
> petro.karashche...@gmail.com> wrote:
>
>> Hello,
>>
>> I'm starting to experiment with NuttX BLE support. I have a device that I
>> can successfully pair with my phone and I would like to try pairing it
>> with
>> the NuttX based device. I chose ESP32 for my experiments. For now I
>> enabled
>> (and fixed) esp32-devkitc:ble configuration, but that is basically all...
>> I
>> do not have much knowledge in bluetooth, but definitely want to master it.
>> When I'm pairing from my phone I see the device name in the list of
>> scanned
>> devices, so the device advertises some human readable string in data. Then
>> I'm running "bt bnep0 scan start" -> "bt bnep0 scan stop" -> "bt bnep0
>> scan
>> get" on my ESP32 and expecting to see some of the same human readable
>> string in the printed output as I do not known the MAC address of my
>> device, but there is not such data sequence in "bt bnep0 scan get" output.
>> I would appreciate some guidance for the BLE dummy like me, so I can move
>> forward a bit.
>>
>> Best regards,
>> Petro
>>
>
>
> I have not touched it in a bit, but I found the sim support I added with
> the hci socket made debugging the Bluetooth stack a lot easier because I
> could use Wireshark/btmon on the actual host machine to show all the hci
> traffic to and from the NuttX stack transparently.  I highly recommend
> trying that to verify there is not anything fundamentally broken.
>
> --Brennan
>

I should probably have added this in more detail to the docs, but see the
testing section of the PR where I added it. I think it shows exactly what
you are trying to do

https://github.com/apache/nuttx/pull/1655


--Brennan

Re: NuttX BLE. Pairing with a device

[Brennan Ashton]

On Tue, Apr 25, 2023, 5:36 PM Petro Karashchenko <
petro.karashche...@gmail.com> wrote:

> Hello,
>
> I'm starting to experiment with NuttX BLE support. I have a device that I
> can successfully pair with my phone and I would like to try pairing it with
> the NuttX based device. I chose ESP32 for my experiments. For now I enabled
> (and fixed) esp32-devkitc:ble configuration, but that is basically all... I
> do not have much knowledge in bluetooth, but definitely want to master it.
> When I'm pairing from my phone I see the device name in the list of scanned
> devices, so the device advertises some human readable string in data. Then
> I'm running "bt bnep0 scan start" -> "bt bnep0 scan stop" -> "bt bnep0 scan
> get" on my ESP32 and expecting to see some of the same human readable
> string in the printed output as I do not known the MAC address of my
> device, but there is not such data sequence in "bt bnep0 scan get" output.
> I would appreciate some guidance for the BLE dummy like me, so I can move
> forward a bit.
>
> Best regards,
> Petro
>


I have not touched it in a bit, but I found the sim support I added with
the hci socket made debugging the Bluetooth stack a lot easier because I
could use Wireshark/btmon on the actual host machine to show all the hci
traffic to and from the NuttX stack transparently.  I highly recommend
trying that to verify there is not anything fundamentally broken.

--Brennan

>

NuttX BLE. Pairing with a device

[Petro Karashchenko]

Hello,

I'm starting to experiment with NuttX BLE support. I have a device that I
can successfully pair with my phone and I would like to try pairing it with
the NuttX based device. I chose ESP32 for my experiments. For now I enabled
(and fixed) esp32-devkitc:ble configuration, but that is basically all... I
do not have much knowledge in bluetooth, but definitely want to master it.
When I'm pairing from my phone I see the device name in the list of scanned
devices, so the device advertises some human readable string in data. Then
I'm running "bt bnep0 scan start" -> "bt bnep0 scan stop" -> "bt bnep0 scan
get" on my ESP32 and expecting to see some of the same human readable
string in the printed output as I do not known the MAC address of my
device, but there is not such data sequence in "bt bnep0 scan get" output.
I would appreciate some guidance for the BLE dummy like me, so I can move
forward a bit.

Best regards,
Petro

Re: MCU/Board with WiFi, BT and USB Host

[Petro Karashchenko]

That is indeed a great board.

I did a brief look into ESP32 NuttX BLE support and have more questions
than answers :) Also the USB host interface is not ported. So I was
thinking of picking Orange Pi 3G-IOT-B for prototyping and then go with
stage 2 cost reduction with ESP32-S3. My only concern is the security and
copy protection, but I found that there is a way to encrypt the file system
on Orange Pi, so I suppose that it is a kind of alternative to tamper
protection of ESP32 secure boot + flash encryption.

Regarding the computing power, my current estimates are 200MHz CPU with
512K RAM and 2MB should be fine, but I'm still in the research phase.

Best regards,
Petro


чт, 20 квіт. 2023 р. о 21:05 Tim Hardisty  пише:

> What sort processing power? Memory? Peripherals?
>
> SAMA5D27 (not that I’m biased lol) perhaps? ATSAMA5D27-WLSOM1 eval board
> has what you need but might be over the top? USB host/device works and you
> can do OTG/DRP on a custom board and it should be more than capable of
> doing CDC-ACM I would have thought?
>
> From: Petro Karashchenko 
> Reply to: "dev@nuttx.apache.org" 
> Date: Thursday, 20 April 2023 at 14:25
> To: "dev@nuttx.apache.org" 
> Subject: MCU/Board with WiFi, BT and USB Host
>
> Hello, I'm looking for an MCU or better a development board that has WiFi,
> BT and USB host capabilities. Can anybody give me advice for that? I need
> to connect a CDC ACM device to that USB, so maybe there are some
> alternatives that can be used (there is a device that exposes its
> functionality via USB to serial), so I need to communicate with that from
> my device. If that MCU is supported by NuttX then it would be super
> fantastic! Best regards, Petro
>

Re: The NuttX Handbook

[Brennan Ashton]

On Tue, Apr 25, 2023, 3:18 PM Gregory Nutt  wrote:

>
> > Thanks Alan! This is why I was a bit surprised why the documentation
> > is not direct part of the source code (i.e. documentation of the
> > file/module/function right in that file/module/function). Kivy does
> > that, it helps understanding the code, allows easy online/pdf
> > documentation out of it, and most important keeps documentation
> > coherent and up to date with the code!
> >
> > It could be easier to maintain / keep things coherent.. this can be
> > also done with Sphinx that we already use.. what do you
>
> The current coding
> standardhttps://
> cwiki.apache.org/confluence/display/NUTTX/Coding+Standard#fileorganization
> forbids documentation tags in the code, but that could change.
>

I think you mean this page in the docs :)
https://nuttx.apache.org/docs/latest/contributing/coding_style.html?highlight=deoxygen


> My experience with using Deoxygen on large, projects has been
> disastrous.  People don't always maintain the tags to the documentation
> was wrong and so the auto-generated  documentation was not
> trust-worthy.  So you always end up looking at the code anyway.  There
> is nothing in the auto-generated code that is not in the the files so
> there is no real value added (there would be if you could trust it).
>
> Also, minor errors in the tags cause a lot of CI failures.  A couple per
> week.
>
> I suppose if documentation tags were added to all files and were all of
> the highest quality, it would be a good thing.   That that would be an
> enormous job and ongoing maintained of the documentation tags would be a
> problem:  Most people won't change them or put in useless, low value
> tags.  Much like PR comments. Or comments and documentation in general.
>
> If we could do it right, then +1 with a significant commitment of time
> and effort.  If we would do only a half-assed job, then -1.
>

I _very_ much agree. I have very rarely found doxygen to be useful and
usually just results in unhelpful boilerplate to make the tool happy and
generates some html that no one will ever look at again.   It is usually
much better when someone spends the time to actually document the
interfaces and the why behind them (like man pages) we already have a
section in the docs for interfaces and it would be great as people extend
and adapt them to continue keeping these up to date.

Additionally from this discussion I have opened two tickets from this
thread.

* Generate and publish the PDF alongside the html docs
https://github.com/apache/nuttx/issues/9095
* A tracking ticket to unify more of the docs.
https://github.com/apache/nuttx/issues/9094

I will start in on both once I return from holiday and have time in front
of a real computer again.

--Brennan

>

Re: The NuttX Handbook

[Xiang Xiao]

not yet, we are busy preparing the Chinese documentation.

On Tue, Apr 25, 2023 at 10:27 PM Alan C. Assis  wrote:

> On 4/25/23, Alan C. Assis  wrote:
> > On 4/25/23, Gregory Nutt  wrote:
> >>
> >>> Yes, using the Documentation/ as base to create a book is a good idea,
> >>> but it should focus on "OS Components" and "API Reference".
> >>
> >> I don't think that the documentation should be limited to simple HowTo
> >> and WhatIs documentation.  I think it should have some technical meat
> >> too!  Like explanations of how things work and why they work that way:
> >> Theory of Operation documents.
> >>
> >> I really like Zephyr's Documentation, for example:
> >> https://docs.zephyrproject.org/latest/index.html  .  There is quite a
> >> bit of meat there; something for everyone.
> >>
> >
> > No, I meant the opposite, the Documentation/ is mostly focused on
> > Installations, HowTos, etc, it is better to be more technical.
> > Currently only "OS Components" and "API Reference" fit this criteria.
> >
> > I think our online Documentation is evolving slowly but it is getting
> > a better shape, the Zephyr documentation you cited is better organized
> > and reach more features. We can walk on that direction.
> >
> > It seems that their "PDF Handbook" is also based on their online
> > Documentation: https://docs.zephyrproject.org/2.7.4/zephyr.pdf
> >
> > Question: How we can do better, even with smaller team / resources?
> > Ideas? ChatGPT is not an option here :-D
> >
>
> Replying myself after seen confluence pages (like
> https://cwiki.apache.org/confluence/display/NUTTX/Memory+Configurations)
>
> We need some task force to move Confluence documentations to Documentation/
>
> Xiang Xiao: about that guy that you said Xiaomi was planing to
> contract to help us with Documentation, do you have some news?
>
> BR,
>
> Alan
>

Re: The NuttX Handbook

[Alan C. Assis]

On 4/25/23, Alan C. Assis  wrote:
> On 4/25/23, Gregory Nutt  wrote:
>>
>>> Yes, using the Documentation/ as base to create a book is a good idea,
>>> but it should focus on "OS Components" and "API Reference".
>>
>> I don't think that the documentation should be limited to simple HowTo
>> and WhatIs documentation.  I think it should have some technical meat
>> too!  Like explanations of how things work and why they work that way:
>> Theory of Operation documents.
>>
>> I really like Zephyr's Documentation, for example:
>> https://docs.zephyrproject.org/latest/index.html  .  There is quite a
>> bit of meat there; something for everyone.
>>
>
> No, I meant the opposite, the Documentation/ is mostly focused on
> Installations, HowTos, etc, it is better to be more technical.
> Currently only "OS Components" and "API Reference" fit this criteria.
>
> I think our online Documentation is evolving slowly but it is getting
> a better shape, the Zephyr documentation you cited is better organized
> and reach more features. We can walk on that direction.
>
> It seems that their "PDF Handbook" is also based on their online
> Documentation: https://docs.zephyrproject.org/2.7.4/zephyr.pdf
>
> Question: How we can do better, even with smaller team / resources?
> Ideas? ChatGPT is not an option here :-D
>

Replying myself after seen confluence pages (like
https://cwiki.apache.org/confluence/display/NUTTX/Memory+Configurations)

We need some task force to move Confluence documentations to Documentation/

Xiang Xiao: about that guy that you said Xiaomi was planing to
contract to help us with Documentation, do you have some news?

BR,

Alan

Re: The NuttX Handbook

[Alan C. Assis]

On 4/25/23, Gregory Nutt  wrote:
>
>> Yes, using the Documentation/ as base to create a book is a good idea,
>> but it should focus on "OS Components" and "API Reference".
>
> I don't think that the documentation should be limited to simple HowTo
> and WhatIs documentation.  I think it should have some technical meat
> too!  Like explanations of how things work and why they work that way:
> Theory of Operation documents.
>
> I really like Zephyr's Documentation, for example:
> https://docs.zephyrproject.org/latest/index.html  .  There is quite a
> bit of meat there; something for everyone.
>

No, I meant the opposite, the Documentation/ is mostly focused on
Installations, HowTos, etc, it is better to be more technical.
Currently only "OS Components" and "API Reference" fit this criteria.

I think our online Documentation is evolving slowly but it is getting
a better shape, the Zephyr documentation you cited is better organized
and reach more features. We can walk on that direction.

It seems that their "PDF Handbook" is also based on their online
Documentation: https://docs.zephyrproject.org/2.7.4/zephyr.pdf

Question: How we can do better, even with smaller team / resources?
Ideas? ChatGPT is not an option here :-D

BR,

Alan

Re: The NuttX Handbook

[Gregory Nutt]

Thanks Alan! This is why I was a bit surprised why the documentation
is not direct part of the source code (i.e. documentation of the
file/module/function right in that file/module/function). Kivy does
that, it helps understanding the code, allows easy online/pdf
documentation out of it, and most important keeps documentation
coherent and up to date with the code!

It could be easier to maintain / keep things coherent.. this can be
also done with Sphinx that we already use.. what do you think folks?
What are the pros and cons? :-)


The current coding 
standardhttps://cwiki.apache.org/confluence/display/NUTTX/Coding+Standard#fileorganization 
forbids documentation tags in the code, but that could change.


My experience with using Deoxygen on large, projects has been 
disastrous.  People don't always maintain the tags to the documentation 
was wrong and so the auto-generated  documentation was not 
trust-worthy.  So you always end up looking at the code anyway.  There 
is nothing in the auto-generated code that is not in the the files so 
there is no real value added (there would be if you could trust it).


Also, minor errors in the tags cause a lot of CI failures.  A couple per 
week.


I suppose if documentation tags were added to all files and were all of 
the highest quality, it would be a good thing.   That that would be an 
enormous job and ongoing maintained of the documentation tags would be a 
problem:  Most people won't change them or put in useless, low value 
tags.  Much like PR comments. Or comments and documentation in general.


If we could do it right, then +1 with a significant commitment of time 
and effort.  If we would do only a half-assed job, then -1.

Re: The NuttX Handbook

[Gregory Nutt]

Yes, using the Documentation/ as base to create a book is a good idea,
but it should focus on "OS Components" and "API Reference".


I don't think that the documentation should be limited to simple HowTo 
and WhatIs documentation.  I think it should have some technical meat 
too!  Like explanations of how things work and why they work that way:  
Theory of Operation documents.


I really like Zephyr's Documentation, for example: 
https://docs.zephyrproject.org/latest/index.html  .  There is quite a 
bit of meat there; something for everyone.

Re: The NuttX Handbook

[Tomek CEDRO]

On Tue, Apr 25, 2023 at 3:59 PM Gregory Nutt wrote:
>
> Sorry, I know I am way to anal retentive:
> > In the past, documentation was partly in README files in various
> > directories in the repo, partly on the NuttX website which was running on
> > MediaWiki.
> It was actually DocuWiki and was the landing page for the old nuttx.org
> website (not that it matters)

Sure it matters Greg! Maybe its a good moment to revise / clean up /
clarify directions. Any ideas are valuable, different points of view,
solid results, this is why I respect the NuttX community so much, and
I really like the discussions here! :-)

-- 
CeDeROM, SQ7MHZ, http://www.tomek.cedro.info

Re: The NuttX Handbook

[Tomek CEDRO]

On Tue, Apr 25, 2023 at 3:35 PM Alan C. Assis wrote:
> Hi Tomek,
>
> Some years ago Matias Nitsche (AKA v0id / protobits) started the
> creation of a NuttX book, documenting many of internal OS functions.
>
> But after some time he gave up, because he realized that NuttX is a
> movable target. Same happens to Linux (although currently I think
> Linux is more stable).
>
> See what happened to Linux Device Drivers from Alessandro Rubini,
> although the book still useful and relevant, many Linux functions and
> subsystems features described in the book doesn't exist anymore.
>
> So, to user point of view the best book about NuttX is any book about
> POSIX and the best "book" for NuttX kernel developers is the source
> code itself.

Thanks Alan! This is why I was a bit surprised why the documentation
is not direct part of the source code (i.e. documentation of the
file/module/function right in that file/module/function). Kivy does
that, it helps understanding the code, allows easy online/pdf
documentation out of it, and most important keeps documentation
coherent and up to date with the code!

It could be easier to maintain / keep things coherent.. this can be
also done with Sphinx that we already use.. what do you think folks?
What are the pros and cons? :-)

Example here: https://github.com/kivy/kivy/tree/master/doc

-- 
CeDeROM, SQ7MHZ, http://www.tomek.cedro.info

Re: The NuttX Handbook

[Gregory Nutt]

Sorry, I know I am way to anal retentive:

In the past, documentation was partly in README files in various
directories in the repo, partly on the NuttX website which was running on
MediaWiki.
It was actually DocuWiki and was the landing page for the old nuttx.org 
website (not that it matters)

Re: Debugging userspace with Nuttx protected build

[Gregory Nutt]

When I was originally developing the kernel mode, I wrote this: 
https://cwiki.apache.org/confluence/display/NUTTX/Memory+Configurations


That was mostly my notes of what I had worked on and my roadmap that was 
guiding me through the kernel mode development.  I burned out on that 
before finishing everything and since then several other people have 
worked with this build mode.  I don't know the current state.


I would be great to have a similar, updated document.  Although this old 
Wiki page is out of date, it still might answer some questions about 
what's there and why. There is even a section on "Partially Linked vs. 
Fully Linked Objects" in the section of things not finished.



On 4/24/2023 7:27 PM, Andrew Dennison wrote:

Are there any examples of a gdb setup to debug a userspace process? One key
issue is to setup the section offsets to match the final application
location once it has been loaded.

I was actually quite surprised that Nuttx applications are still partially
linked with a protected build and that all sections overlap (start at 0) in
the elf file. I had expected the application would be fully linked to
virtual addresses as per linux and another RTOS I used previously. Is this
something that can be changed relatively easily, or are there some
significant challenges?

Kind regards,

Andrew

Re: The NuttX Handbook

[Tomek CEDRO]

On Tue, Apr 25, 2023 at 3:01 PM Nathan Hartman wrote:
> On Tue, Apr 25, 2023 at 8:37 AM Tomek CEDRO wrote:
> > I would like to know what is the current and past approach to the
> > documentation, to plan the work and align the tasks (with other people
> > working on the documentation?). What is the future preferred way of
> > documentation? git+documentation? (c)wiki?
>
> In the past, documentation was partly in README files in various
> directories in the repo, partly on the NuttX website which was running on
> MediaWiki.
>
> As the project moved to Apache Software Foundation, most of the MediaWiki
> was migrated into CWIKI (because ASF has that setup) and there has been a
> gradual effort to reorganize the content of the README files in the repo
> under the Documentation directory and convert them from purely text to
> Sphinx format (which is still text and readable in its source format, but
> can be processed into webpages and probably PDF; it would be nice to offer
> a download link to the latest generated PDF from the NuttX website).
>
> I think that some docs were copied and pasted from the CWIKI to the in-repo
> Documentation directory but I don't know whether everything was. Some
> important stuff might be missing.
>
> Personally I think it would be best to put all the docs in Documentation in
> the repo and _not_ continue to keep it in the CWIKI. (But first we should
> ensure everything has been migrated so that we won't lose anything.)

Thank you for clarification Nathan! I am also pro all-in-one place
kind of documentation. git+sphinx seems more community friendly. So
initial task is to migrate contents from cwiki to git+sphinx, then
remove cwiki doc and use cwiki for some other tasks like roadmap etc?
:-)


> In the past some people expressed that they wanted to centralize docs for
> boards under Documentation rather than keeping README files scattered
> around. I responded that if we do that, we should have a directory
> structure under Documentation that parallels the structure under boards,
> which will serve both to keep things organized and to make it easy, given a
> board path, to find its corresponding docs path (i.e., just prepend
> "Documentation/").

Yes I like the idea, as we would have then all-in-one Handbook, and
easy to follow src+doc structure :-)

I can see that in current approach documentation is not part of the
source code (i.e. no Doxygen like solutions). I guess there is no
problem with organizing the Documentation/ part of the repo to
resemble fully the source code structure, so commits would be easy to
follow and verify (the code + doc part)..?


> Right now, it is well acknowledged that our documentation is lacking in
> several areas. Any help improving it will be tremendously appreciated.

No worries, it all takes time and work, I am eager to help :-)


> Among other improvements, it would be nice if the documentation could be
> organized to flow like a NuttX Handbook. I totally recommend to look at the
> FreeBSD Handbook for inspiration. :-)

yeah! :-)


> > It would be best to have HTML and PDF documentation (maybe other
> > formats too) in a form of "Handbook" (all-in-one-place + searchable +
> > offline). This Handbook could be also provided in a form of e-book for
> > free and maybe some pay-as-you-want basis to support the project.
>
> Not sure how donations would work. Probably they would have to be paid
> directly to ASF, but I think it is possible to earmark donations for
> specific things or projects. This is something that needs to be checked.

This would probably won't be any tremendous amount, but it could go
into freelance hands that work on an important parts (i.e. Yup porting
to PinePhone).. this could be somehow discussed/applied/voted before
distribution. Just an idea on how to help project grow :-)

Kivy for instance uses OpenCollective (https://kivy.org/#donate), If
the ASF has this capabilities we could use ASF for sure :-)


> This
> > would be also probably the first point of contact with the project for
> > the newcomers.
> Agreed.

:-)


-- 
CeDeROM, SQ7MHZ, http://www.tomek.cedro.info

Re: The NuttX Handbook

[Alan C. Assis]

On 4/25/23, Brennan Ashton  wrote:
>
> Others and I _extended_ and converted this to be what is now in
> Documentation it was a lot of work.  This is the documentation for the
> project although it has been slow to convert all the readmes and the wiki
> to be here. I would love to see others help with this time consuming
> effort.
>

Yes, using the Documentation/ as base to create a book is a good idea,
but it should focus on "OS Components" and "API Reference".

Including everything from Documentation/ is overkill and add not much
value compared to online Documentation.

BR,

Alan

Re: The NuttX Handbook

[Alan C. Assis]

Hi Tomek,

Some years ago Matias Nitsche (AKA v0id / protobits) started the
creation of a NuttX book, documenting many of internal OS functions.

But after some time he gave up, because he realized that NuttX is a
movable target. Same happens to Linux (although currently I think
Linux is more stable).

See what happened to Linux Device Drivers from Alessandro Rubini,
although the book still useful and relevant, many Linux functions and
subsystems features described in the book doesn't exist anymore.

So, to user point of view the best book about NuttX is any book about
POSIX and the best "book" for NuttX kernel developers is the source
code itself.

BR,

Alan

On 4/25/23, Tomek CEDRO  wrote:
> Hello world :-)
>
> I was on a trip recently (and it happens quite often) so I was looking
> for a PDF version of NuttX Documentation, kind of Handbook, but I did
> not find one.
>
> I got used to PDF Handbook style because it is all-in-one approach
> that is also easily available and searchable offline.
>
> As I am getting into details and reading the docs, so I can help this part
> :-)
>
> I would like to know what is the current and past approach to the
> documentation, to plan the work and align the tasks (with other people
> working on the documentation?). What is the future preferred way of
> documentation? git+documentation? (c)wiki?
>
> I know there is a doc part on the website that is generated from the
> main repository Documentation/ location. This part seems to need some
> improvement (looks a bit like incomplete copy-paste?) :-)
>
> I know there is a CWIKI. I know there was some bigger documentation
> before..?
>
> It would be best to have HTML and PDF documentation (maybe other
> formats too) in a form of "Handbook" (all-in-one-place + searchable +
> offline). This Handbook could be also provided in a form of e-book for
> free and maybe some pay-as-you-want basis to support the project. This
> would be also probably the first point of contact with the project for
> the newcomers.
>
> As a reference documentation I could point to:
> 1. https://docs.freebsd.org/en/books/handbook/
> 2. https://kivy.org/doc/stable/
>
> Please let me know what you think folks :-)
> Tomek
>
> --
> CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
>

Re: Debugging userspace with Nuttx protected build

[Tiago Medicci Serrano]

Hi!

I had no problems debugging NuttX with protected mode on ESP32-S3
(esp32s3-devkit:knsh).

After launching OpenOCD (https://github.com/espressif/openocd-esp32) with
`-c 'set ESP_RTOS none' -c "set ESP_FLASH_SIZE 0"`, just load the
userspace's symbols with `add-symbol-file` (with the address of the `.text`
region, that you can check with `objdump`, for instance)

xtensa-esp32s3-elf-gdb -ex "target extended-remote :"  -ex "symbol-file
nuttx"  -ex "add-symbol-file nuttx_user.elf 0x4209"  -ex "set remote
hardware-watchpoint-limit 2" -ex "mon reset halt" -ex "flushregs" -ex "set
print pretty" --tui

It works as expected on ESP32-S3.

Best regards,

Em ter., 25 de abr. de 2023 às 09:28, Gregory Nutt 
escreveu:

>
>  >>> I was actually quite surprised that Nuttx applications are still
> partially
>  >>> linked with a protected build and that all sections overlap (start
> at 0)in
>  >>> the elf file. I had expected the application would be fully linked to
>  >>> virtual addresses as per linux and another RTOS I used previously.
> Is this
>  >>> something that can be changed relatively easily, or are there some
>  >>> significant challenges?
>  >>
>  >> That would effect the build logic and the binary loader. The effort
>  >> would probably be significant.
>  >>
>  >> Are you doing a kernel build?  In that case, all applications are
>  >> partially linked ELF modules as you describe.  Linux positions .bss,
>  >> .data, immediately after .text in the virtual address space.  Heap and
>  >> thread stacks and other things are after that. So Linux applications
> can
>  >> be fully linked.
>  >
>  > I used a similar capability with a different small RTOS a while ago.
>  >
>  >> NuttX allocates everything from the heap when the module is loaded.  So
>  >> the application must be fully relocatable and address fix-ups are
>  >> needed.  So the ELF module is a partially linked relocatable ELF file.
>  >>
>  >
>  > For the kernel build (or MMU support in general) I'd assumed Nuttx would
>  > statically link and use the MMU to map the fixed elf section addresses
> to
>  > the pages allocated from the heap. This also helps startup performance
> as
>  > there are no relocations to process. But we're still learning the
> details
>  > of how Nuttx goes together.
>
> It was late last night when I responded.  In the clear light of morning
> I can see that my "justification" is lame and probably wrong.
>
> The REAL reason that the ELF modules work as they do is because they
> were designed to work in the FLAT build with all physical addressing.
> It is used with the KERNEL build because it works there too.
>
> That can't be changed only for the KERNEL build, but there could be a
> fully linked ELF binary just for the KERNEL build.  That should be too
> difficult.  Things that occur to me are:
>
>   * There are no tools for building such as executable.  It would
> probably have to be implemented within a Makefile as is the current
> ELF module build.
>   * There are no shared libraries so everything .. libc, syscalls, etc.
> ... has to be statically linked.  I think that is true of the
> existing ELF modules in the KERNEL build anyway.
>   * Some minor tweaks to crt0 might be necessary (?).
>
>

-- 
Tiago Medicci Serrano

Embedded Software Engineer
MSc Electronics/Microelectronics
m: +55 (19) 981403886 <+55+(19)+981403886>
e: tiago.medi...@gmail.com
a: Campinas, Brazil
Follow me:

Re: The NuttX Handbook

[Nathan Hartman]

On Tue, Apr 25, 2023 at 8:55 AM Brennan Ashton 
wrote:

> On Tue, Apr 25, 2023, 1:46 PM Brennan Ashton 
> wrote:
>
> >
> >
> > On Tue, Apr 25, 2023, 1:37 PM Tomek CEDRO  wrote:
> >
> >> Hello world :-)
> >>
> >> I was on a trip recently (and it happens quite often) so I was looking
> >> for a PDF version of NuttX Documentation, kind of Handbook, but I did
> >> not find one.
> >>
> >> I got used to PDF Handbook style because it is all-in-one approach
> >> that is also easily available and searchable offline.
> >>
> >> As I am getting into details and reading the docs, so I can help this
> >> part :-)
> >>
> >> I would like to know what is the current and past approach to the
> >> documentation, to plan the work and align the tasks (with other people
> >> working on the documentation?). What is the future preferred way of
> >> documentation? git+documentation? (c)wiki?
> >>
> >> I know there is a doc part on the website that is generated from the
> >> main repository Documentation/ location. This part seems to need some
> >> improvement (looks a bit like incomplete copy-paste?) :-)
> >>
> >> I know there is a CWIKI. I know there was some bigger documentation
> >> before..?
> >>
> >> It would be best to have HTML and PDF documentation (maybe other
> >> formats too) in a form of "Handbook" (all-in-one-place + searchable +
> >> offline). This Handbook could be also provided in a form of e-book for
> >> free and maybe some pay-as-you-want basis to support the project. This
> >> would be also probably the first point of contact with the project for
> >> the newcomers.
> >>
> >> As a reference documentation I could point to:
> >> 1. https://docs.freebsd.org/en/books/handbook/
> >> 2. https://kivy.org/doc/stable/
> >>
> >> Please let me know what you think folks :-)
> >> Tomek
> >>
> >> --
> >> CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
> >
> >
> >
> > It is easy enough to generate the PDF from the sphinx documentation if we
> > want that can you create an issue on the website project and I'll enable
> > that in a few weeks.
> >
> > --Brennan
> >
>
>
> Also I want to be very clear since this was incorrect
>
> > I know there was some bigger documentation before..?
>
> Others and I _extended_ and converted this to be what is now in
> Documentation it was a lot of work.  This is the documentation for the
> project although it has been slow to convert all the readmes and the wiki
> to be here. I would love to see others help with this time consuming
> effort.
>
> --Brennan
>

I wrote my reply before I saw this. Are there any more CWIKI pages that
need to be migrated into the repo?

Thanks for your (and other's) efforts in this area.

Nathan

Re: The NuttX Handbook

[Nathan Hartman]

On Tue, Apr 25, 2023 at 8:37 AM Tomek CEDRO  wrote:

> Hello world :-)
>
> I was on a trip recently (and it happens quite often) so I was looking
> for a PDF version of NuttX Documentation, kind of Handbook, but I did
> not find one.
>
> I got used to PDF Handbook style because it is all-in-one approach
> that is also easily available and searchable offline.
>
> As I am getting into details and reading the docs, so I can help this part
> :-)
>
> I would like to know what is the current and past approach to the
> documentation, to plan the work and align the tasks (with other people
> working on the documentation?). What is the future preferred way of
> documentation? git+documentation? (c)wiki?



In the past, documentation was partly in README files in various
directories in the repo, partly on the NuttX website which was running on
MediaWiki.

As the project moved to Apache Software Foundation, most of the MediaWiki
was migrated into CWIKI (because ASF has that setup) and there has been a
gradual effort to reorganize the content of the README files in the repo
under the Documentation directory and convert them from purely text to
Sphinx format (which is still text and readable in its source format, but
can be processed into webpages and probably PDF; it would be nice to offer
a download link to the latest generated PDF from the NuttX website).

I think that some docs were copied and pasted from the CWIKI to the in-repo
Documentation directory but I don't know whether everything was. Some
important stuff might be missing.

Personally I think it would be best to put all the docs in Documentation in
the repo and _not_ continue to keep it in the CWIKI. (But first we should
ensure everything has been migrated so that we won't lose anything.)

In the past some people expressed that they wanted to centralize docs for
boards under Documentation rather than keeping README files scattered
around. I responded that if we do that, we should have a directory
structure under Documentation that parallels the structure under boards,
which will serve both to keep things organized and to make it easy, given a
board path, to find its corresponding docs path (i.e., just prepend
"Documentation/").

Right now, it is well acknowledged that our documentation is lacking in
several areas. Any help improving it will be tremendously appreciated.

Among other improvements, it would be nice if the documentation could be
organized to flow like a NuttX Handbook. I totally recommend to look at the
FreeBSD Handbook for inspiration. :-)


I know there is a doc part on the website that is generated from the
> main repository Documentation/ location. This part seems to need some
> improvement (looks a bit like incomplete copy-paste?) :-)
>
> I know there is a CWIKI. I know there was some bigger documentation
> before..?
>
> It would be best to have HTML and PDF documentation (maybe other
> formats too) in a form of "Handbook" (all-in-one-place + searchable +
> offline). This Handbook could be also provided in a form of e-book for
> free and maybe some pay-as-you-want basis to support the project.



Not sure how donations would work. Probably they would have to be paid
directly to ASF, but I think it is possible to earmark donations for
specific things or projects. This is something that needs to be checked.


This
> would be also probably the first point of contact with the project for
> the newcomers.



Agreed.


As a reference documentation I could point to:
> 1. https://docs.freebsd.org/en/books/handbook/
> 2. https://kivy.org/doc/stable/
>
> Please let me know what you think folks :-)
> Tomek
>
> --
> CeDeROM, SQ7MHZ, http://www.tomek.cedro.info



Cheers
Nathan

Re: The NuttX Handbook

[Brennan Ashton]

On Tue, Apr 25, 2023, 1:46 PM Brennan Ashton 
wrote:

>
>
> On Tue, Apr 25, 2023, 1:37 PM Tomek CEDRO  wrote:
>
>> Hello world :-)
>>
>> I was on a trip recently (and it happens quite often) so I was looking
>> for a PDF version of NuttX Documentation, kind of Handbook, but I did
>> not find one.
>>
>> I got used to PDF Handbook style because it is all-in-one approach
>> that is also easily available and searchable offline.
>>
>> As I am getting into details and reading the docs, so I can help this
>> part :-)
>>
>> I would like to know what is the current and past approach to the
>> documentation, to plan the work and align the tasks (with other people
>> working on the documentation?). What is the future preferred way of
>> documentation? git+documentation? (c)wiki?
>>
>> I know there is a doc part on the website that is generated from the
>> main repository Documentation/ location. This part seems to need some
>> improvement (looks a bit like incomplete copy-paste?) :-)
>>
>> I know there is a CWIKI. I know there was some bigger documentation
>> before..?
>>
>> It would be best to have HTML and PDF documentation (maybe other
>> formats too) in a form of "Handbook" (all-in-one-place + searchable +
>> offline). This Handbook could be also provided in a form of e-book for
>> free and maybe some pay-as-you-want basis to support the project. This
>> would be also probably the first point of contact with the project for
>> the newcomers.
>>
>> As a reference documentation I could point to:
>> 1. https://docs.freebsd.org/en/books/handbook/
>> 2. https://kivy.org/doc/stable/
>>
>> Please let me know what you think folks :-)
>> Tomek
>>
>> --
>> CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
>
>
>
> It is easy enough to generate the PDF from the sphinx documentation if we
> want that can you create an issue on the website project and I'll enable
> that in a few weeks.
>
> --Brennan
>


Also I want to be very clear since this was incorrect

> I know there was some bigger documentation before..?

Others and I _extended_ and converted this to be what is now in
Documentation it was a lot of work.  This is the documentation for the
project although it has been slow to convert all the readmes and the wiki
to be here. I would love to see others help with this time consuming effort.

--Brennan

Re: The NuttX Handbook

[Brennan Ashton]

On Tue, Apr 25, 2023, 1:37 PM Tomek CEDRO  wrote:

> Hello world :-)
>
> I was on a trip recently (and it happens quite often) so I was looking
> for a PDF version of NuttX Documentation, kind of Handbook, but I did
> not find one.
>
> I got used to PDF Handbook style because it is all-in-one approach
> that is also easily available and searchable offline.
>
> As I am getting into details and reading the docs, so I can help this part
> :-)
>
> I would like to know what is the current and past approach to the
> documentation, to plan the work and align the tasks (with other people
> working on the documentation?). What is the future preferred way of
> documentation? git+documentation? (c)wiki?
>
> I know there is a doc part on the website that is generated from the
> main repository Documentation/ location. This part seems to need some
> improvement (looks a bit like incomplete copy-paste?) :-)
>
> I know there is a CWIKI. I know there was some bigger documentation
> before..?
>
> It would be best to have HTML and PDF documentation (maybe other
> formats too) in a form of "Handbook" (all-in-one-place + searchable +
> offline). This Handbook could be also provided in a form of e-book for
> free and maybe some pay-as-you-want basis to support the project. This
> would be also probably the first point of contact with the project for
> the newcomers.
>
> As a reference documentation I could point to:
> 1. https://docs.freebsd.org/en/books/handbook/
> 2. https://kivy.org/doc/stable/
>
> Please let me know what you think folks :-)
> Tomek
>
> --
> CeDeROM, SQ7MHZ, http://www.tomek.cedro.info



It is easy enough to generate the PDF from the sphinx documentation if we
want that can you create an issue on the website project and I'll enable
that in a few weeks.

--Brennan

>
>

The NuttX Handbook

[Tomek CEDRO]

Hello world :-)

I was on a trip recently (and it happens quite often) so I was looking
for a PDF version of NuttX Documentation, kind of Handbook, but I did
not find one.

I got used to PDF Handbook style because it is all-in-one approach
that is also easily available and searchable offline.

As I am getting into details and reading the docs, so I can help this part :-)

I would like to know what is the current and past approach to the
documentation, to plan the work and align the tasks (with other people
working on the documentation?). What is the future preferred way of
documentation? git+documentation? (c)wiki?

I know there is a doc part on the website that is generated from the
main repository Documentation/ location. This part seems to need some
improvement (looks a bit like incomplete copy-paste?) :-)

I know there is a CWIKI. I know there was some bigger documentation before..?

It would be best to have HTML and PDF documentation (maybe other
formats too) in a form of "Handbook" (all-in-one-place + searchable +
offline). This Handbook could be also provided in a form of e-book for
free and maybe some pay-as-you-want basis to support the project. This
would be also probably the first point of contact with the project for
the newcomers.

As a reference documentation I could point to:
1. https://docs.freebsd.org/en/books/handbook/
2. https://kivy.org/doc/stable/

Please let me know what you think folks :-)
Tomek

-- 
CeDeROM, SQ7MHZ, http://www.tomek.cedro.info

Re: Debugging userspace with Nuttx protected build

[Gregory Nutt]

>>> I was actually quite surprised that Nuttx applications are still 
partially
>>> linked with a protected build and that all sections overlap (start 
at 0)in

>>> the elf file. I had expected the application would be fully linked to
>>> virtual addresses as per linux and another RTOS I used previously. 
Is this

>>> something that can be changed relatively easily, or are there some
>>> significant challenges?
>>
>> That would effect the build logic and the binary loader. The effort
>> would probably be significant.
>>
>> Are you doing a kernel build?  In that case, all applications are
>> partially linked ELF modules as you describe.  Linux positions .bss,
>> .data, immediately after .text in the virtual address space.  Heap and
>> thread stacks and other things are after that. So Linux applications can
>> be fully linked.
>
> I used a similar capability with a different small RTOS a while ago.
>
>> NuttX allocates everything from the heap when the module is loaded.  So
>> the application must be fully relocatable and address fix-ups are
>> needed.  So the ELF module is a partially linked relocatable ELF file.
>>
>
> For the kernel build (or MMU support in general) I'd assumed Nuttx would
> statically link and use the MMU to map the fixed elf section addresses to
> the pages allocated from the heap. This also helps startup performance as
> there are no relocations to process. But we're still learning the details
> of how Nuttx goes together.

It was late last night when I responded.  In the clear light of morning 
I can see that my "justification" is lame and probably wrong.


The REAL reason that the ELF modules work as they do is because they 
were designed to work in the FLAT build with all physical addressing.  
It is used with the KERNEL build because it works there too.


That can't be changed only for the KERNEL build, but there could be a 
fully linked ELF binary just for the KERNEL build.  That should be too 
difficult.  Things that occur to me are:


 * There are no tools for building such as executable.  It would
   probably have to be implemented within a Makefile as is the current
   ELF module build.
 * There are no shared libraries so everything .. libc, syscalls, etc.
   ... has to be statically linked.  I think that is true of the
   existing ELF modules in the KERNEL build anyway.
 * Some minor tweaks to crt0 might be necessary (?).

Re: Debugging userspace with Nuttx protected build

[Andrew Dennison]

On Tue, Apr 25, 2023, 3:10 PM Gregory Nutt  wrote:

>
> On 4/24/2023 7:27 PM, Andrew Dennison wrote:
> > Are there any examples of a gdb setup to debug a userspace process? One
> key
> > issue is to setup the section offsets to match the final application
> > location once it has been loaded.
>
> You don't describe your build, so I only give you a general answer.
>


This is for a kernel build targeting risvc32.



> This does not specifically address what you need to do, but might be
> helpful:
>
> https://cwiki.apache.org/confluence/display/NUTTX/Debugging+ELF+Loadable+Modules
>
> I think the basics would be the same for all builds.
>

Similar to debugging Linux kernel modules.


> - You need to be able to stop the ELF module (FLAT or KERNEL build) or
> in FLASH program (PROTECTED build).
>
> - Then you can just add the symbol table of the ELF module )or user
> space) to the debugger.
>
> > I was actually quite surprised that Nuttx applications are still
> partially
> > linked with a protected build and that all sections overlap (start at 0)
> in
> > the elf file. I had expected the application would be fully linked to
> > virtual addresses as per linux and another RTOS I used previously. Is
> this
> > something that can be changed relatively easily, or are there some
> > significant challenges?
>
> That would effect the build logic and the binary loader.  The effort
> would probably be significant.
>
> Are you doing a kernel build?  In that case, all applications are
> partially linked ELF modules as you describe.  Linux positions .bss,
> .data, immediately after .text in the virtual address space.  Heap and
> thread stacks and other things are after that. So Linux applications can
> be fully linked.
>

I used a similar capability with a different small RTOS a while ago.


> NuttX allocates everything from the heap when the module is loaded.  So
> the application must be fully relocatable and address fix-ups are
> needed.  So the ELF module is a partially linked relocatable ELF file.
>

For the kernel build (or MMU support in general) I'd assumed Nuttx would
statically link and use the MMU to map the fixed elf section addresses to
the pages allocated from the heap. This also helps startup performance as
there are no relocations to process. But we're still learning the details
of how Nuttx goes together.

Re: Telnet broken?

[Xiang Xiao]

Nathan, could you try:
https://github.com/apache/nuttx/blob/master/boards/sim/sim/sim/configs/adb/defconfig
I just try it work as expect in last mainline:
telnet 127.0.0.1 2323
Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.

Welcome to NuttShell(NSH) Telnet Server...
login: admin
password:
User Logged-in!
Username: admin Password: Administrator
Maybe, some configuration mismatch.

On Tue, Apr 25, 2023 at 5:06 AM Nathan Hartman 
wrote:

> On Mon, Apr 24, 2023 at 4:54 PM Gregory Nutt  wrote:
>
> >
> > > Including the doubling of characters and momentary display of some
> > > characters which seem to change rapidly?
> >
> > That probably comes from NSH.  I think it still sends an escape sequence
> > to clear to the end of the line.  So any additional garbage at the end
> > after the first four characters would only be present momentarily.
> >
> > But things are changing rapidly, obviously more rapidly than can be
> > tested.  So I would have to studly the nshlib code again to see what it
> > is doing today.
> >
> > So do you think that that last release was too shaky?  Should there be a
> > bugfix release for that one?
>
>
>
> Unfortunately I wasn't available to test and vote on the most recent
> release and I also don't currently know in exactly which commit or PR this
> broke, but it is definitely broken now, so if it has been released, then
> yes, I think it makes sense to do another release once it's fixed.
>
> I don't know how many people are using the telnet/nsh combination but I
> have to do it with this particular board since the only communication port
> it has is a network port. When telnet doesn't work correctly it really
> messes everything up for me because I can't really interface to it.
>
> Cheers
> Nathan
>

Re: Debugging userspace with Nuttx protected build

[Brennan Ashton]

On Tue, Apr 25, 2023, 6:10 AM Gregory Nutt  wrote:

>
> On 4/24/2023 7:27 PM, Andrew Dennison wrote:
> > Are there any examples of a gdb setup to debug a userspace process? One
> key
> > issue is to setup the section offsets to match the final application
> > location once it has been loaded.
>

This won't help you today as it is not yet implemented, but longer term I
think it would be really nice to get ptrace support implemented so we could
allow for a debug server stub to run in userspace.

https://github.com/apache/nuttx/issues/2028

--Brennan