Minor bugfixes

neural_modelling/src/common/neuron-typedefs.h

@@ -33,16 +33,13 @@
 #define UNUSED __attribute__((__unused__))
 #endif
 
-// Determine the type of a spike
-#ifndef __SPIKE_T__
-
-//! The type of a SpiNNaker multicast message key word
+//! The type of a SpiNNaker multicast message key word.
 typedef uint32_t key_t;
-//! The type of a SpiNNaker multicast message payload word
+
+//! The type of a SpiNNaker multicast message payload word.
 typedef uint32_t payload_t;
 
 #ifdef SPIKES_WITH_PAYLOADS
-
 //! The type of a spike
 typedef uint64_t spike_t;
 
@@ -53,55 +50,46 @@ union _spike_t {
         key_t key;
     };
 };
+#else  /*SPIKES_WITHOUT_PAYLOADS*/
+//! The type of a spike
+typedef uint32_t spike_t;
+#endif /*SPIKES_WITH_PAYLOADS*/
 
-//! \brief helper method to retrieve the key from a spike
+//! \brief Retrieve the key from a spike.
 //! \param[in] s: the spike to get the key from
-//! \return key_t: the key from the spike
+//! \return the key from the spike
 static inline key_t spike_key(spike_t s) {
+#ifdef SPIKES_WITH_PAYLOADS
     union _spike_t spike;
     spike.pair = s;
     return spike.key;
+#else  /*SPIKES_WITHOUT_PAYLOADS*/
+    return s;
+#endif /*SPIKES_WITH_PAYLOADS*/
 }
 
-//! \brief helper method to retrieve the pay-load from a spike
-//! \param[in] s: the spike to get the pay-load from
-//! \return payload_t: the pay-load from the spike (only used if the model
-//!     is compiled with SPIKES_WITH_PAYLOADS)
+//! \brief Retrieve the payload from a spike.
+//! \param[in] s: the spike to get the payload from
+//! \return the payload from the spike; always zero when `SPIKES_WITH_PAYLOADS`
+//!     is not defined.
 static inline payload_t spike_payload(spike_t s) {
+#ifdef SPIKES_WITH_PAYLOADS
     union _spike_t spike;
     spike.pair = s;
     return spike.payload;
-}
-
 #else  /*SPIKES_WITHOUT_PAYLOADS*/
-
-//! The type of a spike
-typedef uint32_t spike_t;
-
-//! \brief helper method to retrieve the key from a spike
-//! \param[in] s: the spike to get the key from
-//! \return key_t: the key from the spike
-static inline key_t spike_key(spike_t s) {
-    return s;
-}
-
-//! \brief helper method to retrieve the pay-load from a spike
-//! \param[in] s: the spike to get the pay-load from
-//! \return payload_t: the pay-load from the spike (default-ly set to zero if
-//!                    the model is not compiled with SPIKES_WITH_PAYLOADS)
-static inline payload_t spike_payload(UNUSED spike_t s) {
+    use(s);
     return 0;
-}
 #endif /*SPIKES_WITH_PAYLOADS*/
-#endif /*__SPIKE_T__*/
+}
 
-//! The type of a synaptic row
+//! The type of a synaptic row.
 typedef address_t synaptic_row_t;
 
-//! The type of an input
+//! The type of an input.
 typedef REAL input_t;
 
-//! The type of a state variable
+//! The type of a state variable.
 typedef REAL state_t;
 
 #endif /* __NEURON_TYPEDEFS_H__ */

neural_modelling/src/delay_extension/delay_extension.c

@@ -32,11 +32,12 @@
 //! the size of the circular queue for packets.
 #define IN_BUFFER_SIZE 256
 
-//! values for the priority for each callback
+//! Tthe priority for each callback
 enum delay_extension_callback_priorities {
     MC_PACKET = -1, //!< multicast packet reception uses FIQ
-    SDP = 0,        //!< SDP handling is highest ordinary priority
-    USER = 1,       //!< User interrupt is next (clearing packet received queue)
+    SDP = 0,        //!< SDP handling is direct interrupt
+    USER = 1,       //!< User interrupt is highest queued priority (used for
+                    //!< clearing the packet received queue)
     DMA = 2,        //!< DMA complete handling is next
     TIMER = 3,      //!< Regular timer tick handling is lowest priority
 };
