/ - Diff - Colony - Robotics Club

Revision 78

I2C is documented. This is a pre-merge commit.

     /**
      * @file i2c.h
      * @brief Definitions for i2c.
+     *
      * Definitions for i2c. KEVIN - what is i2c?
+     *
      * @author CMU Robotics Club
      **/
     #ifndef _I2C_H_
     #define _I2C_H_
     #include <stddef.h>
     // for i2c_byte coming from charge board
     //I2C Message Codes
     #define I2C_MSG_ACKNOWLEDGE       'A'
     #define I2C_MSG_BATTERY_CHARGING  'C'
     #define I2C_MSG_DATA              'D'
     #define I2C_MSG_CONTACT_ERROR     'E'
     #define I2C_MSG_BATTERY_FULL      'F'
     #define I2C_MSG_NO_CONTACT        'N'
     #define I2C_MSG_REQUEST_DATA      'R'
     #define I2C_MSG_GO_TO_SLEEP       'Y'
     #define I2C_MSG_ENTERING_SLEEP    'Z'
     char i2c_prev_byte; //store first byte of i2c packet (255 if null)
     // for i2c_register (checked in charging FSM)
     #define I2C_REG_DEFAULT			0
     #define I2C_REG_CHARGING		1
     #define I2C_REG_CONTACT_ERROR	2
     #define I2C_REG_BATTERY_FULL	3
     #define I2C_REG_NO_CONTACT		4
     int i2c_register;
     /** @brief KEVIN **/
     typedef void (*fun_srecv_t)(char);
     /** @brief KEVIN **/
     typedef int (*fun_mrecv_t)(char);
     /** @brief KEVIN **/
     typedef char (*fun_send_t)(void);
     /** @brief KEVIN **/
     int i2c_init(char addr, fun_mrecv_t master_recv, fun_srecv_t slave_recv, fun_send_t slave_send);
     /** @brief KEVIN **/
     void i2c_clear(void);
     /** @brief A function for the master to send data to a slave. **/
     int i2c_send(char dest, char* data, size_t bytes);
     /** @brief KEVIN **/
     int i2c_request(char dest);
     /** @brief KEVIN **/
     void i2c_packet_rec (char i2c_byte);
     /** @brief KEVIN **/
     void i2c_packet_sniff(char data);
     unsigned char i2c_homing_sensor_data;
     unsigned char i2c_homing_sensor_data_dirty;
     //data dirty-ness
     //data is dirty if the user decides so (generally, after it is used and new data is required).
     //the bit set to 1 will mark the data with the same name as dirty.
     //each time a new sensor value is read, the dirty bit is set to fresh, indicating that new data was available.
     #define I2C_DATA_FRESH 0		//fresh = not dirty
     #define I2C_DATA_DIRTY 1		//dirty is true
     #endif

     /* @file i2c.c
      * @brief KEVIN
      * In the case where you have master sends and then a master request to the same
      * address, you will not give up control of the line because the send and
      * request addresses are seen as different addresses. Inbetween it will send a
      * restart but will not give up the line.
+     *
      * @author CMU Robotics Club
      * @bug Not tested.
      */
     #include <avr/interrupt.h>
     #include <util/twi.h>
     #include "i2c.h"
     #include "ring_buffer.h"
     #include "serial.h"
     /* Set bit rate 12 = 100kbit/s (max speed setting is 10 for an
      * 8 MHz clock). It is a divider, so the lower the number the faster the speed.
      */
     #define I2C_BIT_RATE_DIVIDER 0x0C
     static int start_flag;
     static fun_mrecv_t master_recv_function;
     static fun_srecv_t slave_recv_function;
     static fun_send_t slave_send_function;
     RING_BUFFER_NEW(i2c_buffer, 64, char, i2c_write_buff, i2c_addr_buff);
     /**
      * KEVIN - description
+     *
      * @param addr KEVIN
      * @param master_recv KEVIN
      * @param slave_recv KEVIN
      * @param slave_send KEVIN
+     *
      * @return KEVIN
+     *
      **/
     int i2c_init(char addr, fun_mrecv_t master_recv, fun_srecv_t slave_recv, fun_send_t slave_send) {
       master_recv_function = master_recv;
       slave_recv_function = slave_recv;
       slave_send_function = slave_send;
       RING_BUFFER_CLEAR(i2c_write_buff);
       RING_BUFFER_CLEAR(i2c_addr_buff);
       /* enables twi interrupt, automatic ack sending, and all twi hardware */
       TWCR =  (_BV(TWEA) | _BV(TWEN) | _BV(TWIE));
       /* sets the bit rate of data transmission */
       TWBR = I2C_BIT_RATE_DIVIDER;
       /* sets the address (it is stored in the 7 most significant bits) and allows
        * global messages to be accepted */
       TWAR = (addr << 1) | 1;
       i2c_homing_sensor_data_dirty = I2C_DATA_DIRTY;
       return 0;
+    }
     /**
      * KEVIN - description
      **/
     void i2c_clear(void)
