complete ble ota move

src/esp32/BluetoothSoftwareUpdate.cpp

@@ -0,0 +1,179 @@
+#include "BluetoothSoftwareUpdate.h"
+#include "BluetoothUtil.h"
+#include "CallbackCharacteristic.h"
+#include "RadioLibInterface.h"
+#include "configuration.h"
+#include "lock.h"
+#include <Arduino.h>
+#include <BLE2902.h>
+#include <CRC32.h>
+#include <Update.h>
+#include <esp_gatt_defs.h>
+
+using namespace meshtastic;
+
+CRC32 crc;
+uint32_t rebootAtMsec = 0; // If not zero we will reboot at this time (used to reboot shortly after the update completes)
+
+uint32_t updateExpectedSize, updateActualSize;
+
+Lock *updateLock;
+
+class TotalSizeCharacteristic : public CallbackCharacteristic
+{
+  public:
+    TotalSizeCharacteristic()
+        : CallbackCharacteristic("e74dd9c0-a301-4a6f-95a1-f0e1dbea8e1e",
+                                 BLECharacteristic::PROPERTY_WRITE | BLECharacteristic::PROPERTY_READ)
+    {
+    }
+
+    void onWrite(BLECharacteristic *c)
+    {
+        BLEKeepAliveCallbacks::onWrite(c);
+
+        LockGuard g(updateLock);
+        // Check if there is enough to OTA Update
+        uint32_t len = getValue32(c, 0);
+        updateExpectedSize = len;
+        updateActualSize = 0;
+        crc.reset();
+        bool canBegin = Update.begin(len);
+        DEBUG_MSG("Setting update size %u, result %d\n", len, canBegin);
+        if (!canBegin)
+            // Indicate failure by forcing the size to 0
+            c->setValue(0UL);
+        else {
+            // This totally breaks abstraction to up up into the app layer for this, but quick hack to make sure we only
+            // talk to one service during the sw update.
+            // DEBUG_MSG("FIXME, crufty shutdown of mesh bluetooth for sw update.");
+            // void stopMeshBluetoothService();
+            // stopMeshBluetoothService();
+
+            if (RadioLibInterface::instance)
+                RadioLibInterface::instance->sleep(); // FIXME, nasty hack - the RF95 ISR/SPI code on ESP32 can fail while we are
+                                                      // writing flash - shut the radio off during updates
+        }
+    }
+};
+
+#define MAX_BLOCKSIZE 512
+
+class DataCharacteristic : public CallbackCharacteristic
+{
+  public:
+    DataCharacteristic() : CallbackCharacteristic("e272ebac-d463-4b98-bc84-5cc1a39ee517", BLECharacteristic::PROPERTY_WRITE) {}
+
+    void onWrite(BLECharacteristic *c)
+    {
+        BLEKeepAliveCallbacks::onWrite(c);
+
+        LockGuard g(updateLock);
+        std::string value = c->getValue();
+        uint32_t len = value.length();
+        assert(len <= MAX_BLOCKSIZE);
+        static uint8_t
+            data[MAX_BLOCKSIZE]; // we temporarily copy here because I'm worried that a fast sender might be able overwrite srcbuf
+        memcpy(data, c->getData(), len);
+        // DEBUG_MSG("Writing %u\n", len);
+        crc.update(data, len);
+        Update.write(data, len);
+        updateActualSize += len;
+    }
+};
+
+static BLECharacteristic *resultC;
+
+class CRC32Characteristic : public CallbackCharacteristic
+{
+  public:
+    CRC32Characteristic() : CallbackCharacteristic("4826129c-c22a-43a3-b066-ce8f0d5bacc6", BLECharacteristic::PROPERTY_WRITE) {}
+
+    void onWrite(BLECharacteristic *c)
+    {
+        BLEKeepAliveCallbacks::onWrite(c);
+
+        LockGuard g(updateLock);
+        uint32_t expectedCRC = getValue32(c, 0);
+        uint32_t actualCRC = crc.finalize();
+        DEBUG_MSG("expected CRC %u\n", expectedCRC);
+
+        uint8_t result = 0xff;
+
+        if (updateActualSize != updateExpectedSize) {
+            DEBUG_MSG("Expected %u bytes, but received %u bytes!\n", updateExpectedSize, updateActualSize);
+            result = 0xe1;                   // FIXME, use real error codes
+        } else if (actualCRC != expectedCRC) // Check the CRC before asking the update to happen.
+        {
+            DEBUG_MSG("Invalid CRC! expected=%u, actual=%u\n", expectedCRC, actualCRC);
+            result = 0xe0; // FIXME, use real error codes
+        } else {
+            if (Update.end()) {
+                DEBUG_MSG("OTA done, rebooting in 5 seconds!\n");
+                rebootAtMsec = millis() + 5000;
+            } else {
+                DEBUG_MSG("Error Occurred. Error #: %d\n", Update.getError());
+
+                if (RadioLibInterface::instance)
+                    RadioLibInterface::instance->startReceive(); // Resume radio
+            }
+            result = Update.getError();
+        }
+        assert(resultC);
+        resultC->setValue(&result, 1);
+        resultC->notify();
+    }
+};
+
+void bluetoothRebootCheck()
+{
+    if (rebootAtMsec && millis() > rebootAtMsec)
+        ESP.restart();
+}
+
+/*
+See bluetooth-api.md
+
+ */
+BLEService *createUpdateService(BLEServer *server, std::string hwVendor, std::string swVersion, std::string hwVersion)
+{
+    if (!updateLock)
+        updateLock = new Lock();
+
+    // Create the BLE Service
+    BLEService *service = server->createService(BLEUUID("cb0b9a0b-a84c-4c0d-bdbb-442e3144ee30"), 25, 0);
+
+    assert(!resultC);
+    resultC = new BLECharacteristic("5e134862-7411-4424-ac4a-210937432c77",
+                                    BLECharacteristic::PROPERTY_READ | BLECharacteristic::PROPERTY_NOTIFY);
+
+    addWithDesc(service, new TotalSizeCharacteristic, "total image size");
+    addWithDesc(service, new DataCharacteristic, "data");
+    addWithDesc(service, new CRC32Characteristic, "crc32");
+    addWithDesc(service, resultC, "result code");
+
+    resultC->addDescriptor(addBLEDescriptor(new BLE2902())); // Needed so clients can request notification
+
+    BLECharacteristic *swC =
+        new BLECharacteristic(BLEUUID((uint16_t)ESP_GATT_UUID_SW_VERSION_STR), BLECharacteristic::PROPERTY_READ);
+    swC->setValue(swVersion);
+    service->addCharacteristic(addBLECharacteristic(swC));
+
+    BLECharacteristic *mfC = new BLECharacteristic(BLEUUID((uint16_t)ESP_GATT_UUID_MANU_NAME), BLECharacteristic::PROPERTY_READ);
+    mfC->setValue(hwVendor);
+    service->addCharacteristic(addBLECharacteristic(mfC));
+
+    BLECharacteristic *hwvC =
+        new BLECharacteristic(BLEUUID((uint16_t)ESP_GATT_UUID_HW_VERSION_STR), BLECharacteristic::PROPERTY_READ);
+    hwvC->setValue(hwVersion);
+    service->addCharacteristic(addBLECharacteristic(hwvC));
+
+    return service;
+}
+
+void destroyUpdateService()
+{
+    assert(resultC);
+
+    resultC = NULL;
+}

