CurieMailbox: refactor in preparation for Serial

The Serial class will soon be using the mailbox to transfer data between
cores. This refactor prepares the library for that, by moving the HW
access code into cores/arduino, and implementing per-channel callback
functions

Author: eriknyquist

cores/arduino/mailbox.cpp

@@ -0,0 +1,163 @@
+#include <string.h>
+#include "interrupt.h"
+#include "scss_registers.h"
+#include "mailbox.h"
+
+#define CHANNEL_STS_MASK            0x1
+#define CHANNEL_INT_MASK            0x2
+#define CTRL_WORD_MASK              0x7FFFFFFF
+#define CHALL_STATUS_MASK           0xFFFF
+#define CHANNEL_STS_BITS            (CHANNEL_STS_MASK | CHANNEL_INT_MASK)
+
+/* Mailbox channel status register */
+#define IO_REG_MAILBOX_CHALL_STS    (SCSS_REGISTER_BASE + 0xAC0)
+
+typedef struct mbox_channel mbox_channel_t;
+typedef struct mbox_intmask mbox_intmask_t;
+
+/* Represents the registers for a single mailbox channel */
+struct mbox_channel {
+    uint32_t ctrl;
+    uint32_t data[CHANNEL_DATA_WORDS];
+    uint32_t sts;
+};
+
+/* Mailbox interrupt mask; right now we only care about the
+ * second byte, for SS mailbox interrupts (one bit per mailbox channel) */
+struct mbox_intmask {
+    uint8_t lmt_intmask;
+    uint8_t ss_intmask;
+    uint8_t lmt_halt;
+    uint8_t ss_halt;
+};
+
+static volatile mbox_intmask_t *intmask;
+static volatile mbox_channel_t *mbox;
+static void (*callbacks[NUM_MAILBOX_CHANNELS])(CurieMailboxMsg);
+
+void mailbox_register (int channel, void(*callback)(CurieMailboxMsg))
+{
+    if (channel >= 0 && channel < NUM_MAILBOX_CHANNELS) {
+        callbacks[channel] = callback;
+    }
+}
+
+void mailbox_unregister (int channel)
+{
+    if (channel >= 0 && channel < NUM_MAILBOX_CHANNELS) {
+        callbacks[channel] = 0;
+    }
+}
+
+void mailbox_disable_receive (int channel)
+{
+    intmask->ss_intmask |= 1 << channel;
+}
+
+void mailbox_enable_receive (int channel)
+{
+    intmask->ss_intmask &= ~(1 << channel);
+}
+
+static void do_callback (int channel, CurieMailboxMsg& msg)
+{
+    void (*cb)(CurieMailboxMsg) = callbacks[channel];
+    if (cb) {
+        cb(msg);
+    }
+}
+
+static void mailbox_read (int channel, CurieMailboxMsg& msg)
+{
+    unsigned int i;
+
+    /* Copy channel data into CurieMailboxMsg object */
+    msg.id = mbox[channel].ctrl & CTRL_WORD_MASK;
+    msg.channel = channel;
+
+    for (i = 0; i < CHANNEL_DATA_WORDS; ++i) {
+        msg.data[i] = mbox[channel].data[i];
+    }
+
+    /* Clear channel status & interrupt flags */
+    mbox[channel].sts |= CHANNEL_STS_BITS;
+}
+
+void mailbox_write (CurieMailboxMsg msg)
+{
+    int i;
+    uint32_t key;
+
+    /* Can't write if channel status flag is set */
+    while ((mbox[msg.channel].sts & CHANNEL_STS_MASK));
+    key = interrupt_lock();
+
+    /* Poplate channel payload */
+    mbox[msg.channel].ctrl |= (msg.id & CTRL_WORD_MASK);
+    for (i = 0; i < CHANNEL_DATA_WORDS; ++i) {
+        mbox[msg.channel].data[i] = msg.data[i];
+    }
+
+    /* Trigger interupt to host */
+    mbox[msg.channel].ctrl |= ~(CTRL_WORD_MASK);
+
+    /* Wait for HW to set the channel status bit */
+    while (!(mbox[msg.channel].sts & CHANNEL_STS_MASK));
+
+    /* Wait for destination processor to clear channel status bit */
+    while ((mbox[msg.channel].sts & CHANNEL_STS_MASK));
+    interrupt_unlock(key);
+}
+
+static uint16_t get_chall_sts (void)
+{
+    return MMIO_REG_VAL(IO_REG_MAILBOX_CHALL_STS) & CHALL_STATUS_MASK;
+}
+
+static void mailbox_isr (void)
+{
+    int i;
+    uint32_t sts;
+    CurieMailboxMsg msg;
+
+    sts = get_chall_sts();
+    /* Get channel number */
+    for (i = 0; i < NUM_MAILBOX_CHANNELS; ++i) {
+        if (sts & (1 << (i * 2 + 1))) {
+            break;
+        }
+    }
+
+    mailbox_read(i, msg);
+    do_callback(i, msg);
+}
+
+static void mailbox_hardware_init (void)
+{
+    int i;
+
+    for (i = 0; i < NUM_MAILBOX_CHANNELS; ++i) {
+        mbox[i].sts &= ~(CHANNEL_STS_BITS);
+    }
+}
+
+static void mailbox_interrupts_init (bool master)
+{
+    interrupt_disable(SOC_MBOX_INTERRUPT);
+
+   /* Mask SS mailbox interrupts for all channels;
+    * Unmasking is done by enableReceive */
+    intmask->ss_intmask = 0xFF;
+
+    if (master) mailbox_hardware_init();
+    interrupt_connect(SOC_MBOX_INTERRUPT, mailbox_isr);
+    interrupt_enable(SOC_MBOX_INTERRUPT);
+}
+
+void mailbox_init (bool master)
+{
+    intmask = (mbox_intmask_t *)IO_REG_MAILBOX_INT_MASK;
+    mbox = (mbox_channel_t *)IO_REG_MAILBOX_BASE;
+    memset(callbacks, 0, sizeof(callbacks));
+    mailbox_interrupts_init(master);
+}

