mirror of
https://github.com/apache/nuttx.git
synced 2026-10-11 08:10:21 +00:00
f6ecf80ebb
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
86 lines
4.5 KiB
Markdown
86 lines
4.5 KiB
Markdown
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.
|