YAVRTOS

mailbox_t data_mbox;

void get_and_post_data();

void data_consumer_1_task(void *p) {
        int16_t version;
        int *data;
        ...
        version = get_current_mbox_version(&data_mbox);
        while (1) {
                if ((data = (int *)read_mbox_min_version(&data_mbox, &version)) != 0) {
                        do_something_with_the_data(*data);
                }
                release_mbox_read();
                version++;
        }
}

void data_consumer_2_task(void *p) {
        int16_t version;
        int *data;
        ...
        version = get_current_mbox_version(&data_mbox);
        while (1) {
                if ((data = (int *)read_mbox_min_version(&data_mbox, &version)) != 0) {
                        do_something_else_with_the_data(*data);
                }
                release_mbox_read();
                version++;
        }
}

void data_producer_task(void *p) {
        ...
        while (1) {
                ...
                get_and_post_data();
                ...
        }
}

void get_and_post_data() {
        int the_data = get_data_from_some_microcontroller_system();
        write_mbox(&data_mbox, &the_data, 0, 2); // See below...
}

int main() {
        ...
        initialise_mbox(&data_mbox, 0, 0);
        ...
}

The first parameter is the number of reading tasks to wait for. In this case, we decide that we do not wish to wait for any reading task - if there are no tasks waiting to read from the mailbox (i.e. no tasks have suspended themselves on read_mbox_min_version()), then the data will end up being "lost". It is up to the application developer to decide how many tasks, if any, must receive the data.

The second parameter means that, once the data has been put into the mailbox, the data_producer_task will be suspended until all of the tasks that were suspended on read_mbox_min_version() have received the data and have called release_mbox_read(). It also means that, once all the receiving tasks have called release_mbox_read(), the mailbox will contain a new version with a null pointer. This means that the data_producer_task is guaranteed that no-one is going to subsequently try and read the the_data which is important, as the_data is a local variable and hence ceases to exist once get_and_post_data() returns.

Example 2 - sending commands to a task

// This structure contains an instruction for our lcd display driver task
typedef struct lcd_command_struct {
        uint8_t command; // e.g. cursor on, clear display
        char string[21]; // e.g. a string to display
        ...
} lcd_command_t;

// The mailbox that will be used to send instructions to the lcd display driver task
mailbox_t lcd_commands_mbox;

// The lcd display driver task
void lcd_display_driver_task(void *p) {
        lcd_command_t *cmd;
        int16_t version;
        initialise_lcd_display();
        version = get_current_mbox_version(&lcd_commands_mbox);
        while (1) {
                // When we set up the mailbox with initialise_mbox(), we set it up with null data, so our first read is going to return null
                if ((cmd = (lcd_command_t *)read_mbox_min_version(&lcd_commands_mbox, &version)) != 0) {
                        process_lcd_command(cmd);
                }
                release_mbox_read();
                version++;
        }
}

// A task that wants to send something to the LCD
void data_provider_task(void *p) {
        lcd_command_t cmd;
        while (1) {
                get_information_for_lcd(&cmd);
                write_mbox(&lcd_commands_mbox, &cmd, 1, 1); // see below...
        }
}

int main() {
        ...
        initialise_mbox(&lcd_commands_mbox, 0, 0);
        ...
}

Also, we don't want the data_provider_task to make another call to get_information_for_lcd() until the lcd_display_driver_task has finished reading the command we have just sent it (otherwise, get_information_for_lcd() could over-write the information held in the lcd_command before the lcd_display_driver_task has finished with it). By providing a value of one for the wait_for_empty_nullify argument of write_mbox(), we ensure that write_mbox() won't return until the lcd_display_driver_task has executed release_mbox_read().

In this case, there is no need to "nullify" the mailbox after it has been read, because we know that no other task is going to attempt to read it again.

Of course, there is nothing to stop other tasks from using the lcd_commands_mbox - the mailbox is, in effect, a software interface to your LCD that any task can call upon at any time.

Example 3 - sending data from an ISR to a task

// We cannot use a local variable to hold the ISR data, as the data still needs to exist when the ISR exits
int isr_data;

mailbox_t isr_data_mbox;

uint8_t isr() {
        isr_data = read_data_from_some_microcontroller_system();
        write_mbox_now(&isr_data_mbox, &isr_data);
        return 1; // We have (probably) affected a mailbox, so the task switcher needs to run
}

TASK_ISR(xxxx_vect, isr())

void data_reading_task(void *p) {
        int isr_data_local_copy;
        int *i;
        int16_t version = get_current_mbox_version(&isr_data_mbox);
        while (1) {
                if ((i = (int *)read_mbox_min_version(&isr_data_mbox, &version)) != 0) {
                        isr_data_local_copy = *i; // Quickly retrieve the data!
                        release_mbox_read(); // The mailbox is now available to the ISR again
                        process_data(isr_data_local_copy);
                } else {
                        release_mbox_read(); // A good idea to always call this after any attempt to read a mailbox...
                }
                version++;
        }
}

int main() {
        ...
        initialise_mbox(&isr_data_mbox, 0, 0);
        ...
}

Chris O'Byrne - YAVRTOS

Using mailboxes

Example 1 - distributing data throughout the application

Example 2 - sending commands to a task

Example 3 - sending data from an ISR to a task