+    {
       RING_BUFFER_CLEAR(i2c_write_buff);
       RING_BUFFER_CLEAR(i2c_addr_buff);
       i2c_register = I2C_REG_DEFAULT;
+    }
     /**
      * KEVIN - description
+     *
      * @param dest KEVIN
      * @param data KEVIN
      * @param bytes KEVIN
+     *
      * @return KEVIN
      **/
     int i2c_send(char dest, char *data, size_t bytes) {
       int i;
       /* adding data to be sent to ring buffers is not atomic,
        * so disable interrupts */
       cli();
       for(i = 0; i < bytes; i++) {
         if(RING_BUFFER_FULL(i2c_write_buff)) {
           sei();
           return -1;
+        }
         RING_BUFFER_ADD(i2c_write_buff, data[i]);
         RING_BUFFER_ADD(i2c_addr_buff, dest << 1);
+      }
       sei();
     	/* send the start bit, only if this device is not currently master */
       if(!start_flag) {
         start_flag = 1;
         TWCR |= _BV(TWSTA);
         TWCR |= _BV(TWINT);
+      }
       return 0;
+    }
     /**
      * KEVIN - description
+     *
      * @param dest KEVIN
+     *
      * @return KEVIN
      **/
     int i2c_request(char dest) {
       if(RING_BUFFER_FULL(i2c_write_buff))
         return -1;
       RING_BUFFER_ADD(i2c_write_buff, 0);
       RING_BUFFER_ADD(i2c_addr_buff, (dest << 1) | 1);
       if(!start_flag) {
         start_flag = 1;
         TWCR |= _BV(TWSTA);
         TWCR |= _BV(TWINT);
+      }
       return 0;
+    }
     ISR(TWI_vect) {
       static char data_to_send;
       static char addr_to_send = -1;
       char addr, statusCode;
         //Get status code (only upper 5 bits)
         statusCode = (TWSR & 0xF8);
       switch (statusCode) {
         //Start sent successfully
         case TW_START:
         case TW_REP_START:
           /* Send address and write
            * ring_buffer will not be empty */
           RING_BUFFER_REMOVE(i2c_addr_buff, addr_to_send);
           RING_BUFFER_REMOVE(i2c_write_buff, data_to_send);
           /* first send the address */
           TWDR = addr_to_send;
           //Turn off start bits
           TWCR &= ~_BV(TWSTA);
           break;
         //Master Transmit - Address sent succesfully
         case TW_MT_SLA_ACK:
           //Send byte
           TWDR = data_to_send;
           break;
         //Master Transmit - Data sent succesfully
         case TW_MT_DATA_ACK:
           //If there is still data to send
           if(!RING_BUFFER_EMPTY(i2c_write_buff)) {
             RING_BUFFER_PEEK(i2c_addr_buff, addr);
             //Still data for this address
             if(addr == addr_to_send) {
               RING_BUFFER_REMOVE(i2c_addr_buff, addr);
               RING_BUFFER_REMOVE(i2c_write_buff, TWDR);
               break;
+            }
             //No more data for this address, data for another address -> resend start
             else {
               TWCR |= _BV(TWSTA);
               break;
+            }
+          }
           /* there are no bytes to send */
           TWCR |= _BV(TWSTO);
           start_flag = 0;
           break;
         //Master Receive - Address sent succesfully
         case TW_MR_SLA_ACK:
           break;
         //Master Receive - Data received succesfully
         case TW_MR_DATA_ACK:
           if(master_recv_function) {
             if(!master_recv_function(TWDR)) {
               TWCR &= ~_BV(TWEA);
+            }
+          }
           break;
         case TW_MR_DATA_NACK:
           TWCR |= _BV(TWEA);
           //If there is still data to send
           if(!RING_BUFFER_EMPTY(i2c_write_buff)) {
             TWCR |= _BV(TWSTA);
             break;
+          }
           /* there are no bytes to send */
           TWCR |= _BV(TWSTO);
           start_flag = 0;
           break;
         //Slave Transmit - Address received
         case TW_ST_SLA_ACK:
           break;
         //Slave Transmit - Nack received, no data requsted
         case TW_ST_DATA_NACK:
           break;
         //Slave Transmit - Data requested, ack received
         case TW_ST_DATA_ACK:
           if (slave_send_function) {
             TWDR = slave_send_function();
+          }
           break;
         //Slave Receive - Address received
         case TW_SR_SLA_ACK:
           break;
         //Slave Receive - Data received, ack returned
         case TW_SR_DATA_ACK:
           if(slave_recv_function)
             slave_recv_function(TWDR);
           break;
         //Stop sent
         case TW_SR_STOP:
           break;
+      }
       /* Toggle TWINT so that it resets and executes the commands */
       TWCR |= _BV(TWINT);
+    }
     /**
      * KEVIN - description
      * @param data KEVIN
      **/
     void i2c_packet_sniff(char data) {
       usb_putc(data);
       usb_putc(' ');
+    }
     /**
      * KEVIN - description
+     *
      * @param i2c_byte KEVIN
      **/
     void i2c_packet_rec (char i2c_byte)
