[RFC] Add "Description:" header to defconfig file

["Alan C. Assis" <ac...@gmail.com>]

Dear NuttXers,

As some people here know, recently Espressif added support for USB OTG
Device on ESP32S3 (thanks to Dong Heng).

And it opened the possibility to have USB Console using this USB OTG
Device or using the USB_SERIAL_JTAG (see TRM: "33 USB Serial/JTAG
Controller (USB_SERIAL_JTAG)" ).

So, to "avoid" confusion we will follow this convention: usbconsole
when referring to USB console using USB_SERIAL_JTAG and usbnsh when
referring to USB console using USB Device.

However for a newcomer who never saw his email, it will be difficult
to understand what each one does. Same apply to many board profiles we
already have currently.

Of course, the best way to solve it is creating a documentation for
each board profile, but it is something that doesn't happen easily.

So, I think having a "Description: " in the defconfig could help here.
People could read it to know what it does or we could use:
"./tools/configure.sh info boardname:profile" to print this information.

This is just a RFC, I opened it here:
https://github.com/apache/nuttx/issues/9598

BR,

Alan

Re: [RFC] Add "Description:" header to defconfig file

["Alan C. Assis" <ac...@gmail.com>]

Hi Tomek,

On 6/24/23, Tomek CEDRO <to...@cedro.info> wrote:
> On Sat, Jun 24, 2023 at 3:53 PM Alan C. Assis wrote:
>> Dear NuttXers,
>> As some people here know, recently Espressif added support for USB OTG
>> Device on ESP32S3 (thanks to Dong Heng).
>
> BIG TANKS!! :-)
>
>> And it opened the possibility to have USB Console using this USB OTG
>> Device or using the USB_SERIAL_JTAG (see TRM: "33 USB Serial/JTAG
>> Controller (USB_SERIAL_JTAG)" ).
>>
>> So, to "avoid" confusion we will follow this convention: usbconsole
>> when referring to USB console using USB_SERIAL_JTAG and usbnsh when
>> referring to USB console using USB Device.
>>
>> However for a newcomer who never saw his email, it will be difficult
>> to understand what each one does. Same apply to many board profiles we
>> already have currently.
>
> The defconfig name should and can be self-explanatory:
>
> 1. usbconsole when referring to USB console using USB_SERIAL_JTAG is
> not self-explanatory. Why not just use usbnshespserialjtag? I know it
> looks ugly (can be usbnsh_esp_serialjtag?) but its grepable and most
> times it is copied / typed only once? :-)
>

Exactly because of this usbnshespserialjtag and usbnsh_esp_serialjtag
are not good names and didn't help much to explain the differences.

> 2. usbnsh when referring to USB console using USB Device... as for
> other devices so there is no confusion.
>

Yes, usbnsh is default across all platforms with USB Device CDC/ACM as
console, so we reserve it to be 100% compatible.
In theory the console over USB_SERIAL_JTAG is a "usb nsh", just using
an Espressif-only USB IP that is not real USB Device, imagine it as a
USB Device that only can be a CDC.

>> Of course, the best way to solve it is creating a documentation for
>> each board profile, but it is something that doesn't happen easily.
>
> Just let me know what to put and where and I will help with updating
> the documentation.. lets keep things coherent and make folks used to
> the process :-)
>

Just look some examples of supported boards:
https://nuttx.apache.org/docs/latest/platforms/index.html and add the
missing boards and board profiles.

I think we could create some board Template/Skeleton to be used when
submitting now boards.

I see a lot of inconsistencies and quality issues, let see just 3
random examples:


https://nuttx.apache.org/docs/latest/platforms/arm/rp2040/boards/waveshare-rp2040-lcd-1.28/index.html

Good things:
1) included board image;
2) included pinout diagrams;
3) include Feature session

Bad things:
1) didn't explain how to flash NuttX in the board
2) shallow/non-existent explanation about each board profile (read the
descriptions and you will see)


https://nuttx.apache.org/docs/latest/platforms/risc-v/mpfs/boards/icicle/index.html

Good things:
1) included board image;

Bad things:
1) didn't include Feature session; Although it is separated by CPU,
Memory and storage, Interfaces, Sensor, etc
2) didn't include all board profiles: hwtest, knsh, network, nsh,
opensbi, pnsh, rpmsg-ch1, rpmsg-ch2, rpmsg-sbi, usb


https://nuttx.apache.org/docs/latest/platforms/risc-v/esp32c3/boards/esp32c3-devkit/index.html

Good things:
1) included board image;
2) explained how to flash NuttX in the board
3) all board profiles really well explained

Bad things:
1) missing pinout diagrams;
2) didn't include Feature session;

>> So, I think having a "Description: " in the defconfig could help here.
>> People could read it to know what it does or we could use:
>> "./tools/configure.sh info boardname:profile" to print this information.
>
> I like the idea! It would be nice to have "Description" field within
> the "Defconfig" itself, that would create self-explanatory solution
> right at the code and on the `-L` list :-) Right now some options are
> obvious only for people who already know them and this is not the
> way.. for instance some CONFIG options also could be more verbose :-)
>

Nice to know you liked it. I think Brennan is worried that this
"Description:" field could make people more lazy about creating the
board documentation, but I don't think so.
I think "Description: " and Documentation are different thing, that
are not "OR Exclusive".

>
>> This is just a RFC, I opened it here:
>> https://github.com/apache/nuttx/issues/9598
>
> My comments inside too :-)
>

Thanks!

BR,

Alan

Re: [RFC] Add "Description:" header to defconfig file

[Tomek CEDRO <to...@cedro.info>]

On Sat, Jun 24, 2023 at 3:53 PM Alan C. Assis wrote:
> Dear NuttXers,
> As some people here know, recently Espressif added support for USB OTG
> Device on ESP32S3 (thanks to Dong Heng).

BIG TANKS!! :-)

> And it opened the possibility to have USB Console using this USB OTG
> Device or using the USB_SERIAL_JTAG (see TRM: "33 USB Serial/JTAG
> Controller (USB_SERIAL_JTAG)" ).
>
> So, to "avoid" confusion we will follow this convention: usbconsole
> when referring to USB console using USB_SERIAL_JTAG and usbnsh when
> referring to USB console using USB Device.
>
> However for a newcomer who never saw his email, it will be difficult
> to understand what each one does. Same apply to many board profiles we
> already have currently.

The defconfig name should and can be self-explanatory:

1. usbconsole when referring to USB console using USB_SERIAL_JTAG is
not self-explanatory. Why not just use usbnshespserialjtag? I know it
looks ugly (can be usbnsh_esp_serialjtag?) but its grepable and most
times it is copied / typed only once? :-)

2. usbnsh when referring to USB console using USB Device... as for
other devices so there is no confusion.


> Of course, the best way to solve it is creating a documentation for
> each board profile, but it is something that doesn't happen easily.

Just let me know what to put and where and I will help with updating
the documentation.. lets keep things coherent and make folks used to
the process :-)


> So, I think having a "Description: " in the defconfig could help here.
> People could read it to know what it does or we could use:
> "./tools/configure.sh info boardname:profile" to print this information.

I like the idea! It would be nice to have "Description" field within
the "Defconfig" itself, that would create self-explanatory solution
right at the code and on the `-L` list :-) Right now some options are
obvious only for people who already know them and this is not the
way.. for instance some CONFIG options also could be more verbose :-)


> This is just a RFC, I opened it here:
> https://github.com/apache/nuttx/issues/9598

My comments inside too :-)


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