@@ -124,9 +125,7 @@ static uint32_t timer_period = 0;
 //---------------------------------------
 // Because we don't want to include string.h or strings.h for memset
 //! \brief Sets an array of counters to zero
-//!
-//! This is basically just bzero()
-//!
+//! \details This is basically just `bzero()`
 //! \param[out] counters: The array to zero
 //! \param[in] num_items: The size of the array
 static inline void zero_spike_counters(
@@ -303,10 +302,9 @@ static bool initialize(void) {
 
 // Callbacks
 //! \brief Handles incoming spikes (FIQ)
-//!
-//! Adds the spikes to the circular buffer handling spikes for later handling by
-//! ::spike_process()
-//!
+//! \details
+//!     Adds the spikes to the circular buffer handling spikes for later
+//!     handling by ::spike_process()
 //! \param[in] key: the key of the multicast message
 //! \param payload: ignored
 static void incoming_spike_callback(uint key, UNUSED uint payload) {
@@ -325,8 +323,9 @@ static inline index_t key_n(key_t k) {
 }
 
 //! \brief Processes spikes queued by ::incoming_spike_callback()
-//!
-//! Note that this has to be fairly fast; it is processing with interrupts off.
+//! \details
+//!     Note that this has to be fairly fast; it is processing with interrupts
+//!     off.
 static inline void spike_process(void) {
     // turn off interrupts as this function is critical for
     // keeping time in sync.

neural_modelling/src/neuron/c_main.c

@@ -155,7 +155,7 @@ static void c_main_store_provenance_data(address_t provenance_region) {
     log_debug("finished other provenance data");
 }
 
-//! \brief Initialises the model by reading in the regions and checking
+//! \brief Initialise the model by reading in the regions and checking
 //!        recording data.
 //! \return True if it successfully initialised, false otherwise
 static bool initialise(void) {
@@ -258,7 +258,7 @@ static bool initialise(void) {
     return true;
 }
 
-//! \brief the function to call when resuming a simulation
+//! \brief Callback called when resuming a simulation
 void resume_callback(void) {
     data_specification_metadata_t *ds_regions =
             data_specification_get_data_address();

neural_modelling/src/neuron/decay.h

@@ -17,8 +17,9 @@
 
 /*! \file
  *
- *  \brief utility method for decaying a value by a given amount
- *
+ *  \brief Utility functions for decaying a value multiplicatively by a given
+ *      amount
+ *  \details
  *    The API includes:
  *
  *     - decay_s1615()
@@ -44,11 +45,11 @@
 //! the future if the type is redefined
 typedef UFRACT decay_t;
 
-//! \brief this method takes a s1615 and decays it by a given amount
-//! (denoted by the decay) (to compensate for the valve behaviour of a synapse
-//! in biology (spike goes in, synapse opens, then closes slowly)).
-//! \param[in] x the s1615 value to decayed
-//! \param[in] decay the amount to decay the value by
+//! \brief Decay a s1615 by a given amount (denoted by the decay) to
+//!     compensate for the valve behaviour of a synapse in biology (spike goes
+//!     in, synapse opens, then closes slowly).
+//! \param[in] x: the s1615 value to decayed
+//! \param[in] decay: the amount to decay the value by
 //! \return the new decayed s1615 value
 static inline s1615 decay_s1615(s1615 x, decay_t decay) {
     int64_t s = (int64_t) bitsk(x);
@@ -57,24 +58,24 @@ static inline s1615 decay_s1615(s1615 x, decay_t decay) {
     return kbits((int_k_t) ((s * u) >> 32));
 }
 
-//! \brief this method takes a s1616 and decays it by a given amount
-//! (denoted by the decay) (to compensate for the valve behaviour of a synapse
-//! in biology (spike goes in, synapse opens, then closes slowly)).
-//! \param[in] x the s1616 value to decayed
-//! \param[in] decay the amount to decay the value by
-//! \return the new decayed s1616 value
+//! \brief Decay a u1616 by a given amount (denoted by the decay) to compensate
+//!     for the valve behaviour of a synapse in biology (spike goes in, synapse
+//!     opens, then closes slowly).
+//! \param[in] x: the u1616 value to decayed
+//! \param[in] decay: the amount to decay the value by
+//! \return the new decayed u1616 value
 static inline u1616 decay_u1616(u1616 x, decay_t decay) {
     uint64_t s = (uint64_t) bitsuk(x);
     uint64_t u = (uint64_t) bitsulr(decay);
 
     return ukbits((uint_uk_t) ((s * u) >> 32));
 }
 
-//! \brief this method takes a s015 and decays it by a given amount
-//! (denoted by the decay) (to compensate for the valve behaviour of a synapse
-//! in biology (spike goes in, synapse opens, then closes slowly)).
-//! \param[in] x the s015 value to decayed
-//! \param[in] decay the amount to decay the value by
+//! \brief Decay a s015 by a given amount (denoted by the decay) (to compensate
+//!     for the valve behaviour of a synapse in biology (spike goes in, synapse
+//!     opens, then closes slowly).
+//! \param[in] x: the s015 value to decayed
+//! \param[in] decay: the amount to decay the value by
 //! \return the new decayed s015 value
 static inline s015 decay_s015(s015 x, decay_t decay) {
     int64_t s = (int64_t) bitsk(x);
@@ -83,12 +84,12 @@ static inline s015 decay_s015(s015 x, decay_t decay) {
     return rbits((int_r_t) ((s * u) >> 32));
 }
 
-//! \brief this method takes a s016 and decays it by a given amount
-//! (denoted by the decay) (to compensate for the valve behaviour of a synapse
-//! in biology (spike goes in, synapse opens, then closes slowly)).
-//! \param[in] x the s016 value to decayed
-//! \param[in] decay the amount to decay the value by
-//! \return the new decayed s016 value
+//! \brief Decay a u016 by a given amount (denoted by the decay) (to compensate
+//!     for the valve behaviour of a synapse in biology (spike goes in, synapse
+//!     opens, then closes slowly).
+//! \param[in] x: the u016 value to decayed
+//! \param[in] decay: the amount to decay the value by
+//! \return the new decayed u016 value
 static inline u016 decay_u016(u016 x, decay_t decay) {
     uint64_t s = (uint64_t) bitsuk(x);
     uint64_t u = (uint64_t) bitsulr(decay);
@@ -105,20 +106,22 @@ static inline u016 decay_u016(u016 x, decay_t decay) {
  * the abort statement and therefore kills scripts dead on SpiNNaker.
  * ---------------------------------
  */
-//! \brief This is a type-generic decay "function".
+//! \brief Decay a value by a given amount (denoted by the decay) (to
+//!     compensate for the valve behaviour of a synapse in biology (spike goes
+//!     in, synapse opens, then closes slowly).
 //! \param[in] x: the value to decayed
-//! \param[in] d: the amount to decay the value by
+//! \param[in] d: the amount to decay the value by (a decay_t)
 //! \return the new decayed value
 #define decay(x, d) ({ \
     __typeof__(x) tmp = (x); \
     if (__builtin_types_compatible_p(__typeof__(x), s1615)) {\
-        tmp = decay_s1615(x, d); \
+        tmp = decay_s1615(tmp, d); \
     } else if (__builtin_types_compatible_p(__typeof__(x), u1616)) {\
-        tmp = decay_u1616(x, d); \
+        tmp = decay_u1616(tmp, d); \
     } else if (__builtin_types_compatible_p(__typeof__(x), s015)) {\
-        tmp = decay_s015(x, d); \
+        tmp = decay_s015(tmp, d); \
     } else if (__builtin_types_compatible_p(__typeof__(x), u016)) {\
-        tmp = decay_u016(x, d); \
+        tmp = decay_u016(tmp, d); \
     } else {\
         abort(1); \
     }\

neural_modelling/src/neuron/implementations/neuron_impl.h

@@ -51,7 +51,7 @@ static void neuron_impl_load_neuron_parameters(
 static bool neuron_impl_do_timestep_update(
         index_t neuron_index, input_t external_bias);
 
-//! \brief Stores neuron parameters back into SDRAM
+//! \brief Store neuron parameters back into SDRAM
 //! \param[out] address: the address in SDRAM to start the store
 //! \param[in] next: Offset of next address in store
 //! \param[in] n_neurons: The number of neurons

neural_modelling/src/neuron/implementations/neuron_impl_external_devices.h

@@ -45,7 +45,7 @@ enum send_type {
 #include <debug.h>
 
 
-//! The definition of the threshold
+//! The definition of the threshold, and what to do when that happens
 typedef struct packet_firing_data_t {
     //! The key to send to update the value
     uint32_t key;
@@ -124,7 +124,9 @@ static uint global_timer_count;
 #endif // !SOMETIMES_UNUSED
 
 
-// Typesafe magic reinterpret cast
+//! \brief Typesafe magic reinterpret cast
+//! \param[in] value: The value to reinterpret
+//! \return The reinterpreted value
 static inline uint _int_bits(int value) {
     typedef union _int_bits_union {
         int int_value;
@@ -136,7 +138,7 @@ static inline uint _int_bits(int value) {
     return converter.uint_value;
 }
 
-//! \brief Converts the value into the right form for sending as a payload
+//! \brief Convert the value into the right form for sending as a payload
 //! \param[in] type: what type of payload are we really dealing with
 //! \param[in] value: the value, after scaling
 //! \return The word to go in the multicast packet payload
@@ -170,7 +172,7 @@ static bool neuron_impl_initialise(uint32_t n_neurons) {
     if (sizeof(global_neuron_params_t)) {
         global_parameters = spin1_malloc(sizeof(global_neuron_params_t));
         if (global_parameters == NULL) {
-            log_error("Unable to allocate global neuron parameters"
+            log_error("Unable to allocate global neuron parameters "
                     "- Out of DTCM");
             return false;
         }
@@ -322,9 +324,9 @@ static void neuron_impl_load_neuron_parameters(
 #endif // LOG_LEVEL >= LOG_DEBUG
 }
 
-//! \brief Determines if the device should fire
-//! \param[in] packet_firing: The parameters to use to determine if it
-//!                           should fire now
+//! \brief Determine if the device should fire
+//! \param[in] packet_firing:
+//!     The parameters to use to determine if it should fire now
 //! \return True if the neuron should fire
 static bool _test_will_fire(packet_firing_data_t *packet_firing) {
     if (packet_firing->time_until_next_send == 0) {
@@ -466,7 +468,7 @@ static bool neuron_impl_do_timestep_update(index_t neuron_index,
 }
 
 SOMETIMES_UNUSED // Marked unused as only used sometimes
-//! \brief Stores neuron parameters back into SDRAM
+//! \brief Store neuron parameters back into SDRAM
 //! \param[out] address: the address in SDRAM to start the store
 //! \param[in] next: Offset of next address in store
 //! \param[in] n_neurons: number of neurons

neural_modelling/src/neuron/implementations/neuron_impl_standard.h

@@ -353,7 +353,7 @@ static bool neuron_impl_do_timestep_update(index_t neuron_index,
 }
 
 SOMETIMES_UNUSED // Marked unused as only used sometimes
-//! \brief Stores neuron parameters back into SDRAM
+//! \brief Store neuron parameters back into SDRAM
 //! \param[out] address: the address in SDRAM to start the store
 //! \param[in] next: Offset of next address in store
 //! \param[in] n_neurons: number of neurons

neural_modelling/src/neuron/input_types/input_type.h

@@ -48,7 +48,7 @@ typedef struct input_type_t input_type_t;
 //! Declaration of the input type pointer
 typedef input_type_t *input_type_pointer_t;
 
-//! \brief Gets the actual input value. This allows any scaling to take place
+//! \brief Get the actual input value. This allows any scaling to take place
 //! \param[in,out] value: The array of the receptor-based values of the input
 //!     before scaling
 //! \param[in] input_type: The input type pointer to the parameters
@@ -60,7 +60,7 @@ static input_t *input_type_get_input_value(
         input_t *restrict value, const input_type_t *input_type,
         uint16_t num_receptors);
 
-//! \brief Converts an excitatory input into an excitatory current
+//! \brief Convert an excitatory input into an excitatory current
 //! \param[in,out] exc_input: Pointer to array of excitatory inputs from
 //!     different receptors this timestep. Note that this will already have
 //!     been scaled by input_type_get_input_value()
@@ -70,7 +70,7 @@ static void input_type_convert_excitatory_input_to_current(
         input_t *restrict exc_input, const input_type_t *input_type,
         state_t membrane_voltage);
 
-//! \brief Converts an inhibitory input into an inhibitory current
+//! \brief Convert an inhibitory input into an inhibitory current
 //! \param[in,out] inh_input: Pointer to array of inhibitory inputs from
 //!     different receptors this timestep. Note that this will already have
 //!     been scaled by input_type_get_input_value()