+    {
       if(i2c_prev_byte == 'H') {
         usb_puti(i2c_byte);
     	i2c_homing_sensor_data = i2c_byte;
     	i2c_homing_sensor_data_dirty = I2C_DATA_FRESH;
+      }
       else
       	usb_putc(i2c_byte);
       usb_putc(' ');
       i2c_prev_byte = i2c_byte;
       switch(i2c_byte)
+    	{
     		case I2C_MSG_BATTERY_CHARGING:
     			i2c_register = I2C_REG_CHARGING;
     			break;
     		case I2C_MSG_CONTACT_ERROR:
     			i2c_register = I2C_REG_CONTACT_ERROR;
     			break;
     		case I2C_MSG_BATTERY_FULL:
     			i2c_register = I2C_REG_BATTERY_FULL;
     			break;
     		case I2C_MSG_NO_CONTACT:
     			i2c_register = I2C_REG_NO_CONTACT;
     			break;
     		default:
     			i2c_register = I2C_REG_DEFAULT;
     			break;
+    	}
+    }

      * @brief
      * In the case where you have master sends and then a master request to the same
      * address, you will not give up control of the line because the send and
      * request addresses are seen as different addresses. Inbetween it will send a
      * request addresses are seen as different addresses. In between it will send a
      * restart but will not give up the line.
+     *
      * @author CMU Robotics Club
      * @author CMU Robotics Club, Kevin Woo, Sursh Nidhiry
      * @bug Not tested.
      */
