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 (u_short bc)
	Commit written buffer space.
char *	NutSegBufReadCommit (size_t bc)
	Commit read buffer space.
void	NutSegBufWriteLast (u_short bc)
	Commit written buffer space and finish write access.
void	NutSegBufReadLast (u_short 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.

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.

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.

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.

char* NutSegBufWriteCommit (  u_short  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.

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.

void NutSegBufWriteLast (  u_short  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.

void NutSegBufReadLast (  u_short  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.

u_long NutSegBufAvailable (  void   )

Return the available buffer space. Returns: Total number of free bytes in the buffer.

u_long NutSegBufUsed (  void   )

Return the used buffer space. Returns: Total number of used bytes in the buffer.

---