ipc: Document capabilities and limitations of ipc_service backends.

[doki-nordic]

Is your enhancement proposal related to a problem? Please describe.

The ipc_service has multiple backends. Right now there are RPMsg and icmsg. ipc_service has a unified API, but the behavior is significantly different for each backed. The user has no clear information about those differences. This kind of information is needed to choose the correct backend.

Describe the solution you'd like

It would be nice to write information for each backend or one comparison of existing backends. Right now there is no high-level documentation for ipc_service, so where can be placed such information? Maybe also high-level documentation for ipc_service would be nice.

Describe alternatives you've considered

None

Additional context

The limitations that I know about each backend:

• RPMsg
  • no timeout supported when there is no memory available with zero-copy API. Only NO_WAIT is acceptable.
  • the buffer size allocated for zero-copy API is constant and it is 512 bytes by default.
• icmsg
  • only one endpoint per instance is possible.
  • no zero-copy interface. It may be changed in the future, but with a limitation that the messages will be received in the same order as they were allocated which can be different than the send order.
  • no multi-threading safety, the user is responsible for ensuring that only one thread is accessing an instance, e.g. with a mutex.
  • the maximum message size is limited. The limit is configurable (255 by default), increasing it may increase the system work queue stack size.
  • no timeout supported when there is no memory available

Do you know more limitations or any kind of behavior that should be mentioned?

[doki-nordic]

@carlocaione, @emob-nordic, @pdunaj, @nordic-krch, what do you think about adding such information? Do you have some additional things that should be mentioned?

[carlocaione]

the buffer size allocated for zero-copy API is constant and it is 512 bytes by default.

This will change with #45978.

In general I'm ok with this.

[doki-nordic]

the buffer size allocated for zero-copy API is constant and it is 512 bytes by default.

This will change with #45978.

Yes, but still it will be constant per instance, so it is still worth mentioning. The buffer size will be the same for both very small messages and huge messages.

[carlocaione]

Yes, but still it will be constant per instance, so it is still worth mentioning. The buffer size will be the same for both very small messages and huge messages.

Yes, indeed.

[pdunaj]

For RPMsg

no timeout supported

Isn't that the timeout is supported for one side only?

For icmsg it's fine. I think some of these will go away soon but we may update the doc later on.

[eobalski]

I'm okay with providing high level documentation for ipc-service and looking forward to some draft PR with it. I wouldn't put much limitations on backends (yet). Some of limitations you've mentioned are intentionally made.

[carlocaione]

Isn't that the timeout is supported for one side only?

no, limitations is for host and remote.

[doki-nordic]

Some of limitations you've mentioned are intentionally made.

Yes, I am aware of it. They are created by design, and they are not some kind of bug or feature left to be done later.

But, they exists and user should be aware of it. Maybe we should avoid using the limitation word to avoid suggesting that something is wrong with specific backend.

[eobalski]

Some of limitations you've mentioned are intentionally made.

Yes, I am aware of it. They are created by design, and they are not some kind of bug or feature left to be done later.

But, they exists and user should be aware of it. Maybe we should avoid using the limitation word to avoid suggesting that something is wrong with specific backend.

I see we are on the same page. Not 100% sure but maybe its worthwhile to include @hubertmis as i was recently asked if we are planning to add some kind of documentation for icmsg itself. Maybe we could align any requests towards that in this thread.

[hubertmis]

Not 100% sure but maybe its worthwhile to include @hubertmis as i was recently asked if we are planning to add some kind of documentation for icmsg itself.

I was asking about specification of icmsg protocol. If we start porting icmsg to other OSes we need a source of truth how the protocol should behave. It might be a documented specification.

But backends limitations list sounds to me like a separated documentation with a other goal: to help system designer select proper ipc_service backend.

[mkschreder]

I think it is time to make the IPC system not just for hardware IPC but also for registering simple CoAP based endpoints in addition to just being an "interprocessor communication" thing. I'm looking into possibly using it for software only communication between clients.

[eobalski]

I think it is time to make the IPC system not just for hardware IPC but also for registering simple CoAP based endpoints in addition to just being an "interprocessor communication" thing. I'm looking into possibly using it for software only communication between clients.

IIRC IPC-Service was designed for interprocessor communication. If it fits CoAP based endpoitns its fine for me, but this is added value - not something we aim for.