Porting Guide for L3 API #940

tymoteuszblochmobica · 2019-02-06T10:47:37Z

Added Layer 3 IP porting connectivity guide

NOTE FOR TECH WRITERS: THIS IS FOR 5.12 ONLY. DO NOT MERGE INTO 5.11.

tymoteuszblochmobica · 2019-02-06T10:49:02Z

@SeppoTakalo please review
@mikaleppanen please review

SeppoTakalo

Small changes requested. Otherwise looks OK.

SeppoTakalo · 2019-02-06T12:16:29Z

docs/porting/connectivity/Layer3IP.md

+
+The scope of this document is limited to advanced cellular modems, where the device presents an additional IP Layer3  interface to send and receive frames, and one of the onboard network stacks that runs on Mbed OS on the host processor uses this.
+
+(If the device has an off-board network stack, a driver needs to implement `NetworkStack` directly instead to pass network calls to the offboard stack).


Remove the () and add link to NetworkStack porting guide.

See [NetworkStack porting guide](networkstack.html)

SeppoTakalo · 2019-02-06T12:20:03Z

docs/porting/connectivity/Layer3IP.md

+
+The first step in the port is to create a driver class for cellular device that you can instantiate to control your device. You must derive this class from the `L3IP` class. A network stack (or test framework) uses this API to control your driver.
+
+The L3IP-derived driver would normally be installed in features/cellular/framework/targets, often in a `TARGET_XXX` directory.


Remove this line, as the porting guide does not need to specify where to place the driver. We allow some flexibility there.

SeppoTakalo · 2019-02-06T12:28:05Z

docs/porting/connectivity/Layer3IP.md

+
+
+### Being the default Interface
+Currently EMAC based  interfaces are created by automated factories and can be default for applications.


This is not specific to EMAC.
Any interface type can be supplied as a default interface.

See https://os.mbed.com/docs/mbed-os/v5.11/apis/network-interfaces.html and scroll down for "Default network interface"

So re-phare this to something like: "In Mbed OS targets may provide default network interfaces through automated factory method"...

SeppoTakalo · 2019-02-06T12:31:41Z

docs/porting/connectivity/Layer3IP.md

+
+### OnboardNetworkStack
+
+The precise details of the `OnboardNetworkStack` API should not concern an L3IP driver writer - it provides the mechanism to bind a driver to a stack, and the APIs needed to implement a `NetworkInterface`, but this is handled  by `L3IPInterface`, either as a base class of your own `XXXInterface`.


I don't understand this sentence:

but this is handled by L3IPInterface, either as a base class of your own XXXInterface.

Either ... or...

Is there an option?

SeppoTakalo · 2019-02-06T12:33:50Z

docs/porting/connectivity/Layer3IP.md

+
+Greentea L3IP tests are in the Mbed OS tree under the `TESTS/network/L3IP` directory.
+
+The driver should also be exercised with real-world examples, such as the [Arm Mbed Client example](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-client/).


I would prefer to leave this out, and just refer to our Socket test plan.
I have seen it too many times that people skip the socket tests and go directly to test with client. This approach might hide lots of bugs in the socket level, as we have seen.

SeppoTakalo · 2019-02-11T10:14:28Z

docs/porting/connectivity/Layer3IP.md