-...
      * This code will operate in a multi-master enviornment and can be either a
      * slave or a master at any time (as long as they are not one or the other at
      * the moment. You can queue up multiple transmission modes in the buffer up to
      * the buffer size. The buffer is a ring buffer.
      * the buffer size. The buffer is implemented as a ring buffer.
+     *
      * It is implemented using callback functions. Whenever you want to send a packet
      * you can call the built in send function (as a master) and it will send an array
      * of bytes. Master recieve and slave send/receive are all handled by call back
      * of bytes. Master recieve and slave send/receive are all handled by the call back
      * functions. It is up to the end user to create functions that will handle the
      * receiving of packets. Their functions will be called with every byte recieved
      * so you must either buffer the inputs or handle each one separately.
-...
      *								requests data from you.
      **/
     int i2c_init(char addr, fun_mrecv_t master_recv, fun_srecv_t slave_recv, fun_send_t slave_send) {
       master_recv_function = master_recv;
       slave_recv_function = slave_recv;
       slave_send_function = slave_send;
         master_recv_function = master_recv;
         slave_recv_function = slave_recv;
         slave_send_function = slave_send;
       RING_BUFFER_CLEAR(i2c_write_buff);
       RING_BUFFER_CLEAR(i2c_addr_buff);
         RING_BUFFER_CLEAR(i2c_write_buff);
         RING_BUFFER_CLEAR(i2c_addr_buff);
       /* enables twi interrupt, automatic ack sending, and all twi hardware */
       TWCR =  (_BV(TWEA) | _BV(TWEN) | _BV(TWIE));
         /* enables twi interrupt, automatic ack sending, and all twi hardware */
         TWCR =  (_BV(TWEA) | _BV(TWEN) | _BV(TWIE));
       /* sets the bit rate of data transmission */
       TWBR = I2C_BIT_RATE_DIVIDER;
         /* sets the bit rate of data transmission */
         TWBR = I2C_BIT_RATE_DIVIDER;
       /* sets the address (it is stored in the 7 most significant bits) and allows
        * global messages to be accepted */
       TWAR = (addr << 1) | 1;
         /* sets the address (it is stored in the 7 most significant bits) and allows
          * global messages to be accepted */
         TWAR = (addr << 1) | 1;
       return 0;
         return 0;
+    }
     /**
-...
      *						many bytes from the array that the function will send.
      **/
     int i2c_send(char dest, char *data, size_t bytes) {
       int i;
         int i;
       /* adding data to be sent to ring buffers is not atomic,
        * so disable interrupts */
       cli();
       for(i = 0; i < bytes; i++) {
         if(RING_BUFFER_FULL(i2c_write_buff)) {
           sei();
           return -1;
         /* adding data to be sent to ring buffers is not atomic,
          * so disable interrupts */
         cli();
         for(i = 0; i < bytes; i++) {
             if(RING_BUFFER_FULL(i2c_write_buff)) {
                 sei();
                 return -1;
+            }
             RING_BUFFER_ADD(i2c_write_buff, data[i]);
             RING_BUFFER_ADD(i2c_addr_buff, dest << 1);
+        }
         RING_BUFFER_ADD(i2c_write_buff, data[i]);
         RING_BUFFER_ADD(i2c_addr_buff, dest << 1);
+      }
       /* re-enable the interrupts */
       sei();
     	/* send the start bit, only if this device is not currently master */
       if(!start_flag) {
         start_flag = 1;
         TWCR |= _BV(TWSTA);
         TWCR |= _BV(TWINT);
+      }
         /* re-enable the interrupts */
         sei();
         /* send the start bit, only if this device is not currently master */
         if(!start_flag) {
             start_flag = 1;
             TWCR |= _BV(TWSTA);
             TWCR |= _BV(TWINT);
+        }
       return 0;
         return 0;
+    }
     /**
-...
      * @param dest		The destination that we want to receive information from.
      **/
     int i2c_request(char dest) {
       if(RING_BUFFER_FULL(i2c_write_buff))
         return -1;
         if(RING_BUFFER_FULL(i2c_write_buff))
             return -1;
       RING_BUFFER_ADD(i2c_write_buff, 0);
       RING_BUFFER_ADD(i2c_addr_buff, (dest << 1) | 1);
         RING_BUFFER_ADD(i2c_write_buff, 0);
         RING_BUFFER_ADD(i2c_addr_buff, (dest << 1) | 1);
       if(!start_flag) {
         start_flag = 1;
         TWCR |= _BV(TWSTA);
         TWCR |= _BV(TWINT);
+      }
         if(!start_flag) {
             start_flag = 1;
             TWCR |= _BV(TWSTA);
             TWCR |= _BV(TWINT);
+        }
       return 0;
         return 0;
+    }
     /**
-...
      * Uses the status codes from the I2C register to handle the events
      * needed to advance in I2C stages. For instance, you will get a bit for
      * receiving a start ack, then a address ack, then a data ack, etc.
      * The events are handled in each switch case.
      * The events are handled in each switch case. The status codes are defined
      * by avr-gcc in /util/twi.h but are the same codes as the Atmel documentation.
+     *
      * Bytes are sent by popping off the ring buffer. It also will keep track
      * of what modes the send is in.
+     *
      * Errors are handled here as well.
      **/
      /* @} */
     ISR(TWI_vect) {
       static char data_to_send;
       static char addr_to_send = -1;
       char addr, statusCode;
       //PORTG &= ~_BV(PG2);
     	static char data_to_send;
     	static char addr_to_send = -1;
     	char addr, statusCode;
         //Get status code (only upper 5 bits)
         statusCode = (TWSR & 0xF8);
     	//usb_putc(statusCode);
       switch (statusCode) {
         //Start sent successfully
         case TW_START:
         case TW_REP_START:
           /* Send address and write
            * ring_buffer will not be empty */
           RING_BUFFER_REMOVE(i2c_addr_buff, addr_to_send);
           RING_BUFFER_REMOVE(i2c_write_buff, data_to_send);
           /* first send the address */
           TWDR = addr_to_send;
           //Turn off start bits
           TWCR &= ~_BV(TWSTA);
           break;
     	//Get status code (only upper 5 bits)
     	statusCode = (TWSR & 0xF8);
         //Master Transmit - Address sent succesfully
         case TW_MT_SLA_ACK:
           //Send byte
           TWDR = data_to_send;
     		PORTG &= ~_BV(PG2);
           break;
     	 //Master Transmit - Data sent succesfully
         case TW_MT_DATA_ACK:
           //If there is still data to send
           if(!RING_BUFFER_EMPTY(i2c_write_buff)) {
             RING_BUFFER_PEEK(i2c_addr_buff, addr);
         switch (statusCode) {
             //Start sent successfully
             case TW_START:
             case TW_REP_START:
                 /* Send address and write
                  * ring_buffer will not be empty */
                 RING_BUFFER_REMOVE(i2c_addr_buff, addr_to_send);
                 RING_BUFFER_REMOVE(i2c_write_buff, data_to_send);
                 /* first send the address */
                 TWDR = addr_to_send;
                 //Turn off start bits
                 TWCR &= ~_BV(TWSTA);
                 break;
             //Master Transmit - Address sent succesfully
             case TW_MT_SLA_ACK:
             //Send byte
                 TWDR = data_to_send;
                 PORTG &= ~_BV(PG2);
                 break;
             //Master Transmit - Data sent succesfully
             case TW_MT_DATA_ACK:
                 //If there is still data to send
                 if(!RING_BUFFER_EMPTY(i2c_write_buff)) {
                     RING_BUFFER_PEEK(i2c_addr_buff, addr);
             //Still data for this address
             if(addr == addr_to_send) {
               RING_BUFFER_REMOVE(i2c_addr_buff, addr);
               RING_BUFFER_REMOVE(i2c_write_buff, TWDR);
               break;
+            }
             //No more data for this address, data for another address -> resend start
             else {
               TWCR |= _BV(TWSTA);
               break;
+            }
+          }
                     //Still data for this address
                     if (addr == addr_to_send) {
                         RING_BUFFER_REMOVE(i2c_addr_buff, addr);
                         RING_BUFFER_REMOVE(i2c_write_buff, TWDR);
                         break;
                     //No more data for this address, data for another address -> resend start
                     } else {
                         TWCR |= _BV(TWSTA);
                         break;
+                    }
+                }
                 /* there are no bytes to send */
                 TWCR |= _BV(TWSTO);
                 start_flag = 0;
                 break;
             //Master Transmit - Slave sends a nack, transmit is done
             case TW_MT_DATA_NACK:
                 PORTG |= _BV(PG2);
                 TWCR |= _BV(TWSTO);
                 start_flag = 0;
                 break;
             //Master Receive - Address sent succesfully
             case TW_MR_SLA_ACK:
                 PORTG |= _BV(PG2);
                 break;
             //Master Receive - Data received succesfully
             case TW_MR_DATA_ACK:
                 if(master_recv_function) {
                     if(!master_recv_function(TWDR)) {
                         TWCR &= ~_BV(TWEA);
+                    }
+                }
                 break;
             //Master Receive - Slave sends a nack, transmission is done
             case TW_MR_DATA_NACK:
                 TWCR |= _BV(TWEA);
           /* there are no bytes to send */
           TWCR |= _BV(TWSTO);
           start_flag = 0;
           break;
         case TW_MT_DATA_NACK:
     		PORTG |= _BV(PG2);
     		TWCR |= _BV(TWSTO);
           start_flag = 0;
     		break;
         //Master Receive - Address sent succesfully
         case TW_MR_SLA_ACK:
     	 PORTG |= _BV(PG2);
           break;
         //Master Receive - Data received succesfully
         case TW_MR_DATA_ACK:
           if(master_recv_function) {
             if(!master_recv_function(TWDR)) {
               TWCR &= ~_BV(TWEA);
+            }
+          }
           break;
         case TW_MR_DATA_NACK:
           TWCR |= _BV(TWEA);
                 //If there is still data to send
                 if(!RING_BUFFER_EMPTY(i2c_write_buff)) {
                     TWCR |= _BV(TWSTA);
                     break;
+                }
           //If there is still data to send
           if(!RING_BUFFER_EMPTY(i2c_write_buff)) {
             TWCR |= _BV(TWSTA);
             break;
+          }
           /* there are no bytes to send */
           TWCR |= _BV(TWSTO);
           start_flag = 0;
           break;
                 /* there are no bytes to send */
                 TWCR |= _BV(TWSTO);
                 start_flag = 0;
                 break;
         //Slave Transmit - Address received
         case TW_ST_SLA_ACK:
           break;
         //Slave Transmit - Nack received, no data requsted
         case TW_ST_DATA_NACK:
           break;
         //Slave Transmit - Data requested, ack received
         case TW_ST_DATA_ACK:
           if (slave_send_function) {
             TWDR = slave_send_function();
+          }
           break;
             //Slave Transmit - Address received
             case TW_ST_SLA_ACK:
                 break;
         //Slave Receive - Address received
         case TW_SR_SLA_ACK:
           break;
         //Slave Receive - Data received, ack returned
         case TW_SR_DATA_ACK:
           if(slave_recv_function)
             slave_recv_function(TWDR);
           break;
             //Slave Transmit - Nack received, no data requsted
             case TW_ST_DATA_NACK:
                 break;
             //Slave Transmit - Data requested, ack received
             case TW_ST_DATA_ACK:
                 if (slave_send_function) {
                     TWDR = slave_send_function();
+                }
                 break;
             //Slave Receive - Address received
             case TW_SR_SLA_ACK:
                 break;
             //Slave Receive - Data received, ack returned
             case TW_SR_DATA_ACK:
                 if(slave_recv_function) {
                     slave_recv_function(TWDR);
+                }
                 break;
         //Stop sent
         case TW_SR_STOP:
           break;
     	default:
     		TWCR |= _BV(TWSTO);
           start_flag = 0;
     		RING_BUFFER_CLEAR(i2c_write_buff);
     		RING_BUFFER_CLEAR(i2c_addr_buff);
     	//PORTG |= _BV(PG2);
+      }
             //Stop sent
             case TW_SR_STOP:
                 break;
             //Problem on the bus, reset everything
             default:
                 TWCR |= _BV(TWSTO);
                 start_flag = 0;
                 RING_BUFFER_CLEAR(i2c_write_buff);
                 RING_BUFFER_CLEAR(i2c_addr_buff);
+        }
       /* Toggle TWINT so that it resets and executes the commands */
       TWCR |= _BV(TWINT);
+    }

     /** @file i2c.h
      *  @brief
      *  @brief Header file for I2C
+     *
      *  @author CMU Robotics Club`
      *  @author CMU Robotics Club, Kevin Woo, Suresh Nidhiry
      */
-...
     #include <stddef.h>
     /** @brief */
     /** @brief Address of slave receive handler function */
     typedef void (*fun_srecv_t)(char);
     /** @brief */
     /** @brief Address of master receive handler function*/
     typedef int (*fun_mrecv_t)(char);
     /** @brief */
     /** @brief Address of slave send handler function*/
     typedef char (*fun_send_t)(void);
     /** @brief */
     int i2c_init(char addr, fun_mrecv_t master_recv, fun_srecv_t slave_recv, fun_send_t slave_send);
     /** @brief A function for the master to send data to a slave.
     */
     int i2c_send(char dest, char* data, size_t bytes);
     /** @brief */
     int i2c_request(char dest);
     void i2c_packet_rec (char i2c_byte);

     /** @file Include macros to create a ring buffer. Originally written for 15-410.
      *  Modified for use in ATMega128 serial driver
+     *
      *	@author Cornell Wright (cgwright)
      *	@author Jason P. Winters (jpwinter)
+     *
      *	@bugs Could not create buffer of non byte-sized elements due to modding with sizeof(queue).
      * 		  Fixed 3/2/07, Felix Duvallet and Brad Neuman
      */
     #ifndef _RING_BUFFER_H
     #define _RING_BUFFER_H
     /** @brief Creates the struct for a new ring buffer. This just expands to a
      *	structure definition and thus should be invoked in the global context.
+     *
      *	@param struct_name Name of the ring buffer struct.
+     *
      *	@param size The size of the buffer to create.
+     *
      *	@param type The type of object that the queue is to hold.
+     *
      *	@param ... Name or names of the instance or instances of the ring buffer(s)
      *	to be created.
      */
     #define RING_BUFFER_NEW(struct_name, size, type, ...)	\
     	struct struct_name {	\
     		type queue[size];	\
     		uint8_t start;			\
     		uint8_t end;			\
     		uint8_t buffer_size;			\
     	} __VA_ARGS__
     /** @brief Initializes the ring buffer, setting its size to the correct value
+     *
      *	@param buf The ring buffer to initialize.
+     *
      *  @param size The size of the ring buffer (in array elements)
      */
     #define RING_BUFFER_INIT(buf, size) 			\
     	do {										\
     		(buf).buffer_size = size;				\
     	} while(0)
     /** @brief Sets the specified ring buffer to be empty.
+     *
      *	@param buf The ring buffer to make empty.
      */
     #define RING_BUFFER_CLEAR(buf)	\
     	do {						\
     		(buf).start = 0;		\
     		(buf).end = 0;			\
     	} while (0)
     /** @brief Returns true if the ring buffer specified is empty.
+     *
      *	@param buf The buffer to check emptiness of.
      */
     #define RING_BUFFER_EMPTY(buf) ((buf).start == (buf).end)
     /** @brief Returns true if the ring buffer specified is full.
+     *
      *	@param buf The buffer to check fullness of.
      */
     #define RING_BUFFER_FULL(buf)	\
     		(((buf).end + 1) % (buf).buffer_size == (buf).start)
     /** @brief Adds val to ring buffer buf. Note that val must be of the type
      *	used in creating the ring buffer to prevent the compiler from spewing
      *	confusing errors. Also, this assumes that the ring buffer is not full.
+     *
      *	@param buf The ring buffer to add to.
      *	@param val The value to add.
      */
     #define RING_BUFFER_ADD(buf, val)		\
     	do {								\
     		(buf).queue[(buf).end] = val;	\
     		(buf).end = ((buf).end + 1) % (buf).buffer_size;	\
     	} while (0)
     /** @brief Removes the value at the head of the ring buffer and puts it in
      *	val_ret. Note that val_ret must be the same type used in creating the ring
      *	buffer to prevent the compiler from spewing confusing errors. Also, this
      *	assumes that the ring buffer is not empty.
+     *
      *	@param buf The ring buffer to remove from.
      *	@param val_ret Where to put the value removed from the head of the ring
      *	buffer.
      */
     #define RING_BUFFER_REMOVE(buf, val_ret)	\
     	do {	\
     		(val_ret) = (buf).queue[(buf).start];	\
     		(buf).start = ((buf).start + 1) % (buf).buffer_size;	\
     	} while (0)
     /** @brief Checks the value at the head of the ring buffer without removing it
      *  and puts it into val_ret. Note that val_ret must be the same type used in
      *  creating the ring buffer to prevent the compiler from spewing confusing
      *  errors. Also, this assumes that the ring buffer is not empty.
+     *
      *  @param buf The ring buffer to check from
      *  @param val_ret where to put the value checked from the head of the ring
      */
      #define RING_BUFFER_PEEK(buf, val_ret)  \
       do { \
         (val_ret) = (buf).queue[(buf).start]; \
       } while(0)
     #endif /* _RING_BUFFER_H */

Also available in: Unified diff

Project

General

Profile

Colony

Revision 78