src/esp32/BluetoothSoftwareUpdate.h

@@ -0,0 +1,11 @@
+#pragma once
+
+#include <Arduino.h>
+#include <BLEDevice.h>
+#include <BLEServer.h>
+#include <BLEUtils.h>
+
+BLEService *createUpdateService(BLEServer *server, std::string hwVendor, std::string swVersion, std::string hwVersion);
+
+void destroyUpdateService();
+void bluetoothRebootCheck();

src/esp32/BluetoothUtil.cpp

@@ -0,0 +1,306 @@
+#include "BluetoothUtil.h"
+#include "BluetoothSoftwareUpdate.h"
+#include "configuration.h"
+#include <Arduino.h>
+#include <BLE2902.h>
+#include <Update.h>
+#include <esp_gatt_defs.h>
+
+SimpleAllocator btPool;
+
+/**
+ * Create standard device info service
+ **/
+BLEService *createDeviceInfomationService(BLEServer *server, std::string hwVendor, std::string swVersion,
+                                          std::string hwVersion = "")
+{
+    BLEService *deviceInfoService = server->createService(BLEUUID((uint16_t)ESP_GATT_UUID_DEVICE_INFO_SVC));
+
+    BLECharacteristic *swC =
+        new BLECharacteristic(BLEUUID((uint16_t)ESP_GATT_UUID_SW_VERSION_STR), BLECharacteristic::PROPERTY_READ);
+    BLECharacteristic *mfC = new BLECharacteristic(BLEUUID((uint16_t)ESP_GATT_UUID_MANU_NAME), BLECharacteristic::PROPERTY_READ);
+    // BLECharacteristic SerialNumberCharacteristic(BLEUUID((uint16_t) ESP_GATT_UUID_SERIAL_NUMBER_STR),
+    // BLECharacteristic::PROPERTY_READ);
+
+    /*
+           * Mandatory characteristic for device info service?
+
+          BLECharacteristic *m_pnpCharacteristic = m_deviceInfoService->createCharacteristic(ESP_GATT_UUID_PNP_ID,
+      BLECharacteristic::PROPERTY_READ);
+
+      uint8_t sig, uint16_t vid, uint16_t pid, uint16_t version;
+          uint8_t pnp[] = { sig, (uint8_t) (vid >> 8), (uint8_t) vid, (uint8_t) (pid >> 8), (uint8_t) pid, (uint8_t) (version >>
+      8), (uint8_t) version }; m_pnpCharacteristic->setValue(pnp, sizeof(pnp));
+      */
+    swC->setValue(swVersion);
+    deviceInfoService->addCharacteristic(addBLECharacteristic(swC));
+    mfC->setValue(hwVendor);
+    deviceInfoService->addCharacteristic(addBLECharacteristic(mfC));
+    if (!hwVersion.empty()) {
+        BLECharacteristic *hwvC =
+            new BLECharacteristic(BLEUUID((uint16_t)ESP_GATT_UUID_HW_VERSION_STR), BLECharacteristic::PROPERTY_READ);
+        hwvC->setValue(hwVersion);
+        deviceInfoService->addCharacteristic(addBLECharacteristic(hwvC));
+    }
+    // SerialNumberCharacteristic.setValue("FIXME");
+    // deviceInfoService->addCharacteristic(&SerialNumberCharacteristic);
+
+    // m_manufacturerCharacteristic = m_deviceInfoService->createCharacteristic((uint16_t) 0x2a29,
+    // BLECharacteristic::PROPERTY_READ); m_manufacturerCharacteristic->setValue(name);
+
+    /* add these later?
+      ESP_GATT_UUID_SYSTEM_ID
+      */
+
+    // caller must call service->start();
+    return deviceInfoService;
+}
+
+bool _BLEClientConnected = false;
+
+class MyServerCallbacks : public BLEServerCallbacks
+{
+    void onConnect(BLEServer *pServer) { _BLEClientConnected = true; };
+
+    void onDisconnect(BLEServer *pServer) { _BLEClientConnected = false; }
+};
+
+#define MAX_DESCRIPTORS 32
+#define MAX_CHARACTERISTICS 32
+
+static BLECharacteristic *chars[MAX_CHARACTERISTICS];
+static size_t numChars;
+static BLEDescriptor *descs[MAX_DESCRIPTORS];
+static size_t numDescs;
+
+/// Add a characteristic that we will delete when we restart
+BLECharacteristic *addBLECharacteristic(BLECharacteristic *c)
+{
+    assert(numChars < MAX_CHARACTERISTICS);
+    chars[numChars++] = c;
+    return c;
+}
+
+/// Add a characteristic that we will delete when we restart
+BLEDescriptor *addBLEDescriptor(BLEDescriptor *c)
+{
+    assert(numDescs < MAX_DESCRIPTORS);
+    descs[numDescs++] = c;
+
+    return c;
+}
+
+// Help routine to add a description to any BLECharacteristic and add it to the service
+// We default to require an encrypted BOND for all these these characterstics
+void addWithDesc(BLEService *service, BLECharacteristic *c, const char *description)
+{
+    c->setAccessPermissions(ESP_GATT_PERM_READ_ENCRYPTED | ESP_GATT_PERM_WRITE_ENCRYPTED);
+
+    BLEDescriptor *desc = new BLEDescriptor(BLEUUID((uint16_t)ESP_GATT_UUID_CHAR_DESCRIPTION), strlen(description) + 1);
+    assert(desc);
+    desc->setAccessPermissions(ESP_GATT_PERM_READ_ENCRYPTED | ESP_GATT_PERM_WRITE_ENCRYPTED);
+    desc->setValue(description);
+    c->addDescriptor(desc);
+    service->addCharacteristic(c);
+    addBLECharacteristic(c);
+    addBLEDescriptor(desc);
+}
+
+static BLECharacteristic *batteryLevelC;
+
+/**
+ * Create a battery level service
+ */
+BLEService *createBatteryService(BLEServer *server)
+{
+    // Create the BLE Service
+    BLEService *pBattery = server->createService(BLEUUID((uint16_t)0x180F));
+
+    batteryLevelC = new BLECharacteristic(BLEUUID((uint16_t)ESP_GATT_UUID_BATTERY_LEVEL),
+                                          BLECharacteristic::PROPERTY_READ | BLECharacteristic::PROPERTY_NOTIFY);
+
+    addWithDesc(pBattery, batteryLevelC, "Percentage 0 - 100");
+    batteryLevelC->addDescriptor(addBLEDescriptor(new BLE2902())); // Needed so clients can request notification
+
+    // I don't think we need to advertise this
+    // server->getAdvertising()->addServiceUUID(pBattery->getUUID());
+    pBattery->start();
+
+    return pBattery;
+}
+
+/**
+ * Update the battery level we are currently telling clients.
+ * level should be a pct between 0 and 100
+ */
+void updateBatteryLevel(uint8_t level)
+{
+    // Pretend to update battery levels - fixme do elsewhere
+    if (batteryLevelC) {
+        batteryLevelC->setValue(&level, 1);
+        batteryLevelC->notify();
+    }
+}
+
+void dumpCharacteristic(BLECharacteristic *c)
+{
+    std::string value = c->getValue();
+
+    if (value.length() > 0) {
+        DEBUG_MSG("New value: ");
+        for (int i = 0; i < value.length(); i++)
+            DEBUG_MSG("%c", value[i]);
+
+        DEBUG_MSG("\n");
+    }
+}
+
+/** converting endianness pull out a 32 bit value */
+uint32_t getValue32(BLECharacteristic *c, uint32_t defaultValue)
+{
+    std::string value = c->getValue();
+    uint32_t r = defaultValue;
+
+    if (value.length() == 4)
+        r = value[0] | (value[1] << 8UL) | (value[2] << 16UL) | (value[3] << 24UL);
+
+    return r;
+}
+
+class MySecurity : public BLESecurityCallbacks
+{
+  protected:
+    bool onConfirmPIN(uint32_t pin)
+    {
+        Serial.printf("onConfirmPIN %u\n", pin);
+        return false;
+    }
+
+    uint32_t onPassKeyRequest()
+    {
+        Serial.println("onPassKeyRequest");
+        return 123511; // not used
+    }
+
+    void onPassKeyNotify(uint32_t pass_key)
+    {
+        Serial.printf("onPassKeyNotify %06u\n", pass_key);
+        startCb(pass_key);
+    }
+
+    bool onSecurityRequest()
+    {
+        Serial.println("onSecurityRequest");
+        return true;
+    }
+
+    void onAuthenticationComplete(esp_ble_auth_cmpl_t cmpl)
+    {
+        if (cmpl.success) {
+            uint16_t length;
+            esp_ble_gap_get_whitelist_size(&length);
+            Serial.printf(" authenticated and connected to phone\n");
+        } else {
+            Serial.printf("phone authenticate failed %d\n", cmpl.fail_reason);
+        }
+
+        // Remove our custom PIN request screen.
+        stopCb();
+    }
+
+  public:
+    StartBluetoothPinScreenCallback startCb;
+    StopBluetoothPinScreenCallback stopCb;
+};
+
+BLEServer *pServer;
+
+BLEService *pDevInfo, *pUpdate;
+
+void deinitBLE()
+{
+    assert(pServer);
+
+    pServer->getAdvertising()->stop();
+
+    destroyUpdateService();
+
+    pUpdate->stop();
+    pDevInfo->stop();
+    pUpdate->stop(); // we delete them below
+
+    // First shutdown bluetooth
+    BLEDevice::deinit(false);
+
+    // do not delete this - it is dynamically allocated, but only once - statically in BLEDevice
+    // delete pServer->getAdvertising();
+
+    delete pUpdate;
+    delete pDevInfo;
+    delete pServer;
+
+    batteryLevelC = NULL; // Don't let anyone generate bogus notifies
+
+    for (int i = 0; i < numChars; i++)
+        delete chars[i];
+    numChars = 0;
+
+    for (int i = 0; i < numDescs; i++)
+        delete descs[i];
+    numDescs = 0;
+
+    btPool.reset();
+}
+
+BLEServer *initBLE(StartBluetoothPinScreenCallback startBtPinScreen, StopBluetoothPinScreenCallback stopBtPinScreen,
+                   std::string deviceName, std::string hwVendor, std::string swVersion, std::string hwVersion)
+{
+    BLEDevice::init(deviceName);
+    BLEDevice::setEncryptionLevel(ESP_BLE_SEC_ENCRYPT);
+
+    /*
+     * Required in authentication process to provide displaying and/or input passkey or yes/no butttons confirmation
+     */
+    static MySecurity mySecurity;
+    mySecurity.startCb = startBtPinScreen;
+    mySecurity.stopCb = stopBtPinScreen;
+    BLEDevice::setSecurityCallbacks(&mySecurity);
+
+    // Create the BLE Server
+    pServer = BLEDevice::createServer();
+    static MyServerCallbacks myCallbacks;
+    pServer->setCallbacks(&myCallbacks);
+
+    pDevInfo = createDeviceInfomationService(pServer, hwVendor, swVersion, hwVersion);
+
+    // We now let users create the battery service only if they really want (not all devices have a battery)
+    // BLEService *pBattery = createBatteryService(pServer);
+
+    pUpdate = createUpdateService(pServer, hwVendor, swVersion,
+                                  hwVersion); // We need to advertise this so our android ble scan operation can see it
+
+    // It seems only one service can be advertised - so for now don't advertise our updater
+    // pServer->getAdvertising()->addServiceUUID(pUpdate->getUUID());
+
+    // start all our services (do this after creating all of them)
+    pDevInfo->start();
+    pUpdate->start();
+
+    // FIXME turn on this restriction only after the device is paired with a phone
+    // advert->setScanFilter(false, true); // We let anyone scan for us (FIXME, perhaps only allow that until we are paired with a
+    // phone and configured) but only let whitelist phones connect
+
+    static BLESecurity security; // static to avoid allocs
+    BLESecurity *pSecurity = &security;
+    pSecurity->setCapability(ESP_IO_CAP_OUT);
+    pSecurity->setAuthenticationMode(ESP_LE_AUTH_REQ_SC_BOND);
+    pSecurity->setInitEncryptionKey(ESP_BLE_ENC_KEY_MASK | ESP_BLE_ID_KEY_MASK);
+
+    return pServer;
+}
+
+// Called from loop
+void loopBLE()
+{
+    bluetoothRebootCheck();
+}

