Create custom-target-porting.md #1130

AnotherButler · 2019-08-12T19:51:32Z

Add and edit content provided about porting Mbed OS to a custom board.

Add and edit content provided about porting Mbed OS to a custom board

iriark01 · 2019-08-14T13:39:23Z

docs/porting/custom-target-porting.md

@@ -0,0 +1,163 @@
+# Porting Mbed OS to a custom board
+
+If you are designing a board similar to an existing Mbed Enabled board, you can use target inheritance to configure your board to meet your needs. In previous versions of Mbed OS (before Mbed OS 5.8), adding a new target required modifying the `mbed-os` directory tree itself, but now you can extend an existing MCU port with a `custom_target.json` file and by adding source files that complete a port outside of `mbed-os`.


What are my needs?

Do I need to know what was going on in versions we don't even have docs for anymore?

...needs, such as different clocking, pin connections, peripheral usage, etc.

iriark01 · 2019-08-14T13:39:50Z

docs/porting/custom-target-porting.md

@@ -0,0 +1,163 @@
+# Porting Mbed OS to a custom board
+
+If you are designing a board similar to an existing Mbed Enabled board, you can use target inheritance to configure your board to meet your needs. In previous versions of Mbed OS (before Mbed OS 5.8), adding a new target required modifying the `mbed-os` directory tree itself, but now you can extend an existing MCU port with a `custom_target.json` file and by adding source files that complete a port outside of `mbed-os`.


Do I need to know what was going on in versions we don't even have docs for anymore?

iriark01 · 2019-08-14T13:40:06Z

docs/porting/custom-target-porting.md

+
+If you are designing a board similar to an existing Mbed Enabled board, you can use target inheritance to configure your board to meet your needs. In previous versions of Mbed OS (before Mbed OS 5.8), adding a new target required modifying the `mbed-os` directory tree itself, but now you can extend an existing MCU port with a `custom_target.json` file and by adding source files that complete a port outside of `mbed-os`.
+
+For detailed information about all the ways you can configure targets, go to [adding and configuring targets](../reference/adding-and-configuring-targets.html).


Then what's in this doc?

How does this fit into the general porting story?

iriark01 · 2019-08-14T13:40:55Z

docs/porting/custom-target-porting.md

+
+For detailed information about all the ways you can configure targets, go to [adding and configuring targets](../reference/adding-and-configuring-targets.html).
+
+## Extending an existing Mbed Enabled MCU target configuration


Isn't Mbed Enabled a specific thing, and not just any board that happens to already have a port?

iriark01 · 2019-08-14T13:41:46Z

docs/porting/custom-target-porting.md

+
+1. Choose a target in Mbed OS that your board can inherit from. 
+
+   If that existing target follows one of the recommended inheritance patterns, such as Family -> MCU -> Board, then it makes it simple to just inherit the MCU target information and add your own board information. In some cases, you may need to inherit a Family or Board and add or replace configurations accordingly.


What's a family?

iriark01 · 2019-08-14T13:42:01Z

docs/porting/custom-target-porting.md

+
+1. Choose a target in Mbed OS that your board can inherit from. 
+
+   If that existing target follows one of the recommended inheritance patterns, such as Family -> MCU -> Board, then it makes it simple to just inherit the MCU target information and add your own board information. In some cases, you may need to inherit a Family or Board and add or replace configurations accordingly.


When? Why? How? Do we have more info somewhere?

iriark01 · 2019-08-14T13:45:30Z

docs/porting/custom-target-porting.md

+
+   The new board target configuration inherits the MCU target, then follows similar configurations to the development kit, including specifying it should build with Mbed OS 5. Also, it uses `device_name nRF52840_xxAA`, which matches the CMSIS pack for that device. The `detect_code` is a unique ID that identifies the board to the Mbed OS test tools.
+
+   <span class="notes">**Note:** Contact the Arm Mbed team to get a unique ID, especially if you plan to have your board coexist with other Mbed Enabled boards while running automated tests.</span>