+The scope of this document is limited to advanced cellular modems, where the device presents an additional IP Layer3  interface to send and receive frames, and one of the onboard network stacks that runs on Mbed OS on the host processor uses this.
+
+If the device has an off-board network stack, a driver needs to implement
+ [NetworkStack](https://github.com/ARMmbed//mbed-os-5-docs/blob/development/docs/porting/connectivity/NetworkStack.md)   directly instead to pass network calls to the offboard stack.


This link needs to be fixed.
I think the correct target is https://os.mbed.com/docs/mbed-os/v5.11/porting/networkstack.html

Which is (networkstack.html), or sometimes ../porting/networkstack.html have been used.

SeppoTakalo

Looks OK, but the networkstack porting link needs to be fixed.

SeppoTakalo

Images looks OK now

AnotherButler · 2019-02-12T14:02:04Z

Note to self: 5.12 delivery

AnotherButler · 2019-02-12T21:36:57Z

@tymoteuszblochmobica Thanks for the PR. In the future, if a PR is only applicable for the next release, please let us know in the PR description. Thanks in advance :) [Also, I hope you don't mind I updated your PR description with an obnoxiously bold note to myself.]

AnotherButler

Thanks for the PR 👍 This is great content. Please review my changes to make sure I didn't accidentally change the meaning of anything, and please answer the two questions I've left in comments.

AnotherButler · 2019-02-12T22:14:12Z

docs/porting/connectivity/Layer3IP.md

+
+### IP Layer3 memory manager
+
+The IP Layer3 memory manager class provides an abstracted memory interface toward memory modules used in different network stacks. For the send and receive paths, data is transferred in memory buffers controlled through an `NetStackMemoryManager` object. The network stack, using an L3IP driver, provides it with a reference to the memory manager in use before powering up - this is constant as long as the L3IP is powered.


This last sentence confuses me. Could you please clarify?

It's based on EMAC which has the same memory management arch and behavior.
https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/porting/connectivity/ethernet.md
However to keep it more easy to understand than original i replaced description to:
"The network stack provides L3IP driver with reference to the memory manager before L3IP device powers up."

AnotherButler · 2019-02-12T22:14:52Z

docs/porting/connectivity/Layer3IP.md

+
+To do this, create a C++ class that inherits from both `L3IPInterface` and a base class for the new IP Layer3 cellular interface solution. The `L3IPInterface` is a helper class that implements all the core `NetworkInterface` functionality for you. You then need to implement the extra configuration methods.
+
+You don't usually directly expose the `L3IP` driver class of a cellular driver - it is not usually declared as `L3IP::get_default_instance`. However, passing it to the constructor of your base `L3IPInterface` makes it visible using the `getl3ip` method. 


Is this the first time we mention the getl3ip method? If so, could you please provide some context or a link?

It's also based on EMAC which has the same way of getting driver instance.
https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/porting/connectivity/ethernet.md

Both EMACInterface and L3IPInterface are helper classes provides glue logic between network drivers and network stack.
Methods getl3ip() is similar to wifi/ethernet get_emac() and both are getting driver instance
getl3ip/get_emac is a member of L3IPInterface /EMACInterface

Text replaced to:
" This then makes it visible using the getl3ip method which provides access to L3IP device driver instance. Method getl3ipis a member of L3IPInterface class."

AnotherButler · 2019-02-12T22:22:15Z

docs/porting/connectivity/Layer3IP.md

@@ -0,0 +1,131 @@
+<h2 id="ethernet-port">IP Layer3 (L3IP) drivers</h2>


Please choose another unique heading ID because "ethernet-port" is already used here: https://os.mbed.com/docs/mbed-os/v5.11/porting/ethernet-port.html

@tymoteuszblochmobica use id="l3-porting" here.
The id field is used by the documentation engine to generate the .html file name.

AnotherButler · 2019-02-13T21:48:12Z

It looks like my edits got overwritten. Could you please add them back?

tymoteuszblochmobica · 2019-02-15T14:06:40Z

Edits restored

Edit updated file.

SeppoTakalo suggested changes Feb 6, 2019

View reviewed changes

AnotherButler requested a review from mikaleppanen February 6, 2019 18:34

tymoteuszblochmobica changed the title ~~ONME-3844 Porting Guide for L3 API~~ Porting Guide for L3 API Feb 8, 2019

SeppoTakalo reviewed Feb 11, 2019

View reviewed changes

SeppoTakalo approved these changes Feb 11, 2019

View reviewed changes

SeppoTakalo approved these changes Feb 12, 2019

View reviewed changes

AnotherButler added wait to merge and removed wait to merge labels Feb 12, 2019

AnotherButler reviewed Feb 12, 2019

View reviewed changes

ONME-3844 Porting Guide for L3 API

882b59a

SeppoTakalo mentioned this pull request Feb 19, 2019

Multihoming initial release ARMmbed/mbed-os#9387

Merged

Edit Layer3IP.md

55b5c2a

Edit updated file.

AnotherButler approved these changes Feb 19, 2019

View reviewed changes

AnotherButler merged commit 300f72f into ARMmbed:development Feb 19, 2019


		The scope of this document is limited to advanced cellular modems, where the device presents an additional IP Layer3 interface to send and receive frames, and one of the onboard network stacks that runs on Mbed OS on the host processor uses this.

		(If the device has an off-board network stack, a driver needs to implement `NetworkStack` directly instead to pass network calls to the offboard stack).


		The first step in the port is to create a driver class for cellular device that you can instantiate to control your device. You must derive this class from the `L3IP` class. A network stack (or test framework) uses this API to control your driver.

		The L3IP-derived driver would normally be installed in features/cellular/framework/targets, often in a `TARGET_XXX` directory.



		### Being the default Interface
		Currently EMAC based interfaces are created by automated factories and can be default for applications.


		### OnboardNetworkStack

		The precise details of the `OnboardNetworkStack` API should not concern an L3IP driver writer - it provides the mechanism to bind a driver to a stack, and the APIs needed to implement a `NetworkInterface`, but this is handled by `L3IPInterface`, either as a base class of your own `XXXInterface`.


		Greentea L3IP tests are in the Mbed OS tree under the `TESTS/network/L3IP` directory.

		The driver should also be exercised with real-world examples, such as the [Arm Mbed Client example](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-client/).


		### IP Layer3 memory manager

		The IP Layer3 memory manager class provides an abstracted memory interface toward memory modules used in different network stacks. For the send and receive paths, data is transferred in memory buffers controlled through an `NetStackMemoryManager` object. The network stack, using an L3IP driver, provides it with a reference to the memory manager in use before powering up - this is constant as long as the L3IP is powered.


		To do this, create a C++ class that inherits from both `L3IPInterface` and a base class for the new IP Layer3 cellular interface solution. The `L3IPInterface` is a helper class that implements all the core `NetworkInterface` functionality for you. You then need to implement the extra configuration methods.

		You don't usually directly expose the `L3IP` driver class of a cellular driver - it is not usually declared as `L3IP::get_default_instance`. However, passing it to the constructor of your base `L3IPInterface` makes it visible using the `getl3ip` method.

		@@ -0,0 +1,131 @@
		<h2 id="ethernet-port">IP Layer3 (L3IP) drivers</h2>

Porting Guide for L3 API #940

Porting Guide for L3 API #940

Uh oh!

Conversation

tymoteuszblochmobica commented Feb 6, 2019 • edited by AnotherButler Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tymoteuszblochmobica commented Feb 6, 2019

Uh oh!

SeppoTakalo 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!

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!

SeppoTakalo left a comment

Choose a reason for hiding this comment

Uh oh!

SeppoTakalo left a comment

Choose a reason for hiding this comment

Uh oh!

AnotherButler commented Feb 12, 2019

Uh oh!

AnotherButler commented Feb 12, 2019

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnotherButler commented Feb 13, 2019

Uh oh!

tymoteuszblochmobica commented Feb 15, 2019

Uh oh!

Uh oh!

tymoteuszblochmobica commented Feb 6, 2019 •

edited by AnotherButler

Loading