src/esp32/BluetoothUtil.h

@@ -0,0 +1,39 @@
+#pragma once
+
+#include <functional>
+
+#include <Arduino.h>
+#include <BLEDevice.h>
+#include <BLEServer.h>
+#include <BLEUtils.h>
+#include "SimpleAllocator.h"
+
+// Now handled by BluetoothUtil.cpp
+// BLEService *createDeviceInfomationService(BLEServer* server, uint8_t sig, uint16_t vid, uint16_t pid, uint16_t version);
+
+// Help routine to add a description to any BLECharacteristic and add it to the service
+void addWithDesc(BLEService *service, BLECharacteristic *c, const char *description);
+
+void dumpCharacteristic(BLECharacteristic *c);
+
+/** converting endianness pull out a 32 bit value */
+uint32_t getValue32(BLECharacteristic *c, uint32_t defaultValue);
+
+// TODO(girts): create a class for the bluetooth utils helpers?
+using StartBluetoothPinScreenCallback = std::function<void(uint32_t pass_key)>;
+using StopBluetoothPinScreenCallback = std::function<void(void)>;
+
+void loopBLE();
+BLEServer *initBLE(
+    StartBluetoothPinScreenCallback startBtPinScreen, StopBluetoothPinScreenCallback stopBtPinScreen,
+    std::string devName, std::string hwVendor, std::string swVersion, std::string hwVersion = "");
+void deinitBLE();
+
+/// Add a characteristic that we will delete when we restart
+BLECharacteristic *addBLECharacteristic(BLECharacteristic *c);
+
+/// Add a characteristic that we will delete when we restart
+BLEDescriptor *addBLEDescriptor(BLEDescriptor *c);
+
+/// Any bluetooth objects you allocate _must_ come from this pool if you want to be able to call deinitBLE()
+extern SimpleAllocator btPool;