Oh, is that the detect_code? Then maybe break it out of line 72 so that it more clearly goes with a comment.

iriark01 · 2019-08-14T13:45:56Z

docs/porting/custom-target-porting.md

+1. The new ImaginaryBoard board does not use AnalogIn, and it does not have a Quad SPI. Remove those. 
+
+   1. AnalogIn is an Mbed OS HAL driver, which the MCU target added using `device_has`. Remove it with `device_has_remove`. 
+   1. Similarly, the MCU target added QSPI using `components_add`. Remove it with `components_remove`.


Can I maybe see a before and after of all this?

@maclobdell Can you answer this?

iriark01 · 2019-08-14T13:46:23Z

docs/porting/custom-target-porting.md

+1. (Optional) You can also use `device_has_add` to add additional drivers.
+
+   <span class="notes">**Note:** If you choose to add a driver, you may have to provide the driver implementation if it is not already available for your hardware.</span>
+


Er... that's not a very detailed comment.

iriark01 · 2019-08-14T13:46:36Z

docs/porting/custom-target-porting.md

+
+## Configuring the code directory and folders
+
+The target source code directory should follow a similar structure as the target configuration.


similar as?

iriark01 · 2019-08-14T13:47:59Z

docs/porting/custom-target-porting.md

+
+## Configuring the code directory and folders
+
+The target source code directory should follow a similar structure as the target configuration.


You don't tell me where that directory goes (although I can see in the code block that it goes in mbed-os, it's not obvious that it's mandatory because of how the "For example" sentence is structured)

Standardize formatting for consistency, as requested in comments.

Address some comments.

AnotherButler

@maclobdell Could you please answer these technical questions?

AnotherButler · 2019-08-23T16:15:32Z

docs/porting/custom-target-porting.md

+
+   In this example, there is an MCU target configuration in `mbed-os/targets/targets.json` that the new board can inherit from. It is called MCU_NRF52840.
+
+   Below is a short summary of the MCU target. For simplicity, areas have been omitted.


@maclobdell Can you answer this?

AnotherButler · 2019-08-23T16:15:43Z

docs/porting/custom-target-porting.md

+
+   In this example, the new board is similar to the NRF52840 development kit. 
+
+1. Instead of making edits within `mbed-os`, create a `custom_target.json` file, and put it in a directory alongside `mbed-os`.


@maclobdell Can you answer this?

AnotherButler · 2019-08-23T16:15:50Z

docs/porting/custom-target-porting.md

