doc: ipc_service_icmsg: update protocol specification to version 1.1 #87337
+214
−41
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The ICMsg backed has been updated to support disconnect and reset detection, as well as to improve the binding process. This commit updates the protocol specification to follow those changes. Signed-off-by: Dominik Kilian <Dominik.Kilian@nordicsemi.no>
doki-nordic
force-pushed
the
icmsg-1.1-proto-docs
branch
from
c76217c to
70cca04
Compare
divipillai
reviewed
Mar 20, 2025
Comment on lines
+82
to
83
| #. The domain (or CPU) writes a magic number to its ``tx-region`` of the shared | ||
| memory. |
There was a problem hiding this comment.
Suggested change
| #. The domain (or CPU) writes a magic number to its ``tx-region`` of the shared | |
| memory. | |
| #. The domain (or CPU) writes a magic number to its ``tx-region`` of the shared memory. |
| For this reason, the specification below focuses on one such pair. | ||
| The other pair is identical. | ||
| Each region and channel pair is used to transfer messages in one direction, while the other pair, which is symmetric, transfers messages in the opposite direction. | ||
| Therefore, the specification below focuses on one such pair, as the other is identical. |
There was a problem hiding this comment.
Suggested change
| Therefore, the specification below focuses on one such pair, as the other is identical. | |
| Therefore, the following specification focuses on one such pair, as the other is identical. |
| The ICMsg provides a single endpoint per instance. | ||
|
|
||
| The ICMsg protocol has been updated to support disconnect and reset detection, as well as to improve the binding process. | ||
| The updated version is referred to as version ``1.1`` in this document, while the initial version is referred to as version ``1.0``. |
There was a problem hiding this comment.
Suggested change
| The updated version is referred to as version ``1.1`` in this document, while the initial version is referred to as version ``1.0``. | |
| The updated version is referred to as version 1.1 in this document, while the initial version is referred to as version 1.0. |
|
|
||
| The ICMsg protocol has been updated to support disconnect and reset detection, as well as to improve the binding process. | ||
| The updated version is referred to as version ``1.1`` in this document, while the initial version is referred to as version ``1.0``. | ||
| Version ``1.1`` is designed to be optionally backward-compatible with version ``1.0``. |
There was a problem hiding this comment.
Suggested change
| Version ``1.1`` is designed to be optionally backward-compatible with version ``1.0``. | |
| Version 1.1 is designed to be optionally backward-compatible with version 1.0. |
|
|
||
| The structure and behavior of packets are the same for both protocol versions. | ||
|
|
||
| Packets are transmitted through the FIFO, as described in the version-specific sections below. |
There was a problem hiding this comment.
Suggested change
| Packets are transmitted through the FIFO, as described in the version-specific sections below. | |
| Packets are transmitted through the FIFO, as described in the following version-specific sections. |
Comment on lines
+273
to
+289
| #. Send a notification to the remote side with MBOX and wait for an incoming notification from the remote side. | ||
|
|
||
| #. The remote side will do the same, so at some point, an MBOX notification will be received. | ||
| The following steps will run in the notification handler. | ||
|
|
||
| #. Read ``remote_sid_req`` and ``local_sid_ack`` from TX region handshake word. | ||
|
|
||
| #. If ``remote_sid_req`` is different from ``remote_sid`` and not equal to ``0``, the remote side has requested a new session. | ||
|
|
||
| - We can now initialize the TX FIFO, since we know that the remote side, during receiving, will first read the FIFO indexes. | ||
| Later, it will check if the session has changed before using indexes to receive the message. | ||
| Additionally, we know that the remote side, after a session request change, will not try to receive more data. | ||
| - Keep ``remote_sid_req`` locally as ``remote_sid``. | ||
| - Write handshake word in RX region with ``local_sid_req`` set to ``local_sid`` and ``remote_sid_ack`` set to ``remote_sid``. | ||
| - The remote SID has changed at this point, so the remote side is able to handle MBOX notifications. | ||
| Notify the remote side with MBOX. | ||
| This final notification is needed in case the remote side started too late and missed the previous notification that was sent when the instance was opened. |
There was a problem hiding this comment.
Suggested change
| #. Send a notification to the remote side with MBOX and wait for an incoming notification from the remote side. | |
| #. The remote side will do the same, so at some point, an MBOX notification will be received. | |
| The following steps will run in the notification handler. | |
| #. Read ``remote_sid_req`` and ``local_sid_ack`` from TX region handshake word. | |
| #. If ``remote_sid_req`` is different from ``remote_sid`` and not equal to ``0``, the remote side has requested a new session. | |
| - We can now initialize the TX FIFO, since we know that the remote side, during receiving, will first read the FIFO indexes. | |
| Later, it will check if the session has changed before using indexes to receive the message. | |
| Additionally, we know that the remote side, after a session request change, will not try to receive more data. | |
| - Keep ``remote_sid_req`` locally as ``remote_sid``. | |
| - Write handshake word in RX region with ``local_sid_req`` set to ``local_sid`` and ``remote_sid_ack`` set to ``remote_sid``. | |
| - The remote SID has changed at this point, so the remote side is able to handle MBOX notifications. | |
| Notify the remote side with MBOX. | |
| This final notification is needed in case the remote side started too late and missed the previous notification that was sent when the instance was opened. | |
| #. Send a notification to the remote side with MBOX and wait for an incoming notification from the remote side. | |
| #. The remote side will do the same, so at some point, an MBOX notification will be received. | |
| The following steps will run in the notification handler. | |
| #. Read ``remote_sid_req`` and ``local_sid_ack`` from TX region handshake word. | |
| #. If ``remote_sid_req`` is different from ``remote_sid`` and not equal to ``0``, the remote side has requested a new session. | |
| * Initialize the TX FIFO, since the remote side, during receiving, will first read the FIFO indexes. | |
| Later, it will check if the session has changed before using indexes to receive the message. | |
| Additionally, the remote side, after a session request change, will not try to receive more data. | |
| * Keep ``remote_sid_req`` locally as ``remote_sid``. | |
| * Write handshake word in RX region with ``local_sid_req`` set to ``local_sid`` and ``remote_sid_ack`` set to ``remote_sid``. | |
| * Notify the remote side with MBOX. | |
| This final notification is needed in case the remote side started too late and missed the previous notification that was sent when the instance was opened. | |
| The remote SID has changed at this point, so the remote side is able to handle MBOX notifications. |
| Packets Transmission and Unbound Detection | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| Once the handshake process is complete, the packet sending procedure remains the same as in version ``1.0``, described above. |
There was a problem hiding this comment.
Suggested change
| Once the handshake process is complete, the packet sending procedure remains the same as in version ``1.0``, described above. | |
| Once the handshake process is complete, the packet sending procedure remains the same as in version 1.0. |
As the Protocol version 1.0 is the next topic.
| #. If there are still packets in the FIFO, repeat the procedure. | ||
|
|
||
| When the instance is closed, set ``local_sid`` and ``local_sid_req`` to ``0`` and send an MBOX notification to the remote. | ||
| This will inform the remote that the connection is unbound. |
There was a problem hiding this comment.
Suggested change
| This will inform the remote that the connection is unbound. | |
| This informs the remote that the connection is unbound. |
| Stop processing incoming packets, ignoring any failures from step 1. | ||
| #. If any failure was detected in step 1, handle it now. | ||
| #. Process the incoming packet, for example, by calling the appropriate callback. | ||
| #. If there are still packets in the FIFO, repeat the procedure. |
There was a problem hiding this comment.
Suggested change
| #. If there are still packets in the FIFO, repeat the procedure. | |
| #. Repeat the procedure, if there are still packets in the FIFO. |
Comment on lines
+311
to
+312
| Stop processing incoming packets, ignoring any failures from step 1. | ||
| #. If any failure was detected in step 1, handle it now. |
There was a problem hiding this comment.
Suggested change
| Stop processing incoming packets, ignoring any failures from step 1. | |
| #. If any failure was detected in step 1, handle it now. | |
| #. Stop processing incoming packets and ignore any failures from step 1. | |
| If any failure was detected in step 1, handle it now. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The ICMsg backed has been updated to support disconnect and reset detection, as well as to improve the binding process. This commit updates the protocol specification to follow those changes.