src/esp32/CallbackCharacteristic.h

@@ -0,0 +1,33 @@
+#pragma once
+#include "PowerFSM.h" // FIXME - someday I want to make this OTA thing a separate lb at at that point it can't touch this
+#include "BLECharacteristic.h"
+
+/**
+ * This mixin just lets the power management state machine know the phone is still talking to us
+ */
+class BLEKeepAliveCallbacks : public BLECharacteristicCallbacks
+{
+public:
+    void onRead(BLECharacteristic *c)
+    {
+        powerFSM.trigger(EVENT_CONTACT_FROM_PHONE);
+    }
+
+    void onWrite(BLECharacteristic *c)
+    {
+        powerFSM.trigger(EVENT_CONTACT_FROM_PHONE);
+    }
+};
+
+/**
+ * A characterstic with a set of overridable callbacks
+ */
+class CallbackCharacteristic : public BLECharacteristic, public BLEKeepAliveCallbacks
+{
+public:
+    CallbackCharacteristic(const char *uuid, uint32_t btprops)
+        : BLECharacteristic(uuid, btprops)
+    {
+        setCallbacks(this);
+    }
+};

src/esp32/SimpleAllocator.cpp

@@ -0,0 +1,60 @@
+#include "SimpleAllocator.h"
+#include "assert.h"
+
+
+SimpleAllocator::SimpleAllocator() { reset(); }
+
+void *SimpleAllocator::alloc(size_t size)
+{
+    assert(nextFree + size <= sizeof(bytes));
+    void *res = &bytes[nextFree];
+    nextFree += size;
+    Serial.printf("Total simple allocs %u\n", nextFree);
+
+    return res;
+}
+
+void SimpleAllocator::reset() { nextFree = 0; }
+
+void *operator new(size_t size, SimpleAllocator &p)
+{
+    return p.alloc(size);
+}
+
+#if 0 
+// This was a dumb idea, turn off for now
+
+SimpleAllocator *activeAllocator;
+
+AllocatorScope::AllocatorScope(SimpleAllocator &a)
+{
+    assert(!activeAllocator);
+    activeAllocator = &a;
+}
+
+AllocatorScope::~AllocatorScope()
+{
+    assert(activeAllocator);
+    activeAllocator = NULL;
+}
+
+/// Global new/delete, uses a simple allocator if it is in scope
+
+void *operator new(size_t sz) throw(std::bad_alloc)
+{
+    void *mem = activeAllocator ? activeAllocator->alloc(sz) : malloc(sz);
+    if (mem)
+        return mem;
+    else
+        throw std::bad_alloc();
+}
+
+void operator delete(void *ptr) throw()
+{
+    if (activeAllocator)
+        Serial.println("Warning: leaking an active allocator object"); // We don't properly handle this yet
+    else
+        free(ptr);
+}
+
+#endif

