IPA monitor (Final RFC)

[Alex Elder <elder@linaro.org>]

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.