pw_channel: Add guidance about when to implement Channel

Change-Id: I069ac99abbce5487706c3ef951600ce80fda79fa
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/247353
Commit-Queue: Taylor Cramer <[email protected]>
Reviewed-by: Wyatt Hepler <[email protected]>
Lint: Lint 🤖 <[email protected]>
Reviewed-by: Kayce Basques <[email protected]>

pw_channel/guides.rst

@@ -12,6 +12,40 @@ Quickstart & guides
 Frequently asked questions (FAQs)
 ---------------------------------
 
+My API reads and writes data. Should I implement the ``Channel`` interface, or should my API accept a ``Channel`` to read from and write into?
+==============================================================================================================================================
+Users should typically only implement the ``Channel`` interface themselves if
+they want to control where buffers for underlying data are stored.
+
+On the read side, the channel implementation controls buffer allocation by
+choosing how to allocate the ``MultiBuf`` values that are returned from
+``PendRead``.
+
+On the write side, the channel implementation controls buffer allocation via
+its implementation of the ``PendAllocateWriteBuffer`` method.
+
+Most commonly, lower layers of the communications stack implement ``Channel`` in
+order to provide buffers that are customized to the needs of the underlying
+transport. For example, a UART DMA channel might need to allocate buffers
+out of particular DMA-compatible memory regions, with a particular alignment,
+or of a particular MTU size.
+
+The top-level or application layer should typically work with provided
+channel implementations in order to allow the lower layers to control
+allocation and minimize copies.
+
+Intermediate layers of the stack should generally give preference to
+allowing lower layers of the stack to allocate, and so should implement
+a channel interface for the higher layer by delegating to the lower layer.
+When intermediate layers must copy data (are incompatible with zero-copy),
+they should prefer to accept channels from both the higher and lower
+layers so that both the application layer and lower layers can choose
+how to manage memory allocations.
+
+When necessary, two APIs that accept channels can be paired together
+using a ``ForwardingChannel`` which manages allocations by delegating
+to the provided ``MultiBufAllocator``.
+
 Can different tasks write into and read from the same channel?
 ==============================================================
 No; it is not possible to read from the channel in one task while