Texas Instruments TMS320 User Manual page 214

Data Pipe Manager (PIP Module)
6.4.4 Calling Order for PIP APIs
6-12
When the HWI routine finishes filling up (reading) a frame and calls PIP_put
(PIP_free), the pipe's notify function can be used to automatically post a
software interrupt. In this case, rather than polling the pipe for frame
availability, the reader (writer) function runs only when the software interrupt
is triggered; that is, when frames are available to be read (written).
Such a function would not need to check for the availability of frames in the
pipe, since it is called only when data is ready. As a precaution, the function
can still check whether frames are ready, and if not, cause an error condition,
as in the following example code
if (PIP_getReaderNumFrames(&readerPipe) = 0) {
error(); /* reader function should not have been posted! */
}
Hence, the notify function of pipe objects can serve as a flow-control
mechanism to manage I/O to other threads and hardware devices.
Each pipe object internally maintains a list of empty frames and a counter with
the number of empty frames on the writer side of the pipe, and a list of full
frames and a counter with the number of full frames on the reader side of the
pipe. The pipe object also contains a descriptor of the current writer frame
(that is, the last frame allocated and currently being filled by the application)
and the current reader frame (that is, the last full frame that the application
got and that is currently reading).
When PIP_alloc is called, the writer counter is decreased by one. An empty
frame is removed from the writer list and the writer frame descriptor is
updated with the information from this frame. When the application calls
PIP_put after filling the frame, the reader counter is increased by one, and the
writer frame descriptor is used by DSP/BIOS to add the new full frame to the
pipe's reader list.
Note:
Every call to PIP_alloc must be followed by a call to PIP_put before
PIP_alloc can be called again: the pipe I/O mechanism does not allow
consecutive PIP_alloc calls. Doing so would overwrite previous descriptor
information and would produce undetermined results. This is shown in
Example 6-3.