cores/arduino/mailbox.h

@@ -0,0 +1,21 @@
+#ifndef _MAILBOX_H_
+#define _MAILBOX_H_
+
+#define NUM_MAILBOX_CHANNELS 8
+#define CHANNEL_DATA_WORDS   4
+
+class CurieMailboxMsg {
+public:
+    uint32_t data[CHANNEL_DATA_WORDS];
+    uint32_t id;
+    int channel = 0;
+};
+
+void mailbox_init (bool master);
+void mailbox_register (int channel, void(*callback)(CurieMailboxMsg));
+void mailbox_unregister (int channel);
+void mailbox_enable_receive (int channel);
+void mailbox_disable_receive (int channel);
+void mailbox_write(CurieMailboxMsg msg);
+
+#endif

libraries/CurieMailbox/README.txt

@@ -0,0 +1,111 @@
+CurieMailbox library for Arduino/Genuino 101
+
+Overview:
+
+This library provides access to the inter-processor mailbox that allows
+interrupt-based communication between the x86 and ARC cores contained in the
+Curie module (in such a transaction, the message sender is referred to as the
+"source" processor, and the recipient as the destination processor). Note that
+using this library to send a message to the mailbox, when there is no
+application running at the destination to receive it, will cause the source
+processor busy-wait indefinitely.
+
+Message format:
+
+The CurieMailbox library uses the CurieMailboxMsg class to describe a message
+for the mailbox. In total, a mailbox message contains 17 bytes of data that you
+can fill. Here's how you might populate a CurieMailboxMsg;
+
+    #include "CurieMailbox.h"
+    CurieMailboxMsg msg;
+
+    /* ID can be any 31-bit value */
+    msg.id = 0x7FFFFF;
+
+    /* Data payload is an array of 4 32-bit values */
+    msg.data[0] = 0xDEADBEEF;
+    msg.data[1] = 0xCAFEBABE;
+    msg.data[2] = 0xFFFFFFFF;
+    msg.data[3] = 0x00000000;
+
+    /* And the channel on which the message will be sent */
+    msg.channel = 6;
+
+API reference:
+
+
+void CurieMailbox::begin (bool master)
+
+  Enable interrupts for the mailbox, and optionally initialise the
+  mailbox hardware.
+
+Params:
+
+  bool master: flag indicating whether mailbox hardware should be initialised.
+  The first processor to access the mailbox should do this; if in doubt, set
+  to false (default is false, no initialisation).
+
+
+
+void CurieMailbox::begin (void)
+
+  Enable interrupts for the mailbox, and do not initialise the hardware.
+
+Params:
+
+  None.
+
+
+
+void CurieMailbox::enableReceive (unsigned int channel)
+
+  Unmask interrupts for mailbox channel 'channel', allowing it to receive
+  messages (channels can always send, only reception has to be enabled).
+
+Params:
+
+  int channel:  integer value (0-7) representing the channel to be enabled.
+  If the passed value does not represent a valid channel, then the highest
+  channel will be used instead.
+
+
+
+void CurieMailbox::disableReceive (unsigned int channel)
+
+  Mask interrupts for mailbox channel 'channel', so that messages can no longer
+  be received (but they can still be sent).
+
+Params:
+
+  int channel:  integer value (0-7) representing the channel to be enabled.
+  If the passed value does not represent a valid channel, then the highest
+  channel will be used instead.
+
+
+int CurieMailbox::available (void)
+
+  Returns the number of received mailbox messages available for reading.
+
+Params:
+
+  None
+
+
+
+void CurieMailbox::put (CurieMailboxMsg msg)
+
+  Writes the message 'msg' to the mailbox.
+
+Params:
+
+  CurieMailboxMsg msg: the message to send
+
+
+
+CurieMailboxMsg CurieMailbox::get (void)
+
+  Gets the most recently received unread message from the mailbox.
+
+Params:
+
+  None.

