Re: IPA monitor (Final RFC)

[Alex Elder <elder@linaro.org>]

Damned double spacing.  I'm not sure why it's happening...	-Alex

In previous messages I explained how the Qualcomm IP Accelerator
(IPA) sometimes has the ability to replicate all packets it
processes, and supply those replicated packets to the main
application processor (AP).  I initially suggested using a network
device as the interface for this, but after some discussion, Jakub
recommended using a debugfs file to supply these packets.

Below is basically a specification for the design I'll use.  It is
what I intend to implement, so if anyone has any objection, please
voice it now.  I'll be sending this code out for review in the
coming few weeks.

Thank you.

					-Alex

- A new debugfs directory "qcom_ipaX" will be created for each IPA
   instance (X = IPA device number).  There's normally only going to
   be one of these, but there is at least one SoC that has two.
     /sys/kernel/debug/qcom_ipa0/
- If an IPA instance supports a "monitor endpoint", a "monitor" file
   will be created in its "qcom_ipaX" directory.
     /sys/kernel/debug/qcom_ipa0/monitor
- The "monitor" file is opened exclusively (no O_EXCL needed).  An
   attempt to open that file when it's already open produces EBUSY.
- The monitor file is read-only (S_IRUSR), and does not support seeks.
- Once opened, "monitor packets" (which consist of a fixed size
   status header, followed by replicated packet data) will be
   accumulated in *receive* buffers.  If a replicated packet is
   large, it will have been truncated by hardware to reduce
   monitoring bandwidth.
- Once opened, reads to the monitor file are satisfied as follows:
     - If no receive buffers have accumulated, the read will block
       until at least one monitor packet can be returned.
     - If the file is opened with O_NONBLOCK, a read that would block
       will return EAGAIN instead of blocking.
     - A read that blocks is interruptible.
     - A valid monitor packet is supplied to user space at most once.
     - Only "complete" monitor packets are supplied to the reader.
       I.e., a status header will always be supplied together with
       the packet data it describes.
     - A *read* buffer will be filled with as many monitor packets as
       possible.  If they'll fit in the read buffer, all accumulated
       monitor packets will be returned to the reader.
     - If the read buffer has insufficient room for the next
       available monitor packet, the read request returns.
     - If any monitor packet received from hardware is bad, it--along
       with everything beyond it in its page--will be discarded.
         - The received data must be big enough to hold a status
	  header.
	- The received data must contain the packet data, meaning
	  packet length in the status header lies within range.