readme.txt

MSP430与DSP接口技术3 编辑环境C语言,未试过,仅供参考

TITLE
-----
SSCR (Shared SCRatch) module

USAGE
-----
RF5

DESCRIPTION
-----------
SSCR is a module to manage the overlaying of XDAIS algorithm's on-chip scratch
memory.

FILES
-----
Each SSCR function is placed in a separate file to avoid dead code, unless 
two or more functions are always dependent; in that case, they are placed
together in a single source file.

- sscr*.pjt: project files for building a library for the appropriate
      architecture
- sscr.c: SSCR private global variables
- sscr.h: SSCR header file
- sscr_createbuf.c: SSCR_createBuf() function
- sscr_deletebuf.c: SSCR_deleteBuf() function
- sscr_exit.c: SSCR_exit() function
- sscr_getbuf.c: SSCR_getBuf() function
- sscr_init.c: SSCR_init() function
- sscr_prime.c: SSCR_prime() function
- sscr_setup.c: SSCR_setup() function
- ../include/sscr.h: public header file for the SSCR module
- readme.txt: this file

NOTE
----
Files in the library are compiled with no optimization switches turned on,
and the same is true for the project files. If you plan to use this module 
in a product release, it is advised that you rebuild the library with 
optimization turned on.

The UTL module is used by the SSCR module.  UTL_assert is used to check 
parameters passed into the various functions.  This is to aid in debugging.
For your production code, it is advised that you rebuild the library with 
UTL_assert turned off.

Q&A
---
Q1: What memory is being overlaid?
Q2: How can the scratch memory be overlaid?
Q3: What is a SSCR_bucket?
Q4: Why must SSCR_prime() be called before SSCR_createBuf()?
Q5: Is the SSCR module thread-safe?
Q6: Why would I want to pre-define the buckets in SSCR_setup?

---
Q1: What memory is being overlaid?
A1: XDAIS algorithms request memory from the application. This is done to
    remove memory management from the algorithm.  
    Scratch memory is memory that is freely used by an algorithm without regard
    to its prior contents, i.e. no assumptions about the content can be made 
    by the algorithm and the algorithm is free to leave it in any state.
    Thus, multiple algorithm can share the same scratch memory.  

---
Q2: How can the scratch memory be overlaid?    
A2: Given that an algorithm cannot block during the execution of a runtime 
    execution function, scratch memory can be shared among other algorithms.
    There is one major caveat with this: since BIOS is a preemptive OS (one 
    thread can interrupt another thread), special measures must be taken to 
    prevent corruption of the scratch memory. 
    In BIOS, only threads of a higher priority can preempt a thread, therefore
    a thread of an equal or lower priority cannot preempt a thread. So scratch
    memory can safely be shared among all thread of the same priority.  This is
    called the "by priority" scratch overlaying method. An alternate method of
    scratch overlaying is to have one large scratch buffer that all algorithms 
    use. Locking mechanisms (e.g. semaphores, HWI_disable/restore, etc.) must be
    used to protect against preemption. This is called the "single" scratch 
    overlaying method.
    The "by priority" method has less latency issues, but results in a larger 
    total scratch buffer allocation. The "single" scratch method minimizes 
    memory allocation, but increases latency during the exection of the 
    algorithms.  All applications are different and it is up to the integrator 
    to determine which method or combination is best for them.

---
Q3: What is a SSCR_bucket?
A3: In the "by priority" scratch overlaying method, all algorithms with the 
    same priority will share the same scratch buffer.  This scratch buffer is
    maintained in a SSCR_bucket.  The SSCR_bucket contains the pointer to the
    buffer, size of the buffer and the number of algorithms using the buffer. 

---
Q4: Why must SSCR_prime() be called before SSCR_createBuf()?
A4: The SSCR_prime() does not allocate anything.  It simply determines the
    worst case scratch requirements.  Therefore, SSCR_prime() must be called
    on all algorithms in the system first.  Then SSCR_createBuf() can be called
    to actually allocate the memory.

---
Q5: Is the SSCR module thread-safe?
A5: Yes.  All APIs are thread-safe within the box of the API calling
    sequence specified below.  
                                                  -----------
                                                  |         |
                                                  v         |
    --------------     --------------     ----------------  |
    | SSCR_init  | --> | SSCR_setup | --> | SSCR_prime   |---
    --------------     --------------     ----------------
                                                  |
                                                  |  ----------
                                                  |  |        |
                                                  v  v        |
                                          ------------------   |
                                          | SSCR_createBuf@|----
                                          | SSCR_getBuf    |
                                          | SSCR_deleteBuf@|
                                          ----------------   
                                                  |  
                                                  |  
                                                  v  
                                          ----------------
                                          | SSCR_exit    |
                                          ----------------   
   Additional notes
     @ = must have created a scratch buffer before you can delete it. 

---
Q6: Why would I want to pre-define the buckets in SSCR_setup?
A6: In a dynamic system, the initial configuration might not be the 
    worst-case requirements.  With allowing the integrator to define
    the bucket sizes and supply the buffers, the addition of new algorithms
    during runtime is easier.