libraries/CurieMailbox/examples/SharedCounter/Makefile

@@ -0,0 +1,17 @@
+ifeq ("$(strip $(CODK_DIR))", "")
+  $(error Please set the CODK_DIR variable.)
+endif
+
+ARDUINOSW_DIR ?= $(CODK_DIR)/arc
+
+current_dir = $(shell pwd)
+
+VERBOSE  = true
+
+LIBDIRS  = $(ARDUINOSW_DIR)/corelibs/libraries/CurieMailbox/src
+
+include $(ARDUINOSW_DIR)/Makefile.inc
+
+all: compile
+
+.DEFAULT_GOAL := all

libraries/CurieMailbox/examples/SharedCounter/SharedCounter.ino

@@ -0,0 +1,80 @@
+/*
+ * CurieMailbox: Shared Counter example
+ *
+ * Requires sample Zephyr application CurieMailbox_SharedCounter running on x86
+ * core (get it from https://github.com/01org/CODK-M-X86-Samples)
+ *
+ * This example demonstrates sharing a single integer value between the x86
+ * and ARC core. This sketch (ARC core) starts by sending a value of 0 using
+ * CurieMailbox.put(). This is received by the application running on the x86
+ * core, which increments the value by 1 and sends it back via the mailbox.
+ *
+ * This sketch will read the reply, and again increment it by one and send
+ * it back to the x86 core through the mailbox. In this way the count value
+ * will increase indefinitely, with each core performing alternate increments
+ * and using the mailbox to pass the value in between.
+ *
+ * Copyright (c) 2016 Intel Corporation.  All rights reserved.
+ * See the bottom of this file for the license terms.
+ */
+
+#include "CurieMailbox.h"
+
+uint32_t count = 0;
+
+int sendChannel = 0;     /* We'll send mailbox messages on this channel */
+int receiveChannel = 1;  /* And receive them on this channel */
+
+void setup (void) {
+    Serial.begin(9600);
+
+    /* Enable the mailbox */
+    CurieMailbox.begin();
+
+    /* Enable channel for receiving messages */
+    CurieMailbox.enableReceive(receiveChannel);
+}
+
+void loop (void) {
+    CurieMailboxMsg outMsg; /* This will store the message we are sending */
+    CurieMailboxMsg inMsg;  /* This will store the received message */
+
+    delay(1000);
+
+    outMsg.id = 0;                /* ID can be whatever you like */
+    outMsg.data[0] = count;       /* Data is an array of 4 uint32_t types */
+    outMsg.channel = sendChannel; /* Sending this message to sendChannel */
+
+    CurieMailbox.put(outMsg);     /* Send the message */
+
+    /* Wait for the response */
+    while (CurieMailbox.available() == 0);
+
+    /* Read the response */
+    inMsg = CurieMailbox.get();
+
+    Serial.print("Sent '" + String(outMsg.data[0]) + "' on channel ");
+    Serial.print(String(outMsg.channel) + ", got reply '" + String(inMsg.data[0]));
+    Serial.println("' on channel " + String(inMsg.channel));
+
+    /* Update our count value with the value received from mailbox */
+    count = inMsg.data[0] + 1;
+}
+
+/*
+ * Copyright (c) 2016 Intel Corporation.  All rights reserved.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ */