Minor bugfixes

neural_modelling/Doxyfile

@@ -907,7 +907,7 @@ USE_MDFILE_AS_MAINPAGE =
 # also VERBATIM_HEADERS is set to NO.
 # The default value is: NO.
 
-SOURCE_BROWSER         = NO
+SOURCE_BROWSER         = YES
 
 # Setting the INLINE_SOURCES tag to YES will include the body of functions,
 # classes and enums directly into the documentation.
@@ -1551,7 +1551,7 @@ SKIP_FUNCTION_MACROS   = YES
 # the path). If a tag file is not located in the directory in which doxygen is
 # run, you must also specify the path to the tagfile here.
 
-TAGFILES               = sllt.tag=http://spinnakermanchester.github.io/spinnaker_tools/ common.tag=http://spinnakermanchester.github.io/spinn_common/ fec.tag=http://spinnakermanchester.github.io/SpiNNFrontEndCommon/c/ 
+TAGFILES               = sllt.tag=http://spinnakermanchester.github.io/spinnaker_tools/ common.tag=http://spinnakermanchester.github.io/spinn_common/ fec.tag=http://spinnakermanchester.github.io/SpiNNFrontEndCommon/c/
 
 # When a file name is specified after GENERATE_TAGFILE, doxygen will create a
 # tag file that is based on the input files it reads. See section "Linking to

neural_modelling/src/common/neuron-typedefs.h

@@ -17,6 +17,11 @@
 
 /*! \file
  * \brief   Data type definitions for SpiNNaker Neuron-modelling
+ * \details
+ *      Defines a spike with either a payload or not and implements the
+ *      functionality to extract the key and payload in both cases. If the
+ *      spike is compiled as not having a payload, the payload will always be
+ *      returned as 0.
  */
 
 #ifndef __NEURON_TYPEDEFS_H__
@@ -25,22 +30,13 @@
 #include <common-typedefs.h>
 #include "maths-util.h"
 
-// Determine the type of a spike
-/*
- * defines a spike with either a pay load or not and implements the
- * functionality to extract the key and pay load in both cases. If the
- * spike is compiled as not having a pay load, the pay load will always be
- * returned as 0
- */
-#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;
 
@@ -51,56 +47,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(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

@@ -28,11 +28,12 @@
 #include <simulation.h>
 #include <spin1_api.h>
 
-//! 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(
@@ -297,10 +296,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, uint payload) {
@@ -321,8 +319,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

@@ -148,7 +148,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) {
@@ -246,7 +246,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