Aksal/nuttx
3
1
Fork 1
mirror of https://github.com/apache/nuttx.git synced 2026-10-08 06:45:19 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
nuttx/Documentation/ReleaseNotes/NuttX-5.16.md
Vinicius May f6ecf80ebb Documentation: brand new layout for NuttX documentation. 
The documentation grew one page at a time, so the tree follows the
history of who wrote what and not the shape of NuttX. Scheduling is
spread over three places, a driver page can sit above the subsystem
that owns it, and the front page lists everything at the same level.
That is a lot to face when all you want to know is where the scheduler
lives.

This change files every page under the code it describes. It is a move,
not a rewrite: outside the ten pages named below, every page keeps the
text that is already in master, and no page's text is deleted.

What it does:

* Groups the table of contents into nine chapters.
* Moves the OS subsystems under os/: scheduling, memory, drivers,
  filesystem, networking, IPC, interrupts, libs, time.
* Renames the platform pages to the names the source tree uses, and
  derives their tags from the tree instead of by hand.
* Splits guides/ by subject.
* Adds Documentation/redirects.py, with a rule for every page that left
  its old path, so old URLs keep working. The redirect page also carries
  a link's #anchor across to the new page.

Ten pages have text that is new or rewritten. Nine of them are the
landing page of a chapter, which has to exist for the new structure:

    index                  the front page
    os/index               OS Design
    os/scheduling/index    Scheduling
    os/interrupts/index    Interrupts
    os/ipc/index           IPC
    os/time/index          Time and timers
    about/index            About
    developing/index       Developing NuttX
    ReleaseNotes/index     Release notes

The tenth is os/libs/libbuiltin, the only page here with technical
content: libs/libbuiltin/ had no page at all. Five SVG diagrams come
with these pages, hand-written XML with no editor metadata.

Nothing outside Documentation/ is touched.

How it was checked:

* Sphinx builds with -W: no warnings, and no document left outside a
  toctree.
* A script, offered in the PR, proves the narrow claim this rests on.
  For every page outside the ten named above it erases what a move
  touches -- link target, path, tag line, toctree block, table border --
  from the whole old text and the whole new text, and requires the two
  to be byte for byte identical. It also requires every sentence of a
  deleted page to turn up somewhere, and every page that left its old
  path to have a redirect, from a URL that existed, to where its content
  went. It exits non-zero and names the page if any of that is not true,
  and it tests added pages too, so forgetting to declare one cannot make
  it pass.
* An independent audit checked 133 factual claims on these ten pages
  against the tree, one shell command per claim: 130 confirmed, 1
  refuted and fixed here, 2 not checkable.
* tools/checkpatch.sh is clean over the range.

The diff is large because moving a page changes every link that points
to it. Most of it is pure renames, and board pages that gained one tag
line.

Assisted-by: Claude:claude-opus-5
2026-10-08 01:40:54 +08:00

4.5 KiB
Raw Blame History

NuttX-5.16

The 63rd release of NuttX, Version 5.16, was made on January 10, 2010 and is available for download from the SourceForge website. This release includes initial support for USB host in NuttX. The USB host infrastructure is new to NuttX. This initial USB host release is probably only beta quality; it is expected the some bugs remain in the logic and that the functionality requires extension.

Below is a summary of the NuttX USB host implementation as extracted from the NuttX Porting Guide:

6.3.9 USB Host-Side Drivers

  • include/nuttx/usb/usbhost.h. All structures and APIs needed to work with USB host-side drivers are provided in this header file.
  • struct usbhost_driver_s. Each USB host controller driver must implement an instance of struct usbhost_driver_s. This structure is defined in include/nuttx/usb/usbhost.h. Examples: arch/arm/src/lpc17xx/lpc17_usbhost.c.
  • struct usbhost_class_s. Each USB host class driver must implement an instance of struct usbhost_class_s. This structure is also defined in include/nuttx/usb/usbhost.h. Examples: drivers/usbhost/usbhost_storage.c
  • USB Host Class Driver Registry. The NuttX USB host infrastructure includes a registry. During its initialization, each USB host class driver must call the interface, usbhost_registerclass() in order add its interface to the registry. Later, when a USB device is connected, the USB host controller will look up the USB host class driver that is needed to support the connected device in this registry. Examples: drivers/usbhost/usbhost_registry.c, drivers/usbhost/usbhost_registerclass.c, and drivers/usbhost/usbhost_findclass.c,
  • Detection and Enumeration of Connected Devices. Each USB host device controller supports two methods that are used to detect and enumeration newly connected devices (and also detect disconnected devices):
  • int (*wait)(FAR struct usbhost_driver_s *drvr, bool connected); Wait for a device to be connected or disconnected.
  • int (*enumerate)(FAR struct usbhost_driver_s *drvr); Enumerate the connected device. As part of this enumeration process, the driver will (1) get the device's configuration descriptor, (2) extract the class ID info from the configuration descriptor, (3) call usbhost_findclass() to find the class that supports this device, (4) call the create() method on the struct usbhost_registry_s interface to get a class instance, and finally (5) call the connect() method of the struct usbhost_class_s interface. After that, the class is in charge of the sequence of operations.
  • Binding USB Host-Side Drivers. USB host-side controller drivers are not normally directly accessed by user code, but are usually bound to another, higher level USB host class driver. The class driver exports the standard NuttX device interface so that the connected USB device can be accessed just as with other, similar, on-board devices. For example, the USB host mass storage class driver (drivers/usbhost/usbhost_storage.c) will register a standard, NuttX block driver interface (like /dev/sda) that can be used to mount a file system just as with any other other block driver instance. In general, the binding sequence is:
  1. Each USB host class driver includes an initialization entry point that is called from the application at initialization time. This driver calls usbhost_registerclass() during this initialization in order to makes itself available in the event that the device that it supports is connected. Examples: The function usbhost_storageinit() in the file drivers/usbhost/usbhost_storage.c
  2. Each application must include a waiter thread thread that (1) calls the USB host controller driver's wait() to detect the connection of a device, and then (2) call the USB host controller driver's enumerate method to bind the registered USB host class driver to the USB host controller driver. Examples: The function nsh_waiter() in the file configs/nucleus2g/src/up_nsh.c and the function nsh_waiter() in the file configs/olimex-lpc1766stk/src/up_nsh.c.
  3. As part of its operation during the binding operation, the USB host class driver will register an instances of a standard NuttX driver under the /dev directory. To repeat the above example, the USB host mass storage class driver (drivers/usbhost/usbhost_storage.c) will register a standard, NuttX block driver interface (like /dev/sda) that can be used to mount a file system just as with any other other block driver instance. Examples: See the call to register_blockdriver() in the function usbhost_initvolume() in the file drivers/usbhost/usbhost_storage.c.