Banked Memory
[Application Candies]

Collaboration diagram for Banked Memory:


Detailed Description

Banked RAM support.

Even with a hardware decoder like the one used on the Medianut Board, streaming MP3 data in realtime from a TCP/IP network to the decoder requires some special techniques to make it work on a tiny 8 bit system.

The key to success is avoidance of data copying. Usually data streams are moved from the Ethernet Controller to the Ethernet's driver buffer, then moved to the TCP buffer, again moved to the application buffer and finally from the application buffer to the MP3 decoder buffer. Some systems may use additional steps. Nut/OS tries to avoid these copies. In extreme, the data may be moved directly from the Ethernet controller to the MP3 controller. In reality this will fail, because TCP isn't realtime, but playing MP3 is. So at least one buffer stage is required to compensate the non deterministic arrival of TCP data. Each packet received is moved from the Ethernet controller into a so called NETBUF. Each NETBUF is added to a connection specific queue until the application request data from the connection. For portability reasons and to keep things simple, the application provides a buffer and calls NutTcpReceive() to get that buffer filled with application data out of the queued NETBUFs. This is another copy, but frees the application from dealing with system specific NETBUF structures.

The smart part is, that Nut/OS offers a special buffer management to avoid the final copy into the decoder buffer and that the Nut/OS MP3 decoder driver makes use of this buffer management. As stated, normally the application buffer is filled by some kind of read statement (first copy) and transfered to the driver by some kind of write statement (second copy).

When using the segmented memory management, the application will query the driver for buffer space first and then pass this buffer to the TCP read routine. This way the TCP read routine will directly fill the buffer of the decoder driver. When this has been done, the application commits the buffer filled and requests a new one and so on.

Finally the segmented memory mamagement API can not only handle a continuos memory space, but also one that is divided into several segments. This is usefull with banked memory hardware provided by Ethernut 2 boards.

Todo:
At least some parts should be moved to the device section.


Functions

char * NutSegBufReset (void)
 Reset the segmented buffer.
char * NutSegBufInit (size_t size)
 Initialize the segmented buffer.
char * NutSegBufWriteRequest (size_t *bcp)
 Request segmented buffer space for writing.
char * NutSegBufReadRequest (size_t *bcp)
 Request segmented buffer space for reading.
char * NutSegBufWriteCommit (size_t bc)
 Commit written buffer space.
char * NutSegBufReadCommit (size_t bc)
 Commit read buffer space.
void NutSegBufWriteLast (size_t bc)
 Commit written buffer space and finish write access.
void NutSegBufReadLast (size_t bc)
 Commit written buffer space and finish read access.
u_long NutSegBufAvailable (void)
 Return the available buffer space.
u_long NutSegBufUsed (void)
 Return the used buffer space.


Function Documentation

char* NutSegBufReset ( void   ) 

Reset the segmented buffer.

Returns:
Pointer to the first buffer segment.

Definition at line 79 of file bankmem.c.

References NutSegBufEnable.

Referenced by NutSegBufInit().

char* NutSegBufInit ( size_t  size  ) 

Initialize the segmented buffer.

Parameters:
size Number of bytes to allocate for the global buffer. In systems with banked memory this parameter is ignored and all banked memory is occupied for the global buffer. In systems without banked memory, the specified number of bytes is taken from heap memory.
Returns:
Pointer to the first buffer segment or null on failures.

Definition at line 102 of file bankmem.c.

References NUTBANK_COUNT, NUTBANK_SIZE, NUTBANK_START, NutHeapAlloc(), NutHeapAvailable(), and NutSegBufReset().

Referenced by main().

char* NutSegBufWriteRequest ( size_t *  bcp  ) 

Request segmented buffer space for writing.

This call will also enable the current write segment and may disable the current read segment.

Parameters:
bcp Pointer to a variable, which receives the number of consecutive bytes available for writing.
Returns:
Pointer to the next write position.

Definition at line 132 of file bankmem.c.

References NutSegBufEnable.

char* NutSegBufReadRequest ( size_t *  bcp  ) 

Request segmented buffer space for reading.

This call will also enable the current read segment and may disable the current write segment.

Parameters:
bcp Pointer to a variable, which receives the number of consecutive bytes available for reading.
Returns:
Pointer to the next read position.

Definition at line 155 of file bankmem.c.

References NutSegBufEnable.

char* NutSegBufWriteCommit ( size_t  bc  ) 

Commit written buffer space.

The write pointer will be incremented by the specified number of bytes. If the pointer reaches the end of a segment, the next segment will be enabled and the pointer will point to the start of the new segement.

Parameters:
bc Number of bytes to commit.
Returns:
Pointer to the next write position.

Definition at line 179 of file bankmem.c.

References NUTBANK_COUNT, and NutSegBufEnable.

char* NutSegBufReadCommit ( size_t  bc  ) 

Commit read buffer space.

The read pointer will be incremented by the specified number of bytes. If the pointer reaches the end of a segment, the next segment will be enabled and the pointer will point to the start of the new segement.

Parameters:
bc Number of bytes to commit.
Returns:
Pointer to the next read position.

Definition at line 208 of file bankmem.c.

References NUTBANK_COUNT, and NutSegBufEnable.

void NutSegBufWriteLast ( size_t  bc  ) 

Commit written buffer space and finish write access.

The write pointer will be incremented by the specified number of bytes. This call will also enable the current read segment and may disable the current write segment.

Parameters:
bc Number of bytes to commit.

Definition at line 237 of file bankmem.c.

References NUTBANK_COUNT, and NutSegBufEnable.

void NutSegBufReadLast ( size_t  bc  ) 

Commit written buffer space and finish read access.

The write pointer will be incremented by the specified number of bytes. This call will also enable the current read segment and may disable the current write segment.

Parameters:
bc Number of bytes to commit.

Definition at line 263 of file bankmem.c.

References NUTBANK_COUNT, and NutSegBufEnable.

u_long NutSegBufAvailable ( void   ) 

Return the available buffer space.

Returns:
Total number of free bytes in the buffer.

Definition at line 287 of file bankmem.c.

u_long NutSegBufUsed ( void   ) 

Return the used buffer space.

Returns:
Total number of used bytes in the buffer.

Definition at line 297 of file bankmem.c.

Referenced by VsPlayerFlush().


© 2000-2007 by egnite Software GmbH - visit http://www.ethernut.de/