src/esp32/SimpleAllocator.h

@@ -0,0 +1,42 @@
+#pragma once
+#include <Arduino.h>
+
+#define POOL_SIZE 16384
+
+/**
+ * An allocator (and placement new operator) that allocates storage from a fixed sized buffer.
+ * It will panic if that buffer fills up.
+ * If you are _sure_ no outstanding references to blocks in this buffer still exist, you can call
+ * reset() to start from scratch.
+ * 
+ * Currently the only usecase for this class is the ESP32 bluetooth stack, where once we've called deinit(false)
+ * we are sure all those bluetooth objects no longer exist, and we'll need to recreate them when we restart bluetooth
+ */
+class SimpleAllocator
+{
+    uint8_t bytes[POOL_SIZE];
+
+    uint32_t nextFree;
+
+public:
+    SimpleAllocator();
+
+    void *alloc(size_t size);
+
+    /** If you are _sure_ no outstanding references to blocks in this buffer still exist, you can call
+ * reset() to start from scratch.
+ * */
+    void reset();
+};
+
+void *operator new(size_t size, SimpleAllocator &p);
+
+/**
+ * Temporarily makes the specified Allocator be used for _all_ allocations.  Useful when calling library routines
+ * that don't know about pools
+ */
+class AllocatorScope {
+public:
+    AllocatorScope(SimpleAllocator &a);
+    ~AllocatorScope();
+};