spin1_api.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015 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.
 */
 
#ifndef __SPIN1_API_H__
#define __SPIN1_API_H__
 
#include "sark.h"
 
// ------------------------------------------------------------------------
// Useful SpiNNaker parameters
// ------------------------------------------------------------------------
/* shared memory */
/* system RAM address and size */
#define SPINN_SYSRAM_BASE     SYSRAM_BASE
#define SPINN_SYSRAM_SIZE     SYSRAM_SIZE
/* SDRAM address and size */
#define SPINN_SDRAM_BASE      SDRAM_BASE
#define SPINN_SDRAM_SIZE      SDRAM_SIZE
 
// ------------------------------------------------------------------------
// general parameters and definitions
// ------------------------------------------------------------------------
/* boolean constants */
#define TRUE               (0 == 0)
#define FALSE              (0 != 0)
/* function results   */
#define SUCCESS            (uint) 1
#define FAILURE            (uint) 0
 
#ifndef NULL
#define NULL               0
#endif // NULL
 
// ------------------------------------------------------------------------
// event definitions
// ------------------------------------------------------------------------
enum {
    NUM_EVENTS =           8, 
    MC_PACKET_RECEIVED =   0, 
    DMA_TRANSFER_DONE =    1, 
    TIMER_TICK =           2, 
    SDP_PACKET_RX =        3, 
    USER_EVENT =           4, 
    MCPL_PACKET_RECEIVED = 5, 
    FR_PACKET_RECEIVED =   6, 
    FRPL_PACKET_RECEIVED = 7  
};
 
static const uint VIC_EVENTS[] = {
    (1 << CC_MC_INT),         
    (1 << DMA_DONE_INT),      
    (1 << TIMER1_INT),        
    0,                        
    (1 << SOFTWARE_INT),      
    (1 << CC_MC_INT),         
    (1 << CC_FR_INT),         
    (1 << CC_FR_INT)          
};
 
// ------------------------------------------------------------------------
// DMA transfer parameters
// ------------------------------------------------------------------------
enum {
    DMA_READ =          0, 
    DMA_WRITE =         1  
};
 
// ------------------------------------------------------------------------
// packet parameters
// ------------------------------------------------------------------------
enum {
    NO_PAYLOAD =        0, 
    WITH_PAYLOAD =      1  
};
 
// ------------------------------------------------------------------------
// type definitions
// ------------------------------------------------------------------------
 
typedef void (*callback_t) (uint, uint);  // callbacks
// ------------------------------------------------------------------------
 
 
// ------------------------------------------------------------------------
// simulation control functions
// ------------------------------------------------------------------------
uint spin1_start(sync_bool sync);
uint spin1_start_paused(void);
void spin1_exit(uint error);
 
void spin1_set_timer_tick_and_phase(uint time, uint phase);
 
static inline void spin1_set_timer_tick(uint time)
{
    spin1_set_timer_tick_and_phase(time, 0);
}
 
uint spin1_get_simulation_time(void);
void spin1_pause(void);
void spin1_resume(sync_bool sync);
void spin1_rte(rte_code code);
 
static inline void spin1_delay_us(uint n) {
    sark_delay_us(n);
}
 
void spin1_enable_timer_schedule_proc(void);
 
// ------------------------------------------------------------------------
 
 
// ------------------------------------------------------------------------
// callback and task functions
// ------------------------------------------------------------------------
NONNULL void
spin1_callback_on(uint event_id, callback_t cback, int priority);
 
void spin1_callback_off(uint event_id);
 
NONNULL uint
spin1_schedule_callback(callback_t cback, uint arg0, uint arg1, uint priority);
 
uint spin1_trigger_user_event(uint arg0, uint arg1);
// ------------------------------------------------------------------------
 
 
// ------------------------------------------------------------------------
//  data transfer functions
// ------------------------------------------------------------------------
NONNULL uint
spin1_dma_transfer(uint tag, void *system_address, void *tcm_address,
        uint direction, uint length);
 
void spin1_dma_flush(void);
 
NONNULL void
spin1_memcpy(void *dst, void const *src, uint len);
// ------------------------------------------------------------------------
 
 
// ------------------------------------------------------------------------
//  communications functions
// ------------------------------------------------------------------------
 
void spin1_flush_rx_packet_queue(void);
void spin1_flush_tx_packet_queue(void);
uint spin1_send_packet(uint key, uint data, uint TCR);
 
static inline uint spin1_send_mc_packet(uint key, uint data, uint load) {
    uint tcr = (load) ? PKT_MC_PL : PKT_MC;
 
    return spin1_send_packet(key, data, tcr);
}
 
static inline uint spin1_send_fr_packet(uint key, uint data, uint load) {
    uint tcr = (load) ? PKT_FR_PL : PKT_FR;
 
    return spin1_send_packet(key, data, tcr);
}
 
// ------------------------------------------------------------------------
 
 
// ------------------------------------------------------------------------
// SDP related functions
// ------------------------------------------------------------------------
 
static inline NONNULL void spin1_msg_free(sdp_msg_t *msg) {
    sark_msg_free(msg);
}
 
static inline sdp_msg_t* spin1_msg_get(void) {
    return sark_msg_get();
}
 
static inline NONNULL uint
spin1_send_sdp_msg(sdp_msg_t *msg, uint timeout) {
    return sark_msg_send(msg, timeout);
}
 
// ------------------------------------------------------------------------
 
 
// ------------------------------------------------------------------------
//  interrupt control functions
// ------------------------------------------------------------------------
 