+   }
+   ```
+
+   The new board target configuration inherits the MCU target, then follows similar configurations to the development kit, including specifying it should build with Mbed OS 5. Also, it uses `device_name nRF52840_xxAA`, which matches the CMSIS pack for that device. The `detect_code` is a unique ID that identifies the board to the Mbed OS test tools.


@maclobdell Can you answer this?

AnotherButler · 2019-08-23T16:15:57Z

docs/porting/custom-target-porting.md

+1. The new ImaginaryBoard board does not use AnalogIn, and it does not have a Quad SPI. Remove those. 
+
+   1. AnalogIn is an Mbed OS HAL driver, which the MCU target added using `device_has`. Remove it with `device_has_remove`. 
+   1. Similarly, the MCU target added QSPI using `components_add`. Remove it with `components_remove`.


@maclobdell Can you answer this?

AnotherButler · 2019-08-23T16:17:42Z

docs/porting/custom-target-porting.md

+
+1. Choose a board in Mbed OS that your board can inherit from. 
+
+   If that existing board follows one of the recommended inheritance patterns, such as Family -> MCU -> Board, then it makes it simple to just inherit the MCU target information and add your own board information. In some cases, you may need to inherit a family or board and add or replace configurations accordingly.


@maclobdell What's a family? Do we have more information about this?
I see we have https://os.mbed.com/docs/mbed-os/v5.13/reference/adding-and-configuring-targets.html, but it only talks about parents and children. Are there other family members?

AnotherButler · 2019-08-28T18:09:36Z

Closing in favor of PR #1145

Create custom-target-porting.md

bc8930c

Add and edit content provided about porting Mbed OS to a custom board

AnotherButler requested a review from iriark01 August 12, 2019 19:52

iriark01 reviewed Aug 14, 2019

View reviewed changes

iriark01 suggested changes Aug 14, 2019

View reviewed changes

AnotherButler requested a review from maclobdell August 14, 2019 14:56

Amanda Butler added 2 commits August 16, 2019 10:19

Fix formatting in custom-target-porting.md

da11b78

Standardize formatting for consistency, as requested in comments.

Address some comments in custom-target-porting.md

a8f6f78

Address some comments.

AnotherButler commented Aug 23, 2019

View reviewed changes

maclobdell mentioned this pull request Aug 28, 2019

Create detailed custom-target-porting.md #1145

Closed

AnotherButler closed this Aug 28, 2019

AnotherButler deleted the AnotherButler-patch-3 branch November 7, 2019 23:11

		@@ -0,0 +1,163 @@
		# Porting Mbed OS to a custom board

		If you are designing a board similar to an existing Mbed Enabled board, you can use target inheritance to configure your board to meet your needs. In previous versions of Mbed OS (before Mbed OS 5.8), adding a new target required modifying the `mbed-os` directory tree itself, but now you can extend an existing MCU port with a `custom_target.json` file and by adding source files that complete a port outside of `mbed-os`.


		If you are designing a board similar to an existing Mbed Enabled board, you can use target inheritance to configure your board to meet your needs. In previous versions of Mbed OS (before Mbed OS 5.8), adding a new target required modifying the `mbed-os` directory tree itself, but now you can extend an existing MCU port with a `custom_target.json` file and by adding source files that complete a port outside of `mbed-os`.

		For detailed information about all the ways you can configure targets, go to [adding and configuring targets](../reference/adding-and-configuring-targets.html).


		For detailed information about all the ways you can configure targets, go to [adding and configuring targets](../reference/adding-and-configuring-targets.html).

		## Extending an existing Mbed Enabled MCU target configuration


		1. Choose a target in Mbed OS that your board can inherit from.

		If that existing target follows one of the recommended inheritance patterns, such as Family -> MCU -> Board, then it makes it simple to just inherit the MCU target information and add your own board information. In some cases, you may need to inherit a Family or Board and add or replace configurations accordingly.


		The new board target configuration inherits the MCU target, then follows similar configurations to the development kit, including specifying it should build with Mbed OS 5. Also, it uses `device_name nRF52840_xxAA`, which matches the CMSIS pack for that device. The `detect_code` is a unique ID that identifies the board to the Mbed OS test tools.

		<span class="notes">Note: Contact the Arm Mbed team to get a unique ID, especially if you plan to have your board coexist with other Mbed Enabled boards while running automated tests.</span>

		1. (Optional) You can also use `device_has_add` to add additional drivers.

		<span class="notes">Note: If you choose to add a driver, you may have to provide the driver implementation if it is not already available for your hardware.</span>


		## Configuring the code directory and folders

		The target source code directory should follow a similar structure as the target configuration.


		In this example, there is an MCU target configuration in `mbed-os/targets/targets.json` that the new board can inherit from. It is called MCU_NRF52840.

		Below is a short summary of the MCU target. For simplicity, areas have been omitted.


		In this example, the new board is similar to the NRF52840 development kit.

		1. Instead of making edits within `mbed-os`, create a `custom_target.json` file, and put it in a directory alongside `mbed-os`.


		1. Choose a board in Mbed OS that your board can inherit from.

		If that existing board follows one of the recommended inheritance patterns, such as Family -> MCU -> Board, then it makes it simple to just inherit the MCU target information and add your own board information. In some cases, you may need to inherit a family or board and add or replace configurations accordingly.

Create custom-target-porting.md #1130

Create custom-target-porting.md #1130

Uh oh!

Conversation

AnotherButler commented Aug 12, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnotherButler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnotherButler commented Aug 28, 2019

Uh oh!

Uh oh!