delay_extension.c

Go to the documentation of this file.

/*
 * Copyright (c) 2014 The University of Manchester
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
 
#include "delay_extension.h"
 
#include <common/neuron-typedefs.h>
#include <common/in_spikes.h>
#include <bit_field.h>
#include <data_specification.h>
#include <debug.h>
#include <simulation.h>
#include <spin1_api.h>
#include <common/send_mc.h>
 
#define IN_BUFFER_SIZE 256
 
#define COUNTER_SATURATION_VALUE 255
 
enum delay_extension_callback_priorities {
    MC_PACKET = -1, 
    TIMER = 0,      
    USER = 0,       
    SDP = 1,        
    BACKGROUND = 1, 
    DMA = 2         
};
 
struct delay_extension_provenance {
    uint32_t n_packets_received;
    uint32_t n_packets_processed;
    uint32_t n_packets_added;
    uint32_t n_packets_sent;
    uint32_t n_buffer_overflows;
    uint32_t n_delays;
    uint32_t n_packets_lost_due_to_count_saturation;
    uint32_t n_packets_dropped_due_to_invalid_neuron_value;
    uint32_t n_packets_dropped_due_to_invalid_key;
    uint32_t count_input_buffer_packets_late;
    uint32_t max_backgrounds_queued;
    uint32_t n_background_queue_overloads;
};
 
// Globals
static bool has_key;
static uint32_t key = 0;
static uint32_t incoming_key = 0;
static uint32_t incoming_mask = 0;
static uint32_t incoming_neuron_mask = 0;
 
static uint32_t num_neurons = 0;
 
static uint32_t max_keys = 0;
 
static bool clear_input_buffers_of_late_packets;
 
static uint32_t time = UINT32_MAX;
static uint32_t simulation_ticks = 0;
static uint32_t infinite_run;
 
static uint8_t **spike_counters = NULL;
static uint32_t num_delay_stages = 0;
static uint32_t n_delay_in_a_stage = 0;
static uint32_t num_delay_slots = 0;
static uint32_t num_delay_slots_mask = 0;
static uint32_t neuron_bit_field_words = 0;
 
static uint32_t n_in_spikes = 0;
static uint32_t n_processed_spikes = 0;
static uint32_t n_spikes_sent = 0;
static uint32_t n_spikes_added = 0;
 
static uint32_t n_delays = 0;
 
static uint32_t saturation_count = 0;
 
static uint32_t n_packets_dropped_due_to_invalid_neuron_value = 0;
 
static uint32_t n_packets_dropped_due_to_invalid_key = 0;
 
static uint32_t count_input_buffer_packets_late;
 
static uint32_t timer_period = 0;
 
static bool spike_processing = false;
 
static uint32_t n_backgrounds_queued = 0;
 
static uint32_t n_background_overloads = 0;
 
static uint32_t max_backgrounds_queued = 0;
 
static uint32_t n_colour_bits = 0;
 
static uint32_t colour_mask = 0;
 
static uint32_t colour = 0;
 
//---------------------------------------
// Because we don't want to include string.h or strings.h for memset
static inline void zero_spike_counters(
        uint8_t *counters, uint32_t num_items) {
    for (uint32_t i = 0 ; i < num_items ; i++) {
        counters[i] = 0;
    }
}
 
static inline uint32_t round_to_next_pot(uint32_t v) {
    v--;
    v |= v >> 1;
    v |= v >> 2;
    v |= v >> 4;
    v |= v >> 8;
    v |= v >> 16;
    v++;
    return v;
}
 
static bool read_parameters(struct delay_parameters *params) {
    log_debug("read_parameters: starting");
 
    has_key = params->has_key;
    key = params->key;
    incoming_key = params->incoming_key;
    incoming_mask = params->incoming_mask;
    incoming_neuron_mask = ~incoming_mask;
    log_debug("\t key = 0x%08x, incoming key = 0x%08x, incoming mask = 0x%08x,"
            "incoming key mask = 0x%08x",
            key, incoming_key, incoming_mask, incoming_neuron_mask);
 
    num_neurons = params->n_atoms;
    neuron_bit_field_words = get_bit_field_size(num_neurons);
 
    num_delay_stages = params->n_delay_stages;
    n_delay_in_a_stage = params->n_delay_in_a_stage;
    max_keys = num_neurons * num_delay_stages;
 
    clear_input_buffers_of_late_packets = params->clear_packets;
 
    num_delay_slots = num_delay_stages * n_delay_in_a_stage;
    // We need an extra slot here (to make one clearable after the maximum delay
    // time), and a power of 2 (to make it easier to loop)
    uint32_t num_delay_slots_pot = round_to_next_pot(num_delay_slots + 1);
    num_delay_slots_mask = num_delay_slots_pot - 1;
 
    log_info("\t parrot neurons = %u, neuron bit field words = %u,"
            " num delay stages = %u, num delay slots = %u (pot = %u),"
            " num delay slots mask = %08x, n delay in a stage = %u",
            num_neurons, neuron_bit_field_words,
            num_delay_stages, num_delay_slots, num_delay_slots_pot,
            num_delay_slots_mask, n_delay_in_a_stage);
 
    // Allocate array of counters for each delay slot
    spike_counters = spin1_malloc(num_delay_slots_pot * sizeof(uint8_t*));
    if (spike_counters == NULL) {
        log_error("failed to allocate memory for array of size %u bytes",
                num_delay_slots_pot * sizeof(uint8_t*));
        return false;
    }
 
    for (uint32_t s = 0; s < num_delay_slots_pot; s++) {
        // Allocate an array of counters for each neuron and zero
        spike_counters[s] = spin1_malloc(num_neurons * sizeof(uint8_t));
        if (spike_counters[s] == NULL) {
            log_error("failed to allocate memory for bitfield of size %u bytes",
                    num_neurons * sizeof(uint8_t));
            return false;
        }
        zero_spike_counters(spike_counters[s], num_neurons);
    }
 
    n_colour_bits = params->n_colour_bits;
    colour_mask = (1 << n_colour_bits) - 1;
 
    log_debug("read_parameters: completed successfully");
    return true;
}
 
static void store_provenance_data(address_t provenance_region) {
    log_debug("writing other provenance data");
    struct delay_extension_provenance *prov = (void *) provenance_region;
 
    // store the data into the provenance data region
    prov->n_packets_received = n_in_spikes;
    prov->n_packets_processed = n_processed_spikes;
    prov->n_packets_added = n_spikes_added;
    prov->n_packets_sent = n_spikes_sent;
    prov->n_buffer_overflows = in_spikes_get_n_buffer_overflows();
    prov->n_delays = n_delays;
    prov->n_packets_lost_due_to_count_saturation = saturation_count;
    prov->n_packets_dropped_due_to_invalid_neuron_value =
        n_packets_dropped_due_to_invalid_neuron_value;
    prov->n_packets_dropped_due_to_invalid_key =
        n_packets_dropped_due_to_invalid_key;
    prov->count_input_buffer_packets_late = count_input_buffer_packets_late;
    prov->n_background_queue_overloads = n_background_overloads;
    prov->max_backgrounds_queued = max_backgrounds_queued;
    log_debug("finished other provenance data");
}
 
static bool initialize(void) {
    log_info("initialise: started");
 
    // Get the address this core's DTCM data starts at from SRAM
    data_specification_metadata_t *ds_regions =
            data_specification_get_data_address();
 
    // Read the header
    if (!data_specification_read_header(ds_regions)) {
        return false;
    }
 
    // Get the timing details and set up the simulation interface
    if (!simulation_initialise(
            data_specification_get_region(SYSTEM, ds_regions),
            APPLICATION_NAME_HASH, &timer_period, &simulation_ticks,
            &infinite_run, &time, SDP, DMA)) {
        return false;
    }
 
    // set provenance function
    simulation_set_provenance_function(
            store_provenance_data,
            data_specification_get_region(PROVENANCE_REGION, ds_regions));
 
    // Get the parameters
    if (!read_parameters(data_specification_get_region(
            DELAY_PARAMS, ds_regions))) {
        return false;
    }
 
    log_info("initialise: completed successfully");
 
    return true;
}
 
// Callbacks
static void incoming_spike_callback(uint key, uint payload) {
 
    if (payload == 0) {
        payload = 1;
    }
    log_debug("Received spike %x", key);
 
    for (uint32_t i = payload; i > 0; i--) {
        n_in_spikes++;
        in_spikes_add_spike(key);
    }
 
    if (!spike_processing) {
        if (spin1_trigger_user_event(0, 0)) {
            spike_processing = true;
        }
    }
}
 
static inline index_t key_n(key_t k) {
    return k & incoming_neuron_mask;
}
 
static inline void spike_process(void) {
 
    // While there are any incoming spikes
    spike_t s;
    uint32_t state = spin1_int_disable();
    while (in_spikes_get_next_spike(&s)) {
        spin1_mode_restore(state);
        n_processed_spikes++;
 
        if ((s & incoming_mask) == incoming_key) {
            // Mask out neuron ID
            uint32_t spike_id = key_n(s);
            uint32_t spike_colour = spike_id & colour_mask;
            uint32_t neuron_id = spike_id >> n_colour_bits;
            if (neuron_id < num_neurons) {
 
                // Account for delayed spikes
                int32_t colour_diff = colour - spike_colour;
                uint32_t colour_delay = colour_diff & colour_mask;
 
                // Get current time slot of incoming spike counters
                uint32_t time_slot = (time + colour_delay) & num_delay_slots_mask;
                uint8_t *time_slot_spike_counters = spike_counters[time_slot];
 
                // Increment counter
                if (time_slot_spike_counters[neuron_id] ==
                        COUNTER_SATURATION_VALUE) {
                    saturation_count += 1;
                } else {
                    time_slot_spike_counters[neuron_id]++;
                }
                log_debug("Incrementing counter %u = %u\n",
                        neuron_id,
                        time_slot_spike_counters[neuron_id]);
                n_spikes_added++;
            } else {
                n_packets_dropped_due_to_invalid_neuron_value += 1;
                log_debug("Invalid neuron ID %u", neuron_id);
            }
        } else {
            n_packets_dropped_due_to_invalid_key += 1;
            log_debug("Invalid spike key 0x%08x", s);
        }
        state = spin1_int_disable();
    }
 
    spike_processing = false;
    spin1_mode_restore(state);
}
 
static void user_callback(UNUSED uint unused0, UNUSED uint unused1) {
    spike_process();
}
 
static void background_callback(uint local_time, UNUSED uint timer_count) {
    // Loop through delay stages
    for (uint32_t d = 0; d < num_delay_stages; d++) {
        uint32_t delay_stage_delay = (d + 1) * n_delay_in_a_stage;
        if (local_time >= delay_stage_delay) {
            uint32_t delay_stage_time_slot =
                    (local_time - delay_stage_delay) & num_delay_slots_mask;
            uint8_t *delay_stage_spike_counters =
                    spike_counters[delay_stage_time_slot];
 
            log_debug("%u: Checking time slot %u for delay stage %u (delay %u)",
                    local_time, delay_stage_time_slot, d, delay_stage_delay);
 
            // Loop through neurons
            for (uint32_t n = 0; n < num_neurons; n++) {
 
                // If no spikes to send, skip
                if (delay_stage_spike_counters[n] == 0) {
                    continue;
                }
 
                // Calculate key all spikes coming from this neuron will be
                // sent with
                uint32_t neuron_index = ((d * num_neurons) + n);
                uint32_t spike_key = (key + (neuron_index << n_colour_bits)) | colour;
 
                log_debug("Neuron %u sending %u spikes after delay"
                        "stage %u with key %x",
                        n, delay_stage_spike_counters[n], d,
                        spike_key);
 
                // fire n spikes as payload, 1 as none payload.
                if (has_key) {
                    if (delay_stage_spike_counters[n] > 1) {
                        log_debug(
                            "%d: sending packet with key 0x%08x and payload %d",
                            time, spike_key, delay_stage_spike_counters[n]);
 
                        send_spike_mc_payload(spike_key, delay_stage_spike_counters[n]);
 
                        // update counter
                        n_spikes_sent += delay_stage_spike_counters[n];
                    } else if (delay_stage_spike_counters[n] == 1) {
                        log_debug("%d: sending spike with key 0x%08x", time, spike_key);
 
                        send_spike_mc(spike_key);
 
                        // update counter
                        n_spikes_sent++;
                    }
                }
            }
        }
    }
    n_backgrounds_queued--;
}
 
static void timer_callback(uint timer_count, UNUSED uint unused1) {
    uint32_t state = spin1_int_disable();
    uint32_t n_spikes = in_spikes_size();
    if (clear_input_buffers_of_late_packets) {
        in_spikes_clear();
    }
    // Record the count whether clearing or not for provenance
    count_input_buffer_packets_late += n_spikes;
    time++;
 
    // Clear counters
    if (time > num_delay_slots) {
        uint32_t clearable_slot = ((time - 1) - num_delay_slots) & num_delay_slots_mask;
        log_debug("%d: Clearing time slot %d", time, clearable_slot);
        zero_spike_counters(spike_counters[clearable_slot], num_neurons);
    }
 
    log_debug("Timer tick %u", time);
 
    // If a fixed number of simulation ticks are specified and these have passed
    if (simulation_is_finished()) {
        // handle the pause and resume functionality
        simulation_handle_pause_resume(NULL);
 
        log_debug("Delay extension finished at time %u, %u received spikes, "
                "%u processed spikes, %u sent spikes, %u added spikes",
                time, n_in_spikes, n_processed_spikes, n_spikes_sent,
                n_spikes_added);
 
        log_debug("Delayed %u times", n_delays);
 
        // Subtract 1 from the time so this tick gets done again on the next
        // run
        time--;
 
        simulation_ready_to_read();
        spin1_mode_restore(state);
        return;
    }
 
    // Set the colour for the time step
    colour = time & colour_mask;
 
    if (!spin1_schedule_callback(background_callback, time, timer_count, BACKGROUND)) {
        // We have failed to do this timer tick!
        n_background_overloads++;
    } else {
        n_backgrounds_queued++;
        if (n_backgrounds_queued > max_backgrounds_queued) {
            max_backgrounds_queued++;
        }
    }
    spin1_mode_restore(state);
}
 
void c_main(void) {
    log_info("max dtcm supply %d", sark_heap_max(sark.heap, 0));
    if (!initialize()) {
        log_error("Error in initialisation - exiting!");
        rt_error(RTE_SWERR);
    }
 
    // Start the time at "-1" so that the first tick will be 0
    time = UINT32_MAX;
 
    // Initialise the incoming spike buffer
    if (!in_spikes_initialize_spike_buffer(IN_BUFFER_SIZE)) {
        rt_error(RTE_SWERR);
    }
 
    // Set timer tick (in microseconds)
    log_debug("Timer period %u", timer_period);
    spin1_set_timer_tick(timer_period);
 
    // Register callbacks
    spin1_callback_on(MC_PACKET_RECEIVED, incoming_spike_callback, MC_PACKET);
    spin1_callback_on(MCPL_PACKET_RECEIVED, incoming_spike_callback, MC_PACKET);
    spin1_callback_on(TIMER_TICK, timer_callback, TIMER);
    spin1_callback_on(USER_EVENT, user_callback, USER);
 
    simulation_run();
}