readme.txt

这是一个intel网络处理器ixp24xx系列中微码例子。用汇编写的。可以参考一下。

Scratch Ring Example code Readme file
Copyright 2001 Intel

Introduction
============

This is a MEv2 microcode example that illustrates how to use hardware rings in scratch
memory by showing a multi producer - multi consumer ring. Rings are nothing but 
circular buffer/ FIFO. The scratch pad memory supports upto 16 rings. Each ring
has associated with it a head, tail and count, all maintained by the scratch
hardware automatically.

By Multi Producer we mean that more than one thread is producing on to the ring (But not
neccessarily in parallel). These threads operate in strict order in a pipeline.

The producer produces(puts) n words at a time on to the ring and the consumer 
consumes(gets) n words at a time. The producer and the consumer mutually agree
on what "n" is, though it need not be the case.

The important thing to note here is that before producing, producer should always 
check if the ring is full and the consumer, before consuming, should always check 
if the ring is empty.


Ring full can be checked using the input state SCR_Ring#_Full (where # is the ring number
0-F). Note that the Ring full indication is asserted when the ring is near full (actually
at 50% capacity). As a result, it may not be possible to utilize the entire ring capacity
efficiently. This should be kept in mind when deciding the ring size.

The hardware does not prevent overfilling the ring. It is the responsility of the
programmer.

There is not input state for Ring Empty. Instead, the ring will return a zero if you
try to get (consume) from an empty ring. This has the implication that we cannot
put zero onto the ring because when we get from the ring, we won't be able to say if
the ring is empty or the data returned is zero :-(

Another thing to learn from this example when multiple threads are producing in strict order is
what happens when the ring is full. Do we stall (loop) in that thread or do we drop the packet (assuming
we producing packet buffers on to the ring) and proceed to the next thread (which, in all likelihood will
drop the next packet and so on , until space is available in the ring)?

We choose to stall (loop), because that'll maintain the strict order (which in turn will make the 
pipeline deterministic). Also by stalling, we are using less resources so  that these resources (like
SRAM bandwith etc) are now available more easily for the consumer threads which can now finish its
job quickly.

All scratch operations have a latency of about 50 cycles.


What the example does
=====================
ME 0 and Me 1 are the producers and produces(puts) one word (4 bytes) at a time on to the ring.  Thread 0 
of ME 0 produces a word and signals the next thread: thread 1....and so on. Thread 7 of ME 0 will signal
thread 0 of ME1 and thread 7 of ME 1 will signal thread 0 of ME 0.

ME 2 is the consumer which gets one word at a time.  All threads are used. Each thread gets a word and 
signals the next thread.

The size of the ring is 128 and and is at offset 0x1000 in scratch memory. 
This offset should be aligned on a 4 byte boundary. And we use ring number 0.

This example uses inter-thread signal mechanisms. Pls see the "signal" exmaples on how
they work.


Files
=====

multi_producer.uc		: contains producer code for ME 0
multi_producer1.uc		: contains producer code for ME 1
consumer.uc		: contains consumer code for ME 2
scratchring.h		: contains #defines for the ring.
sig_macros.uc		: contains a set of reusable signal macros that are used 
			  by ME0. ME 1& ME2 code.


How to run the code and verify the result
============================================
Set break points in each thread and see the sequence in which the threads are
woken up. Additionally can set breakpoints when the ring is full or ring is empty.