236 lines
10 KiB
ReStructuredText
236 lines
10 KiB
ReStructuredText
====================
|
||
Platform Directories
|
||
====================
|
||
|
||
.. warning::
|
||
Migrated from:
|
||
https://cwiki.apache.org/confluence/display/NUTTX/Platform+Directories
|
||
|
||
Let's assume that you are not change the OS itself but want to implement or
|
||
extend platform-specific code.In this case, there are six, maybe seven,
|
||
places where you can provide the platform code.
|
||
|
||
.. image:: image/directories.png
|
||
|
||
|
||
REVISIT: This is a out of date. There has been a recent reorganization
|
||
of the board-related directories: The ``configs/`` directory has been
|
||
renamed ``boards/`` and structure under the new ``boards/`` directory is
|
||
significantly different. A ``<board>`` directory would now be found
|
||
at ``boards/<arch>/<chip>/<board>``. Conceptually the figure is correct,
|
||
just not consistent with current naming.
|
||
|
||
Each directory has slightly different properties and are discussed
|
||
in more detail below where:
|
||
|
||
* `<arch>` represents the chip architecture that you are using.
|
||
As examples, `<arch>` might represent ``arm`` or ``mips``.
|
||
* `<chip>` represents the specific chip family that you are using.
|
||
As examples, `<chip>` might mean ``stm32`` or ``efm32``
|
||
* `<board>` represents the specific board that you are using.
|
||
As examples, `<board>` might be ``stm32f4discovery`` or ``dk-tm4c129x``
|
||
|
||
1. arch/<arch>/src/<chip>
|
||
=========================
|
||
|
||
The ``arch/<arch>/src/<chip>`` directory should hold all chip related
|
||
logic. Almost all chip-specific header files should reside here
|
||
too. That includes device-related header files. GPIO header
|
||
files, for example, go here and no where else.
|
||
|
||
2. arch/<arch>/include/<chip>
|
||
=============================
|
||
|
||
The intent of the ``arch/<arch>/include/<chip>`` directory is to
|
||
hold driver-related definitions needed by application in order
|
||
to access drivers registered by the chip-specific logic in the
|
||
``arch/<arch>/src/<chip>`` directory. This would include things like:
|
||
|
||
* The IOCTL cmds that would be used with the driver
|
||
``ioctl()`` interfaces calls,
|
||
* Structure definitions of parameters passed with
|
||
IOCTL cmds, and
|
||
* Structure definitions of binary data that might
|
||
be transferred via the driver ``read()`` or ``write()`` methods.
|
||
|
||
The ``arch/<arch>/include/<chip>`` directory is not currently used
|
||
properly for most of the definitions you will find there. Most
|
||
of the definitions in these header files really belong in the
|
||
``arch/<arch>/src/<chip>`` directory but are here for historical
|
||
reasons only at this point.
|
||
|
||
The difference between header files in ``arch/<arch>/include/<chip>``
|
||
directory and the header files in ``arch/<arch>/src/<chip>`` directory
|
||
is that the former can be included by applications using the
|
||
include path:
|
||
|
||
.. code-block:: c
|
||
|
||
#include <arch/chip/someheader.h>
|
||
|
||
The header files in ``arch/<arch>/src/<chip>`` cannot be used by
|
||
applications. Those header flies can and only be used in the
|
||
``arch/<arch>/src/<chip>`` and in the ``configs/<board>`` directories.
|
||
|
||
The header files in this directory `MUST NOT` introduce `ad hoc`
|
||
non-standard function call interfaces between the application
|
||
and the OS. The OS interfaces are highly controlled and not
|
||
subject to `ad hoc` extension.
|
||
|
||
The NuttX build system enforces this and I do everything that
|
||
I can to restrict usage of all chip specific facilities to those
|
||
directories. In reality you are free, of course, to subvert that
|
||
intent in any way you please for your personal project; but any
|
||
subversion of that intent will not not be committed into the
|
||
upstream NuttX repository.
|
||
|
||
3. configs/<board>/include
|
||
==========================
|
||
|
||
The ``configs/<board>/include`` directory is the moral equivalent of the
|
||
``arch/<arch>/include/<chip>`` directory for boards: The
|
||
``arch/<arch>/include/<chip>`` directory holds chip-specific
|
||
definitions that are accessible all logic (event even application code).
|
||
Similarly the ``configs/<board>/include`` directory holds board-specific
|
||
definitions that are accessible even to applications code. And the
|
||
same kinds of driver interfacing data should appear in these
|
||
files (see the list above).
|
||
|
||
Similarly, the intent of the ``configs/<board>/include`` directory
|
||
is to hold driver-related definitions needed by application in
|
||
order to access drivers registered by the board-specific logic
|
||
in the ``configs/<board>/src`` directory. The header files in the
|
||
``configs/<board>/include`` directory can be included using this
|
||
include path:
|
||
|
||
.. code-block:: c
|
||
|
||
#include <arch/board/someheader.h>
|
||
|
||
The header files in this directory `MUST NOT` introduce `ad hoc`
|
||
non-standard function call interfaces between the application
|
||
and the OS. The OS interfaces are highly controlled and not
|
||
subject to `ad hoc` extension.
|
||
|
||
4. configs/<board>/src
|
||
======================
|
||
|
||
All of your board-specific initialization logic and `all` of the
|
||
custom board device driver logic should go either in a `built-in`
|
||
``configs/<board>/src`` directory or in an external, custom board
|
||
directory. These board directories are where all of your
|
||
board-specific, hardware interfacing work should be done.
|
||
As a minimum, a built-in board directory must contain
|
||
these files/directories at a minimum:
|
||
|
||
* ``Kconfig`` to include the custom board configuration options into
|
||
the NuttX configuration system.
|
||
* ``src/Makefile`` contains the custom board build logic
|
||
* ``include/board.h`` provides board-specific information needed by the system
|
||
|
||
Most people will eventually want to create their own custom board
|
||
directory. If you do ``make menuconfig`` you will find under the board
|
||
menu that you can enable and configure a custom board directory.
|
||
One of these configuration options is the path to your custom
|
||
board directory. That is where you will want to implement all
|
||
of your product-specific device driver logic. As a minimum,
|
||
your custom board directory must contain these files/directories at a minimum:
|
||
|
||
* ``src/Makefile`` contains the custom board build logic
|
||
* ``include/board.h`` provides board-specific information needed by the system
|
||
|
||
NOTE: That the configuration definition file, ``Kconfig``, is not
|
||
currently supported in the custom board configuration directory.
|
||
|
||
Within either type of ``board/src`` directory you will have
|
||
free access to all of the header files in the whole system,
|
||
including even those in the ``arch/<arch>/src/<chip>`` directory.
|
||
There are no limitations whatsoever; All include paths are supported.
|
||
|
||
5. Application Directory
|
||
========================
|
||
|
||
There are many ways to implement your application build. How you do that is
|
||
not really a part of NuttX and the topic is beyond the scope of this Wiki
|
||
page. The NuttX apps package does provide one example of an application
|
||
directory you may choose to use – or not. That apps/ directory is
|
||
intended to provide you with some guidance. But if you search the
|
||
messages in the forum, you can get lots of other ideas how to
|
||
structure the application build.
|
||
|
||
The application logic can include header files from
|
||
``arch/<arch>/include/<chip>`` directory or from the
|
||
``configs/<board>/include`` directory for sole purpose
|
||
of support standard driver interfacing. The header
|
||
files in this directories must not introduce
|
||
uncontrolled, `ad hoc` interfaces into the operating system.
|
||
|
||
In the application directory, you cannot include header files
|
||
from either the ``arch/<arch>/src/<chip>`` directory or the
|
||
``configs/<board>/src`` directory. That is an intentional
|
||
restriction that I try to enforce in order to support the
|
||
NuttX model for the segregation of functionality. But again,
|
||
you can always subvert that in your own repository as you
|
||
like. There should be no device level code in your application.
|
||
There should be no need to access GPIOs or registers or
|
||
anything like that. That all should be done in the chip
|
||
directory or in your board directory.
|
||
|
||
The model I advocate is to create and register standard device
|
||
drivers in your ``configs/<board>/src`` or custom board directory,
|
||
then you can access the device in your application directory
|
||
using the standard ``open()`` / ``close()`` / ``read()`` / ``write()``
|
||
functions.
|
||
|
||
But I am all about freedom. Please do things exactly how you
|
||
want to do them. Make sure the project meets all of your needs
|
||
first; do things as you like. But, of course, I cannot commit
|
||
anything upstream that does not conform to these architectural rules.
|
||
|
||
6. drivers/
|
||
===========
|
||
|
||
Above I said that all of the devices drivers for the board-specific
|
||
resources should go in your ``configs/<board>/src`` directory. However
|
||
if your board is loaded with standard external parts that require
|
||
device drivers – such as an lcd, a touchscreen, serial FLASH,
|
||
accelerometers, etc. – then you will want to re-use or implement
|
||
standard drivers for these parts that can be shared by different
|
||
boards. In that case the ``drivers/`` directory is the correct place
|
||
for those implementations. Header files associated with these
|
||
common drivers would go in the appropriate place under ``include/nuttx/``.
|
||
|
||
7. apps/platform/<board> (maybe)
|
||
================================
|
||
|
||
A final place where you can put application specific data is the
|
||
``apps/platform/<board>`` directory. This is really part of `5.
|
||
Application Directory` if you are using the NuttX ``apps/`` package.
|
||
But since it has a slightly different purpose, it is worth
|
||
discussing separately.
|
||
|
||
The ``apps/platform/`` directory structure is very similar to the
|
||
``nuttx/configs/`` directory with one directory per board. At
|
||
context create time, a symbolic link at ``apps/platform/board``
|
||
is set up to link to the board-specific directory in
|
||
``apps/platform/<board>``.
|
||
|
||
The ``apps/platform/<board>`` directory is where board-specific
|
||
application logic could be placed. This directory is not often
|
||
used. In the normal `flat` Nuttx build, there is really not much
|
||
difference between the ``nuttx/configs/<board>`` board directory
|
||
and the ``apps/platform/<board>`` board directory. Hence the
|
||
former is normally sufficient.
|
||
|
||
The fundamental difference between the two board directories
|
||
is that the ``nuttx/configs/<board>`` board directory is inside
|
||
the operating system while the ``apps/platform/<board>`` directory
|
||
is outside of the operating system. This distinction does not
|
||
mean very much in the `flat` build (``CONFIG_BUILD_FLAT``) because
|
||
nothing enforces `inside`-ness or `outside`-ness in that case.
|
||
But the distinction is very important in protected builds
|
||
(``CONFIG_BUILD_PROTECTED``) and `kernel` builds
|
||
(``CONFIG_BUILD_KERNEL``) because the code operating
|
||
`inside` the OS is privileged, kernel-mode logic;
|
||
the code `outside` of the OS, on the other hand,
|
||
is unprivileged, user-mode code. The two cannot be intermixed. |