diff --git a/Documentation/NuttxPortingGuide.html b/Documentation/NuttxPortingGuide.html index 04b746b5982..27d60da6445 100644 --- a/Documentation/NuttxPortingGuide.html +++ b/Documentation/NuttxPortingGuide.html @@ -12,7 +12,7 @@

NuttX RTOS Porting Guide

-

Last Updated: January 31, 2018

+

Last Updated: February 14, 2018

@@ -1563,6 +1563,31 @@ The specific environmental definitions are unique for each board but should incl Sometimes the board name is too long so stm32_ would be okay too. These should be prototyped in configs/<board>/src/<board>.h and should not be used outside of that directory since board-specific definitions have no meaning outside of the board directory. +
  • +

    + Scope of Inclusions. + Header files are made accessible to internal OS logic and to applications through include paths that are provided to the C/C++ compiler. + Through these include paths, the NuttX build system also enforces modularity in the design. + For example, one important design principle is architectural layering. + In this case I am referring to the OS as layered in to application interface, common internal OS logic, and lower level platform-specific layers. + The platform-specific layers all reside in the either arch/ sub-directorories on the config/ subdirectories: The former sub-directories are reserved for microcontroller-specific logic and the latter for board-specific logic. +

    +

    + In the strict, layered NuttX architecture, the upper level OS services are always available to platform-specific logic. However, the opposite is not true: Common OS logic must never have any dependency on the lower level platform-specific code. The OS logic must be totally agnostic about its hardware environment. Similarly, microcontroller-specific logic was be completely ignorant of board-specific logic. +

    +

    + This strict layering is enforced in the NuttX build system by controlling the compiler include paths: Higher level code can never include header files from either; of the platform-specific source directories; microcontroller-specific code can never include header files from the board-specific source directories. The board-specific directories are, then, at the bottom of the layered hierarchy. +

    +

    + An exception to these inclusion restrictions is the platform-specific include/. These are made available to higher level OS logic. The microcontroller-specific include directory will be linked at include/arch/chip and, hence, can be included like #include <arch/chip/chip.h. + Similarly, the board-specific include directory will be linked at include/arch/board and, hence, can be included like #include <arch/board/board.h. +

    +

    + Keeping in the spirit of the layered architecture, this publicly visible header files must not export platform-specific definitions; Only standardized definitions should be visible such as those provided in include/nuttx/arch.h or include/nuttx/board.h. + And, similarly, these publicly visible header file must not include files that reside in the inaccessible platform-specific source directories. + That practice will cause inclusion failures when the publicly visiable file is included in common logic outside of the platform-specific source directories. +

    +

    • 4.2 APIs Exported by Architecture-Specific Logic to NuttX

    @@ -3852,7 +3877,7 @@ void sched_timer_expiration(void);

    NOTE: The other interfaces described in this document are internal OS interface. boardctl() is an application interface to the OS. - There is not point, in fact, of using boardctl() within the OS; + There is no point, in fact, of using boardctl() within the OS; the board interfaces prototyped in include/nuttx/board.h may be called directly from within the OS.