#ifndef SPIN1_INLINE
#ifdef __GNUC__
#define SPIN1_INLINE static __inline __attribute__((always_inline))
#else
#define SPIN1_INLINE static __forceinline
#endif
#endif
 
SPIN1_INLINE void spin1_store_barrier(void)
{
#ifdef __GNUC__
    // GCC only really has one kind of barrier, and this is how to do it
    asm volatile("" : : : "cc", "memory");
#else
    __force_stores();
#endif
}
 
SPIN1_INLINE void spin1_memory_barrier(void)
{
#ifdef __GNUC__
    // GCC only really has one kind of barrier, and this is how to do it
    asm volatile("" : : : "cc", "memory");
#else
    __memory_changed();
#endif
}
 
#ifdef THUMB
// Implemented in sark_alib.s; needs to be in ARM mode, not THUMB
extern uint spin1_irq_disable(void);
#else
SPIN1_INLINE uint spin1_irq_disable(void)
{
    uint old_val, new_val;
 
#ifdef __GNUC__
    asm volatile (
    "mrs    %[old_val], cpsr \n\
     orr    %[new_val], %[old_val], #0x80 \n\
     msr    cpsr_c, %[new_val] \n"
     : [old_val] "=r" (old_val), [new_val] "=r" (new_val)
     :
     : );
#else
    __asm { mrs old_val, cpsr }
    __asm { orr new_val, old_val, 0x80 }
    __asm { msr cpsr_c, new_val }
#endif
 
    spin1_memory_barrier();
    return old_val;
}
#endif
 
#ifdef THUMB
// Implemented in sark_alib.s; needs to be in ARM mode, not THUMB
extern uint spin1_fiq_disable(void);
#else
SPIN1_INLINE uint spin1_fiq_disable(void)
{
    uint old_val, new_val;
 
#ifdef __GNUC__
    asm volatile (
    "mrs    %[old_val], cpsr \n\
     orr    %[new_val], %[old_val], #0x40 \n\
     msr    cpsr_c, %[new_val] \n"
     : [old_val] "=r" (old_val), [new_val] "=r" (new_val)
     :
     : );
#else
    __asm { mrs old_val, cpsr }
    __asm { orr new_val, old_val, 0x40 }
    __asm { msr cpsr_c, new_val }
#endif
 
    spin1_memory_barrier();
    return old_val;
}
#endif
 
#ifdef THUMB
// Implemented in sark_alib.s; needs to be in ARM mode, not THUMB
extern uint spin1_int_disable(void);
#else
SPIN1_INLINE uint spin1_int_disable(void)
{
    uint old_val, new_val;
 
#ifdef __GNUC__
    asm volatile (
    "mrs    %[old_val], cpsr \n\
     orr    %[new_val], %[old_val], #0xc0 \n\
     msr    cpsr_c, %[new_val] \n"
     : [old_val] "=r" (old_val), [new_val] "=r" (new_val)
     :
     : );
#else
    __asm { mrs old_val, cpsr }
    __asm { orr new_val, old_val, 0xc0 }
    __asm { msr cpsr_c, new_val }
#endif
 
    spin1_memory_barrier();
    return old_val;
}
#endif
 
#ifdef THUMB
// Implemented in sark_alib.s; needs to be in ARM mode, not THUMB
extern void spin1_mode_restore(uint value);
#else
SPIN1_INLINE void spin1_mode_restore(uint value)
{
    spin1_store_barrier();
 
#ifdef __GNUC__
    asm volatile (
    "msr    cpsr_c, %[value]"
    :
    : [value] "r" (value)
    :);
#else
    __asm { msr cpsr_c, value }
#endif
}
#endif
 
 
// ------------------------------------------------------------------------
 
 
// ------------------------------------------------------------------------
//  system resources access functions
// ------------------------------------------------------------------------
uint  spin1_get_id(void);
uint  spin1_get_core_id(void);
uint  spin1_get_chip_id(void);
 
#if 0
//## This routine has been removed - use "rtr_alloc", "rtr_mc_set" instead
uint  spin1_set_mc_table_entry(uint entry, uint key, uint mask, uint route);
#endif
 
static inline SARK_IS_A_MALLOC(1) void*
spin1_malloc(uint bytes) {
    return sark_alloc(bytes, 1);
}
 
static inline void spin1_led_control(uint p) {
    sark_led_set(p);
}
// ------------------------------------------------------------------------
 
 
// ----------------------------------
// pseudo-random number generation
// ----------------------------------
 
static inline void spin1_srand(uint seed) {
    sark_srand(seed);
}
 
static inline uint spin1_rand(void) {
    return sark_rand();
}
 
 
// ------------------------------------------------------------------------
// ------------------------------------------------------------------------
typedef struct {
    uint exit_code;                     
    uint warnings;                      
    uint total_mc_packets;              
    uint dumped_mc_packets;             
    volatile uint discarded_mc_packets; 
    uint dma_transfers;                 
    uint dma_bursts;                    
    uint dma_queue_full;                
    uint task_queue_full;               
    uint tx_packet_queue_full;          
    uint user_event_queue_full;         
    uint writeBack_errors;              
    uint total_fr_packets;              
    uint dumped_fr_packets;             
    uint discarded_fr_packets;          
    uint in_timer_callback;             
    uint number_timer_tic_in_queue;     
    uint largest_number_of_concurrent_timer_tic_overruns;
    uint total_times_tick_tic_callback_overran;
} diagnostics_t;
 
extern diagnostics_t diagnostics;
extern uchar         leadAp;   
// ------------------------------------------------------------------------
 
 
#endif /* __SPIN1_API_H__ */