Page History

= 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.

http://nuttx.org/Documentation/directories.png?800x391Image RemovedImage Added


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.

...

• <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 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).

...

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:

...

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.

...

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.

...