Andy K
Bug fix release
Dependents: AntiTheftGPS XbeeReceive XbeeSend Superball_Ball2 ... more
MODSERIAL is an easy to use library that extends Serial to add fully buffered input and output.
The features of MODSERIAL include:-
- Directly compatible with Serial
- Fully customisable buffer settings
- Current buffer information via the API
- Circular buffers that allow for dynamic compile-time and/or run-time resizing
- Bulk buffer sending using MODDMA GPDMA direct memory to peripheral data transfers.
Connecting up the MODSERIAL module
The starting point for using MODSERIAL is the Mbed's own handbook for Serial library object. MODSERIAL inherits Serial and adds extensions for buffering. So getting started is easy. Follow the Mbed instructions for Serial to get setup. Here's a reproduction of Serial's simple code starter:-
1 #include "mbed.h"
2
3 Serial pc(USBTX, USBRX); // tx, rx
4
5 int main() {
6 pc.printf("Hello World!");
7 while(1) {
8 pc.putc(pc.getc() + 1);
9 }
10 }
All we need to do to use MODSERIAL is to add a #include and alter one line thus:-
1 #include "mbed.h"
2 #include "MODSERIAL.h"
3 MODSERIAL pc(USBTX, USBRX); // tx, rx
4
5 int main() {
6 pc.printf("Hello World!");
7 while(1) {
8 pc.putc(pc.getc() + 1);
9 }
10 }
As we can see, all we have done is add the header at line 2 and changed line 3 to specify the use of MODSERIAL in replacement for Serial. The default settings for MODSERIAL are that both the TX and RX buffers are assigned 256 bytes each of storage space. This storage space is acquired from the heap using malloc.
The default buffer assignment can be manipulated in three ways. First is the compile time setting which alters the default parameters used when creating a MODSERIAL object. This is done thus:-
1 #include "mbed.h" 2 3 #define MODSERIAL_DEFAULT_RX_BUFFER_SIZE 512 4 #define MODSERIAL_DEFAULT_TX_BUFFER_SIZE 1024 5 #include "MODSERIAL.h" 6 7 MODSERIAL pc(USBTX, USBRX); // tx, rx 8 ...
By defining the two #defines before the #include "MODSERIAL.h" alters the defaults MODSERIAL uses to create it's buffers.
The second method is the run-time version. To get TX at 1024 and RX buffer at 512 as above during run-time initialisation, alter the constructor thus:-
1 #include "mbed.h" 2 #include "MODSERIAL.h" 3 4 // Make TX buffer 1024bytes and RX buffer use 512bytes. 5 MODSERIAL pc(USBTX, USBRX, 1024, 512); // tx, rx 6 ...
If you supply only one numeric value, as shown below, both TX and RX will have the same buffer sizes assigned to them:-
1 #include "mbed.h" 2 #include "MODSERIAL.h" 3 4 // Make both TX and RX use a 512byte buffer. 5 MODSERIAL pc(USBTX, USBRX, 512); // tx, rx 6 ...
The third method is reassigning a new buffer while the program is running. This allows the program to grow and shrink either buffer as required. However, there are caveats to do this as will be shown below.
First, expanding the buffer involves increasing the buffer size. This is fairly straight forward and is accomplished thus:-
1 #include "mbed.h"
2 #include "MODSERIAL.h"
3 MODSERIAL pc(USBTX, USBRX); // tx, rx
4
5 int main() {
6
7 // Increase the TX buffer from the default 256bytes to 1024bytes.
8 if (pc.txBufferSetSize(1024) != MODSERIAL::Ok) {
9 error("Failed to allocate memory for new buffer");
10 }
11
12 pc.printf("Hello World!");
13 while(1) {
14 pc.putc(pc.getc() + 1);
15 }
16 }
As can be seen, growing the buffer is fairly straight forward. However, how it is done should be understood by the user. First, a new buffer allocation is made using malloc. Once acquired the current buffer is checked for contents. If the current buffer is not empty it is copied to the new buffer so the old buffer contents is maintained after resizing. The last step is then to free() the old memory buffer.
The buffer can also be contracted to a smaller length buffer. Here's the code:-
1 #include "mbed.h"
2 #include "MODSERIAL.h"
3 MODSERIAL pc(USBTX, USBRX); // tx, rx
4
5 int main() {
6 int result;
7
8 // Decrease the TX buffer from the default 256bytes to 32bytes.
9 result = pc.txBufferSetSize(32);
10 if (result != MODSERIAL::Ok) {
11 switch(result) {
12 case MODSERIAL::BufferOversize:
13 error("Contents too big to fit into new allocation");
14 break;
15 case MODSERIAL::NoMemory:
16 error("Not enough memory for new allocation");
17 break;
18 }
19 }
11
12 pc.printf("Hello World!");
13 while(1) {
14 pc.putc(pc.getc() + 1);
15 }
16 }
Since buffer resizing involves the copying over of any existing old buffer contents the possibility exists that the current buffer contains more bytes than will fit into the new requested buffer. In these conditions the user must handle the return value of the resize functions. If the contents are of no concern then calling txBufferFlush() to empty of the contents before resizing.
MODSERIAL Interrupts
Users of Serial will be familar with the fact that you can attach functions or methods to TxIrq or RxIrq. This attachment of callbacks allows users to have Interrupt Service Routines (ISR) for both the TX and RX channel of the Uart. MODSERIAL uses both of these callbacks to maintain it's buffers and so are not available to users. However, MODSERIAL does contain five potential callbacks the user can use. These are:-
- TxIrq - This callback is used to inform the user's program that a character was transferred from the TX buffer to the Uart's TX THR FIFO.
- RxIrq - This callback is used to inform the user's program that a character was transferred from the Uart's RX FIFO RBR to the RX buffer.
- RxOvIrq - This callback is used to inform the user's program that a character in the Uart's RX FIFO RBR failed to transfer to the RX buffer because the RX buffer was full. The failed byte is availble via xxGetLastChar() methods.
- TxOvIrq - As RX overflow above
- TxEmpty - This callback is made when the last byte in the TX buffer is transferred to the Uart's TX THR FIFO. It informs the user's program that the TX buffer has become empty. However, it does not mean transmission is complete. See the example1.cpp example for more information.
Delineating "packets"
Many devices send information on RS232 interfaces in distinct "packets". As an example of this is NMEA information sent by many GPS modules. Each NMEA sentence is delineated by a '\n' newline character. Each sentence can be of vary length depending upon the information being sent, however, all are seperated by a '\n' newline. Detecting this if very simple with MODSERIAL. Here's an example:-
#include "mbed.h"
#include "MODSERIAL.h"
// Connect the TX of the GPS module to p10 RX input
MODSERIAL gps(NC, p10);
bool newline_detected = false;
// Called everytime a new character goes into
// the RX buffer. Test that character for \n
// Note, rxGetLastChar() gets the last char that
// we received but it does NOT remove it from
// the RX buffer.
void rxCallback(MODSERIAL_IRQ_INFO *q) {
MODSERIAL *serial = q->serial;
if ( serial->rxGetLastChar() == '\n') {
newline_detected = true;
}
}
int main() {
gps.baud(9600);
gps.attach(&rxCallback, MODSERIAL::RxIrq);
// Wait here until we detect the \n going into the buffer.
while (! newline_detected ) ;
// When we get here the RX buffer now contains a NMEA sentence.
// ...
}
Note, the txGetLastChar() and rxGetLastChar() methods only return the last character but they do not remove that character from the associated buffer.
If this is your first time using MODSERIAL or would just like to test it out then see the example.cpp that comes with the library.
ChangeLog.c
- Committer:
- AjK
- Date:
- 2011-05-10
- Revision:
- 21:af2af4c61c2f
- Parent:
- 20:59c74aaedda2
- Child:
- 22:c11ea36f17f9
File content as of revision 21:af2af4c61c2f:
/* $Id:$
1.21 10 May 2011
* http://mbed.org/forum/mbed/topic/2264
1.20 26 April 2011
* Bug fix, not blocking on transmit
by Erik Petrich, http://mbed.org/forum/bugs-suggestions/topic/2200
1.19 20 April 2011
* Fixed some doxygen comment bugs.
1.18 20 April 2011
* All callbacks now use MODSERIAL_callback (rather than Mbed's FunctionPointer[1] type)
to store and invoke it's callbacks. This allows MODSERIAL to pass a parameter
to callbacks. The function prototype is now void func(MODSERIAL_IRQ_INFO *q).
* Callbacks now pass a pointer to a MODSERIAL_IRQ_INFO class type.
This class holds a pointer to the MODSERIAL object that invoked the callback
thus freeing callbacks need to use the global variable of the original
MODSERIAL instance.
* MODSERIAL_IRQ_INFO also declares public functions that are protected within MODSERIAL
thus allowing certain functions to be restricted to callback context only.
* New function MODSERIAL_IRQ_INFO::rxDiscardLastChar() allows an rxCallback function
to remove the character that was just placed into the RX buffer.
[1] http://mbed.org/users/AjK/libraries/FPointer/latest/docs/
1.17 08/Mar/2011
Fixed a memory leak in the DMA code.
1.16 - 12 Feb 2011
* Missed one, doh!
1.15 - 12 Feb 2011
* Fixed some typos.
1.14 - 7 Feb 2011
* Fixed a bug in __putc() that caused the output buffer pointer to
become corrupted.
1.13 - 20/01/2011
* Added extra documentation.
* Fixed some typos.
1.12 - 20/01/2011
* Added new "autoDetectChar()" function. To use:-
1st: Add a callback to invoke when the char is detected:-
.attach(&detectedChar, MODSERIAL::RxAutoDetect);
2nd: Send the char to detect.
.autoDectectChar('\n');
Whenever that char goes into the RX buffer your callback will be invoked.
Added example2.cpp to demo a simple messaging system using this auto feature.
1.11 - 23/11/2010
* Fixed a minor issue with 1.10 missed an alteration of name change.
1.10 - 23/11/2010
* Rename the DMA callback from attach_dma_complete() to attach_dmaSendComplete()
1.9 - 23/11/2010
* Added support for DMA sending of characters. Required is
the MODDMA library module:-
http://mbed.org/users/AjK/libraries/MODDMA/latest
See example_dma.cpp for more information.
1.8 - 22/11/2010
* Added code so that if a buffer is set to zero length then
MODSERIAL defaults to just using the FIFO for that stream
thus making the library "fall back" to teh same operation
that the Mbed Serial library performs.
* Removed dmaSend() function that should have been removed
at 1.7
1.7 - 21/11/2010
* Remove the DMA enum from MODSERIAL.h as it's not currently
ready for release.
* Added page doxygen comments.
1.6 - 21/11/2010
* Version 1.5 solved a blocking problem on putc() when called
from another ISR. However, isr_tx() invokes a callback of it's
own when a byte is tranferred from TX buffer to TX FIFO. User
programs may interpret that as an IRQ callback. That's an ISR
call from within an existing ISR which is not good. So the
TxIrq callback from isr_tx is now conditional. It will only
be called when isr_tx() is actually within it's own ISR and
not when called from alternate ISR handlers.
1.5 - 21/11/2010
* Calling putc() (or any derived function that uses it like
printf()) while inside an interrupt service routine can
cause the system to lock up if the TX buffer is full. This
is because bytes are only transferred from the TX buffer to
the TX FIFO via the TX ISR. If we are, say in an RX ISR already,
then the TX ISR will never trigger. The TX buffer stays full and
there is never space to putc() the byte. So, while putc() blocks
waiting for space it calls isr_tx() to ensure if TX FIFO space
becomes available it will move bytes from the TX buffer to TX
FIFO thus removing the blocking condition within putc().
1.4 - 21/11/2010
* Removed all the new DMA code. I wish mbed.org had proper SVN
versioning, I'm use to working in HEAD and BRANCHES after I've
released a project. Getting bug reports in current releases
while trying to dev new code is hard to manage without source
control of some type!
1.3 - 21/11/2010
* Fixed a macro problem with txIsBusy()
* Started adding code to use "block data" sending using DMA
* Removed #include "IOMACROS.h"
1.2 - 21/11/2010
* Removed unsed variables from flushBuffer()
* Fixed a bug where both RX AND TX fifos are cleared/reset
when just TX OR RX should be cleared.
* Fixed a bug that cleared IIR when in fact it should be left
alone so that any pending interrupt after flush is handled.
* Merged setBase() into init() as it wasn't required anywhere else.
* Changed init() to enforce _uidx is set by Serial to define the _base
address of the Uart in use.
1.1 - 20/11/2010
* Added this file
* Removed cruft from GETC.cpp
* "teh" should be "the", why do my fingers do that?
1.0 - 20/11/2010
* First release.
*/