mirror of
https://github.com/apache/nuttx.git
synced 2026-06-05 07:12:54 +08:00
Documentation: Update some documents affected by the change in the organization of the boards/ sub-directory.
This commit is contained in:
Gregory Nutt
@@ -240,7 +240,7 @@
|
||||
<h1><big><font color="#3c34ec">
|
||||
<i>NuttX RTOS Porting Guide</i>
|
||||
</font></big></h1>
|
||||
<p>Last Updated: August 5, 2019</p>
|
||||
<p>Last Updated: August 8, 2019</p>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
@@ -310,16 +310,20 @@
|
||||
| | | `-- <i>(binfmt-specific source files)</i>
|
||||
| | `-- <i>(common binfmt source files)</i>
|
||||
| |-- <a href="#DirStructConfigs">boards</a>/
|
||||
| | |-- <i><board-name></i>/
|
||||
| | | |-- include/
|
||||
| | | | `-- <i>(other board-specific header files)</i>
|
||||
| | | |-- src/
|
||||
| | | | `-- <i>(board-specific source files)</i>
|
||||
| | | `- configs/
|
||||
| | | |---<i><config-name></i>/
|
||||
| | | | `-- <i>(board configuration-specific source files)</i>
|
||||
| | | `---<i>(other configuration sub-directories for this board)</i>/
|
||||
| | `-- <i><(other board directories)></i>/
|
||||
| | |-- <i><architecture-name></i>/
|
||||
| | | |-- <i><chip-name></i>/
|
||||
| | | | |-- <i><board-name></i>/
|
||||
| | | | | |-- include/
|
||||
| | | | | | `-- <i>(other board-specific header files)</i>
|
||||
| | | | | |-- src/
|
||||
| | | | | | `-- <i>(board-specific source files)</i>
|
||||
| | | | | `- configs/
|
||||
| | | | | |---<i><config-name></i>/
|
||||
| | | | | | `-- <i>(board configuration-specific source files)</i>
|
||||
| | | | | `---<i>(other configuration sub-directories for this board)</i>/
|
||||
| | | | `-- <i><(other board directories)></i>/
|
||||
| | | `-- <i><(other chip directories)></i>/
|
||||
| | `-- <i><(other architecture directories)></i>/
|
||||
| |-- crypto
|
||||
| | |-- Makefile
|
||||
| | |-- Kconfig
|
||||
@@ -527,11 +531,11 @@
|
||||
</p>
|
||||
<p>
|
||||
These board-specific configuration files can be found in the
|
||||
<code>boards/</code><i><board-name></i><code>/</code> sub-directories and are discussed
|
||||
<code>boards/</code><i><arch-name></i><code>/</code><i><chip-name></i><code>/</code><i><board-name></i><code>/</code> sub-directories and are discussed
|
||||
in a paragraph <a href="#boardsdirectorystructure">below</a>.
|
||||
</p>
|
||||
<p>
|
||||
The directory <code>boards/stm32f4disovery/</code>, as an example, holds board-specific logic for the STM32F4 Discovery board and is selected via the <code>CONFIG_ARCH_BOARD="stm32f4discovery"</code> configuration setting.
|
||||
The directory <code>boards/arm/stm32/stm32f4disovery/</code>, as an example, holds board-specific logic for the STM32F4 Discovery board and is selected via the <code>CONFIG_ARCH_BOARD="stm32f4discovery"</code> configuration setting.
|
||||
</p>
|
||||
</li>
|
||||
</ul>
|
||||
@@ -794,15 +798,14 @@
|
||||
|
||||
<h2>2.5 <a name="DirStructConfigs">nuttx/boards</a></h2>
|
||||
<p>
|
||||
The <code>boards/</code> subdirectory contains configuration data for each board.
|
||||
These board-specific configurations plus the architecture-specific configurations in
|
||||
the <code>arch/</code> subdirectory complete define a customized port of NuttX.
|
||||
The <code>boards/</code> subdirectory contains custom logic and board configuration data for each board.
|
||||
These board-specific configurations plus the architecture-specific configurations in the <code>arch/</code> subdirectory complete define a customized port of NuttX.
|
||||
</p>
|
||||
|
||||
<h3><a name="boardsdirectorystructure">2.5.1 Subdirectory Structure</a></h3>
|
||||
<p>
|
||||
The <code>boards/</code> directory contains board specific configuration files. Each board must
|
||||
provide a subdirectory <board-name> under <code>boards/</code> with the following characteristics:
|
||||
provide a sub-directory <board-name> under <code>boards/</code><i><arch-name></i><code>/</code>><i><chip-name></i><code>/</code> with the following characteristics:
|
||||
</p>
|
||||
<ul><pre>
|
||||
<i><board-name></i>
|
||||
@@ -852,7 +855,7 @@
|
||||
</ul>
|
||||
<h4><a name="boardconfigsubdirs">2.5.2.2 Board Specific Configuration Sub-Directories</a></h4>
|
||||
<p>
|
||||
The <code>boards/</code><i><board-name></i><code>/configs</code> sub-directory holds all of the
|
||||
The <code>boards/</code><i><arch-name></i><code>/</code><i><chip-name></i><code>/</code><i><board-name></i><code>/configs</code> sub-directory holds all of the
|
||||
files that are necessary to configure NuttX for the particular board.
|
||||
A board may have various different configurations using the common source files.
|
||||
Each board configuration is described by two files: <code>Make.defs</code> and <code>defconfig</code>.
|
||||
@@ -922,7 +925,7 @@
|
||||
|
||||
<h3><a name="supportedboards">2.5.3 Supported Boards</a></h3>
|
||||
<p>
|
||||
All of the specific boards supported by NuttX are identified in the <a href="https://bitbucket.org/nuttx/nuttx/boards/src/master/README.txt" target="_blank">README.txt</a> file.
|
||||
All of the specific boards supported by NuttX are identified in the <a href="https://bitbucket.org/nuttx/nuttx/src/master/boards/README.txt" target="_blank">README.txt</a> file.
|
||||
</p>
|
||||
<h3><a name="newboardconfig">2.5.4 Adding a New Board Configuration</a></h3>
|
||||
<p>
|
||||
@@ -932,7 +935,7 @@
|
||||
<p>
|
||||
You will need modify the file <code>boards/Kconfig</code>.
|
||||
Let's look at the STM32F4-Discovery configuration in the <code>Kconfig</code> file and see how we would add a new board directory to the configuration.
|
||||
For this configuration let's say that you new board resides in the directory <code>boards/myboard</code>;
|
||||
For this configuration let's say that you new board resides in the directory <code>boards/myarch/mychip/myboard</code>;
|
||||
It uses an MCU selected with <code>CONFIG_ARCH_CHIP_MYMCU</code>; and you want the board to be selected with <code>CONFIG_ARCH_BOARD_MYBOARD</code>.
|
||||
Then here is how you can clone the STM32F4-Discovery configuration in <code>boards/Kconfig</code> to support your new board configuration.
|
||||
</p>
|
||||
@@ -982,7 +985,7 @@ config ARCH_BOARD
|
||||
</pre></ul>
|
||||
<p>
|
||||
This logic will assign string value to a configuration variable called <code>CONFIG_ARCH_BOARD</code> that will name the directory where the board-specific files reside.
|
||||
In our case, these files reside in <code>boards/myboard</code> and we add the following to the long list of defaults (again in alphabetical order):
|
||||
In our case, these files reside in <code>boards/myarch/mychip/myboard</code> and we add the following to the long list of defaults (again in alphabetical order):
|
||||
</p>
|
||||
<ul><pre>
|
||||
default "myboard" if ARCH_BOARD_MYBOARD
|
||||
@@ -991,15 +994,15 @@ config ARCH_BOARD
|
||||
Now the build system knows where to find your board configuration!
|
||||
</p>
|
||||
<p>
|
||||
And finally, add something like this near the bottom of <code>boards/myboard</code>:
|
||||
And finally, add something like this near the bottom of <code>boards/myarch/mychip/myboard</code>:
|
||||
</p>
|
||||
<ul><pre>
|
||||
if ARCH_BOARD_MYBOARD
|
||||
source "boards/myboard/Kconfig"
|
||||
source "boards/myarch/mychip/myboard/Kconfig"
|
||||
endif
|
||||
</pre></ul>
|
||||
<p>
|
||||
This includes additional, board-specific configuration variable definitions in <code>boards/myboard/Kconfig</code>.
|
||||
This includes additional, board-specific configuration variable definitions in <code>boards/myarch/mychip/myboard/Kconfig</code>.
|
||||
</p>
|
||||
|
||||
<h2>2.6 <a name="DirStructCrypto">nuttx/crypto</a></h2>
|
||||
@@ -1557,8 +1560,8 @@ tools/
|
||||
This could be done manually as follows:
|
||||
</p>
|
||||
<ul>
|
||||
<li>Copy <code>boards/</code><i><board-name></i>/<code>configs/[</code><i><config-dir></i><code>/]Make.defs</code> to <code>${TOPDIR}/Make.defs</code> (see NOTE below),</li>
|
||||
<li>Copy <code>boards/</code><i><board-name></i>/<code>configs/[</code><i><config-dir></i><code>/]defconfig</code> to <code>${TOPDIR}/.config</code></li>
|
||||
<li>Copy <code>boards/</code><i><arch-name></i><code>/</code><i><chip-name></i><code>/</code><i><board-name></i><code>/configs/[</code><i><config-dir></i><code>/]Make.defs</code> to <code>${TOPDIR}/Make.defs</code> (see NOTE below),</li>
|
||||
<li>Copy <code>boards/</code><i><arch-name></i><code>/</code><i><chip-name></i><code>/</code><i><board-name></i><code>/configs/[</code><i><config-dir></i><code>/]defconfig</code> to <code>${TOPDIR}/.config</code></li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
@@ -1570,7 +1573,7 @@ tools/
|
||||
And <app-dir> is the location of the optional application directory.
|
||||
</p>
|
||||
<p>
|
||||
NOTE: Recall that the <code>Make.defs</code> file may reside in either the <code>boards/</code><i><board-name></i>/<code>configs/[</code><i><config-dir></i></code> directory or in the <code>boards/</code><i><board-name></i>/<code>scripts</code>.
|
||||
NOTE: Recall that the <code>Make.defs</code> file may reside in either the <code>boards/</code><i><arch-name></i><code>/</code><i><chip-name></i><code>/</code><i><board-name></i>/<code>configs/[</code><i><config-dir></i></code> directory or in the <code>boards/</code><i><arch-name></i><code>/</code><i><chip-name></i><code>/</code><i><board-name></i>/<code>scripts</code>.
|
||||
</p>
|
||||
<p>
|
||||
<b>Automated Configuration</b>.
|
||||
@@ -1717,8 +1720,8 @@ The specific environmental definitions are unique for each board but should incl
|
||||
<li>Auto-generating the file <code>${TOPDIR}/.version</code> with version 0.0 if one does not exist.</li>
|
||||
<li>Auto-generating the file <code>include/nuttx/version.h</code> using the <code>${TOPDIR}/.version</code> file.</li>
|
||||
<li>Creating a link to <code>${TOPDIR}/arch/</code><i><arch-name></i><code>/include</code> at <code>${TOPDIR}/include/arch</code>.</li>
|
||||
<li>Creating a link to <code>${TOPDIR}/boards/</code><i><board-name></i><code>/include</code> at <code>${TOPDIR}/include/arch/board</code>.</li>
|
||||
<li>Creating a link to <code>${TOPDIR}/boards/</code><i><board-name></i><code>/src</code> at <code>${TOPDIR}/arch/</code><i><arch-name></i><code>/src/board</code></li>
|
||||
<li>Creating a link to <code>${TOPDIR}/boards/</code><i><arch-name></i><code>/</code><i><chip-name></i><code>/</code><i><board-name></i><code>/include</code> at <code>${TOPDIR}/include/arch/board</code>.</li>
|
||||
<li>Creating a link to <code>${TOPDIR}/boards/</code><i><arch-name></i><code>/</code><i><chip-name></i><code>/</code><i><board-name></i><code>/src</code> at <code>${TOPDIR}/arch/</code><i><arch-name></i><code>/src/board</code></li>
|
||||
<li>Creating a link to <code>${APPDIR}/include</code> at <code>${TOPDIR}/include/apps</code></li>
|
||||
<li>Creating make dependencies.
|
||||
</ul>
|
||||
@@ -1774,7 +1777,7 @@ The specific environmental definitions are unique for each board but should incl
|
||||
<b>Board-Specific Interfaces</b>.
|
||||
Any interface which is unique to a board should be prefixed with the board name, for example <code>stm32f4discovery_</code>.
|
||||
Sometimes the board name is too long so <code>stm32_</code> would be okay too.
|
||||
These should be prototyped in <code>boards/<board>/src/<board>.h</code> and should not be used outside of that directory since board-specific definitions have no meaning outside of the board directory.
|
||||
These should be prototyped in <code>boards/<arch>/<chip>/<board>/src/<board>.h</code> and should not be used outside of that directory since board-specific definitions have no meaning outside of the board directory.
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
@@ -1799,7 +1802,7 @@ The specific environmental definitions are unique for each board but should incl
|
||||
Keeping in the spirit of the layered architecture, these publicly visible header files must <i>not</i> export platform-specific definitions; Only platform-specific realizations of standardized declarations should be visible.
|
||||
Those <i>standardized declarations</i> should appear in common header files such as those provided by <code>include/nuttx/arch.h</code> and <code>include/nuttx/board.h</code>.
|
||||
Similarly, these publicly visible header file must <i>not</i> include files that reside in the inaccessible platform-specific source directories.
|
||||
For example, the board-specific <code>boards/<board>/include/board.h</code> header file must never include microcontroller-specific header files that reside in <code>arch/<arch>/src/<mcu></code>.
|
||||
For example, the board-specific <code>boards/<arch>/<chip>/<board>/include/board.h</code> header file must never include microcontroller-specific header files that reside in <code>arch/<arch>/src/<mcu></code>.
|
||||
That practice will cause inclusion failures when the publicly visible file is included in common logic outside of the platform-specific source directories.
|
||||
</p>
|
||||
</li>
|
||||
@@ -5216,7 +5219,7 @@ void iob_dump(FAR const char *msg, FAR struct iob_s *iob, unsigned int len,
|
||||
The controller-specific, "upper half" touchscreen drivers reside in the directory <code>drivers/input</code>.
|
||||
</li>
|
||||
<li><b>"Lower Half" Drivers</b>.
|
||||
Platform-specific touchscreen drivers reside in either: (1) The <code>arch/</code><i><architecture></i><code>/src/</code><i><hardware></i> directory for the processor architectures that have build in touchscreen controllers or (2) the <code>boards/</code><i><board></i><code>/src/</code> directory for boards that use an external touchscreen controller chip.
|
||||
Platform-specific touchscreen drivers reside in either: (1) The <code>arch/</code><i><architecture></i><code>/src/</code><i><hardware></i> directory for the processor architectures that have build in touchscreen controllers or (2) the <code>boards/</code><i><arch></i><code>/</code><i><chip></i><code>/</code><i><board></i><code>/src/</code> directory for boards that use an external touchscreen controller chip.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
@@ -6086,7 +6089,7 @@ int kbd_decode(FAR struct lib_instream_s *stream, FAR struct kbd_getstate_s *sta
|
||||
<li>
|
||||
<p>
|
||||
<b>Examples</b>:
|
||||
<code>drivers/lcd/p14201.c</code>, <code>boards/sam3u-ek/src/up_lcd.c.</code>
|
||||
<code>drivers/lcd/p14201.c</code>, <code>boards/arm/sam34/sam3u-ek/src/up_lcd.c.</code>
|
||||
See also the usage of the LCD driver in the <code>graphics/</code> directory.
|
||||
</p>
|
||||
</li>
|
||||
@@ -6378,7 +6381,7 @@ int kbd_decode(FAR struct lib_instream_s *stream, FAR struct kbd_getstate_s *sta
|
||||
</p>
|
||||
<p>
|
||||
<b>Examples</b>:
|
||||
The function <code>nsh_waiter()</code> in the file <code>boards/olimex-lpc1766stk/src/lpc17_40_appinit.c</code>.
|
||||
The function <code>nsh_waiter()</code> in the file <code>boards/arm/lpc17xx_40xx/olimex-lpc1766stk/src/lpc17_40_appinit.c</code>.
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
|
||||
Reference in New Issue
Block a user