SerialBuffered.h

00001 /*
00002     Copyright (c) 2010 Andy Kirkham
00003  
00004     Permission is hereby granted, free of charge, to any person obtaining a copy
00005     of this software and associated documentation files (the "Software"), to deal
00006     in the Software without restriction, including without limitation the rights
00007     to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00008     copies of the Software, and to permit persons to whom the Software is
00009     furnished to do so, subject to the following conditions:
00010  
00011     The above copyright notice and this permission notice shall be included in
00012     all copies or substantial portions of the Software.
00013  
00014     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00015     IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00016     FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00017     AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00018     LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00019     OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00020     THE SOFTWARE.
00021 */
00022 
00023 #ifndef SERIALBUFFERED_H
00024 #define SERIALBUFFERED_H
00025 
00026 #include "mbed.h"
00027 
00028 
00029 
00030 /** SerialBuffered based on Serial but fully buffered IO
00031  *
00032  * Example:
00033  * @code
00034  * #include "mbed.h"
00035  * #include "SerialBuffered.h"
00036  *
00037  * SerialBuffered serial1 (p13, p14); 
00038  * SerialBuffered serial2 (p28, p27);
00039  *
00040  * int main() {
00041  *     while(1) {
00042  *         if (serial1.readable()) {
00043  *             while (!serial2.writeable());
00044  *             serial2.putc(serial1.getch());
00045  *         }
00046  *         if (serial2.readable()) {
00047  *             while (!serial1.writeable());
00048  *             serial1.putc(serial2.getc());
00049  *         }
00050  *     }
00051  * }
00052  * @endcode
00053  *
00054  * <b>Note</b>, because this system "traps" the interrupts for the UART
00055  * being used <b>do not</b> use the .attach() method, otherwise the buffers
00056  * will cease functioning. Or worse, behaviour becomes unpredictable.
00057  */
00058 
00059 class SerialBuffered : public Serial {
00060 
00061     public:
00062         enum { None = 0, One = 1, Two = 2 };
00063         enum { WordLength5 = 0, WordLength6 = 1, WordLength7 = 2, WordLength8 = 3 };
00064         enum { NoParity = 0, OddParity = (1UL << 3), EvenParity = (3UL << 3), Forced1 = (5UL << 3), Forced0 = (7UL << 3) };
00065         enum { StopBit1 = (0UL << 2), StopBit2 = (1UL << 2) };
00066         
00067         /** Create a SerialBuffered object connected to the specified pins
00068          *
00069          * @param PinName tx The Mbed TX pin for the uart port.
00070          * @param PinName rx The Mbed RX pin for the uart port.
00071          */
00072         SerialBuffered(PinName tx, PinName rx);
00073         
00074         virtual ~SerialBuffered();
00075         
00076         /** Get a character from the serial stream.
00077          *
00078          * @return char A char value of the character read.
00079          */
00080         char getc(void);
00081         
00082         /** Gets a character from the serial stream with optional blocking.
00083          *
00084          * This method allows for getting a character from the serial stream
00085          * if one is available. If <b>blocking</b> is true, the method will
00086          * wait for serial input if the RX buffer is empty. If <b>blocking</b>
00087          * is false, the method will return immediately if the RX buffer is empty.
00088          * On return, if not blocking and the buffer was empty, -1 is returned.
00089          *
00090          * @param blocking true or false, when true will block.
00091          * @return int An int representation of the 8bit char or -1 on buffer empty.
00092          */
00093         int  getc(bool blocking);
00094         
00095         /** Puts a characher to the serial stream.
00096          *
00097          * This sends a character out of the uart port or, if no room in the
00098          * TX FIFO, will place the character into the TX buffer. <b>Note</b>, if the
00099          * TX buffer is also full, this method will <b>block</b> (wait) until
00100          * there is room in the buffer.
00101          *
00102          * @param int An int representation of the 8bit character to send.
00103          * @return int Always returns zero.
00104          */
00105         int  putc(int c);
00106         
00107         /** Puts a characher to the serial stream.
00108          *
00109          * As with putc(int c) this function allows for a character to be sent
00110          * to the uart TX port. However, an extra parameter is added to allow
00111          * the caller to decide if the method should block or not. If blocking
00112          * is disabled then this method returns -1 to signal there was no room 
00113          * in the TX FIFO or the TX buffer. The character c passed is has not
00114          * therefore been sent.
00115          *
00116          * @param int An int representation of the 8bit character to send.
00117          * @param bool true if blocking required, false to disable blocking.
00118          * @return int Zero on success, -1 if no room in TX FIFO or TX buffer.
00119          */
00120         int  putc(int c, bool blocking);
00121         
00122         /** Are there characters in the RX buffer we can read?
00123          *
00124          * @return int 1 if characters are available, 0 otherwise.
00125          */
00126         int  readable(void);
00127         
00128         /** Is there room in the TX buffer to send a character?
00129          *
00130          * @return int 1 if room available, 0 otherwise.
00131          */
00132         int  writeable(void);
00133         
00134         /** Set's the UART baud rate.
00135          *
00136          * Any allowed baudrate may be passed. However, you should
00137          * ensure it matches the far end of the serial link.
00138          * 
00139          * @param int The baudrate to set.
00140          */
00141         void baud(int baudrate);
00142         
00143         /** Sets the serial format.
00144          *
00145          * Valid serial bit lengths are:-
00146          * <ul>
00147          *  <li>SerialBuffered::WordLength5</li>
00148          *  <li>SerialBuffered::WordLength6</li>
00149          *  <li>SerialBuffered::WordLength7</li>
00150          *  <li>SerialBuffered::WordLength8</li>
00151          * </ul>
00152          *
00153          * Valid serial parity are:-
00154          * <ul>
00155          *  <li>SerialBuffered::NoParity</li>
00156          *  <li>SerialBuffered::OddParity</li>
00157          *  <li>SerialBuffered::EvenParity</li>
00158          *  <li>SerialBuffered::Forced1</li>
00159          *  <li>SerialBuffered::Forced0</li>
00160          * </ul>
00161          *
00162          * Valid stop bits are:-
00163          * <ul>
00164          *  <li>SerialBuffered::None</li>
00165          *  <li>SerialBuffered::One</li>
00166          *  <li>SerialBuffered::Two</li>
00167          * </ul>
00168          *
00169          * @param int bits
00170          * @param int parity
00171          * @param int stopbits
00172          */
00173         void format(int bits, int parity, int stopbits);
00174         
00175         /** Change the TX buffer size
00176          *
00177          * By default, when the SerialBuffer object is created, a default
00178          * TX buffer of 256 bytes in size is created. If you need a bigger
00179          * (or smaller) buffer then use this function to change the TX buffer
00180          * size. 
00181          *
00182          * <b>Note</b>, when a buffer is resized, any previous buffer
00183          * in operation is discarded (destroyed and lost).
00184          *
00185          * @param int The size of the TX buffer required.
00186          */
00187         void set_tx_buffer_size(int buffer_size);
00188         
00189         /** Change the TX buffer size and provide your own allocation.
00190          *
00191          * This methos allows for the buffer size to be changed and for the
00192          * caller to pass a pointer to an area of RAM they have already set
00193          * aside to hold the buffer. The standard method is to malloc space
00194          * from the heap. This method allows that to be overriden and use a
00195          * user supplied buffer. 
00196          *
00197          * <b>Note</b>, the buffer you create must be of the size you specify!
00198          * <b>Note</b>, when a buffer is resized, any previous buffer
00199          * in operation is discarded (destroyed and lost).
00200          *
00201          * @param int The size of the TX buffer required.
00202          * @param char* A pointer to a buffer area you previously allocated.
00203          */
00204         void set_tx_buffer_size(int buffer_size, char *buffer);
00205         
00206         /** Change the RX buffer size
00207          *
00208          * By default, when the SerialBuffer object is created, a default
00209          * RX buffer of 256 bytes in size is created. If you need a bigger
00210          * (or smaller) buffer then use this function to change the RX buffer
00211          * size. 
00212          *
00213          * <b>Note</b>, when a buffer is resized, any previous buffer
00214          * in operation is discarded (destroyed and lost).
00215          *
00216          * @param int The size of the RX buffer required.
00217          */
00218         void set_rx_buffer_size(int buffer_size);
00219         
00220         /** Change the RX buffer size and provide your own allocation.
00221          *
00222          * This methos allows for the buffer size to be changed and for the
00223          * caller to pass a pointer to an area of RAM they have already set
00224          * aside to hold the buffer. The standard method is to malloc space
00225          * from the heap. This method allows that to be overriden and use a
00226          * user supplied buffer. 
00227          *
00228          * <b>Note</b>, the buffer you create must be of the size you specify!
00229          * <b>Note</b>, when a buffer is resized, any previous buffer
00230          * in operation is discarded (destroyed and lost).
00231          *
00232          * @param int The size of the RX buffer required.
00233          * @param char* A pointer to a buffer area you previously allocated.
00234          */
00235         void set_rx_buffer_size(int buffer_size, char *buffer);
00236         
00237     protected:
00238         /** Calculate the divisors for a UART's baud
00239          *
00240          * @param int The desired baud rate
00241          * @param int The UART in use to calculate for
00242          */
00243         uint16_t calculate_baud(int baud, int uart);
00244             
00245     private:
00246         /** set_uart0
00247          *
00248          * Sets up the hardware and interrupts for the UART.
00249          *
00250          * @param PinName tx
00251          * @param PinName rx
00252          */
00253         void set_uart0(PinName tx, PinName rx);
00254         
00255         /** set_uart1
00256          *
00257          * Sets up the hardware and interrupts for the UART.
00258          *
00259          * @param PinName tx
00260          * @param PinName rx
00261          */
00262         void set_uart1(PinName tx, PinName rx);
00263         
00264         /** set_uart2
00265          *
00266          * Sets up the hardware and interrupts for the UART.
00267          *
00268          * @param PinName tx
00269          * @param PinName rx
00270          */
00271         void set_uart2(PinName tx, PinName rx);
00272         
00273         /** set_uart3
00274          *
00275          * Sets up the hardware and interrupts for the UART.
00276          *
00277          * @param PinName tx
00278          * @param PinName rx
00279          */
00280         void set_uart3(PinName tx, PinName rx);
00281         
00282         /** Reset the TX Buffer
00283          *
00284          * @param int The UART buffer to reset.
00285          */
00286         void reset_uart_tx(int uart_number);
00287         
00288         /** Reset the RX Buffer
00289          *
00290          * @param int The UART buffer to reset.
00291          */
00292         void reset_uart_rx(int uart_number);
00293         
00294         /** LPC1768 UART peripheral base address for UART in use.
00295          */
00296         unsigned long uart_base;
00297         
00298         /** LPC1768 UART number for UART in use.
00299          */
00300         int uart_number;
00301 };
00302 
00303 #endif