==================== 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 ```` directory would now be found at ``boards///``. 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: * `` represents the chip architecture that you are using. As examples, `` might represent ``arm`` or ``mips``. * `` represents the specific chip family that you are using. As examples, `` might mean ``stm32`` or ``efm32`` * `` represents the specific board that you are using. As examples, `` might be ``stm32f4discovery`` or ``dk-tm4c129x`` 1. arch//src/ ========================= The ``arch//src/`` 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//include/ ============================= The intent of the ``arch//include/`` directory is to hold driver-related definitions needed by application in order to access drivers registered by the chip-specific logic in the ``arch//src/`` 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//include/`` 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//src/`` directory but are here for historical reasons only at this point. The difference between header files in ``arch//include/`` directory and the header files in ``arch//src/`` directory is that the former can be included by applications using the include path: .. code-block:: c #include The header files in ``arch//src/`` cannot be used by applications. Those header flies can and only be used in the ``arch//src/`` and in the ``configs/`` 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//include ========================== The ``configs//include`` directory is the moral equivalent of the ``arch//include/`` directory for boards: The ``arch//include/`` directory holds chip-specific definitions that are accessible all logic (event even application code). Similarly the ``configs//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//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//src`` directory. The header files in the ``configs//include`` directory can be included using this include path: .. code-block:: c #include 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//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//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//src/`` 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//include/`` directory or from the ``configs//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//src/`` directory or the ``configs//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//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//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/ (maybe) ================================ A final place where you can put application specific data is the ``apps/platform/`` 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/``. The ``apps/platform/`` 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 directory and the ``apps/platform/`` board directory. Hence the former is normally sufficient. The fundamental difference between the two board directories is that the ``nuttx/configs/`` board directory is inside the operating system while the ``apps/platform/`` 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.