lib/reconos.h

   1 /*
   2  *                                                        ____  _____
   3  *                            ________  _________  ____  / __ \/ ___/
   4  *                           / ___/ _ \/ ___/ __ \/ __ \/ / / /\__ \
   5  *                          / /  /  __/ /__/ /_/ / / / / /_/ /___/ /
   6  *                         /_/   \___/\___/\____/_/ /_/\____//____/
   7  *
   8  * ======================================================================
   9  *
  10  *   title:        ReconOS library - Main library
  11  *
  12  *   project:      ReconOS
  13  *   author:       Andreas Agne, University of Paderborn
  14  *                 Markus Happe, University of Paderborn
  15  *                 Daniel Borkmann, ETH Zürich
  16  *                 Sebastian Meisner, University of Paderborn
  17  *                 Christoph Rüthing, University of Paderborn
  18  *   description:  Main ReconOS library
  19  *
  20  * ======================================================================
  21  */
  22
  23 #ifndef RECONOS_H
  24 #define RECONOS_H
  25
  26 #include <pthread.h>
  27 #include <stdint.h>
  28
  29 #define RECONOS_VERSION_STRING          "v3.0"
  30
  31
  32 /* == Resource options ================================================== */
  33
  34 struct reconos_resource {
  35         uint32_t type;
  36         void *ptr;
  37 };
  38
  39 #define RECONOS_RESOURCE_TYPE_MBOX     0x00000001
  40 #define RECONOS_RESOURCE_TYPE_SEM      0x00000002
  41 #define RECONOS_RESOURCE_TYPE_MUTEX    0x00000004
  42 #define RECONOS_RESOURCE_TYPE_COND     0x00000008
  43 #define RECONOS_RESOURCE_TYPE_RQ       0x00000010
  44
  45 // just for backward compatability
  46 #define RECONOS_TYPE_MBOX              RECONOS_RESOURCE_TYPE_MBOX
  47 #define RECONOS_TYPE_SEM               RECONOS_RESOURCE_TYPE_SEM
  48 #define RECONOS_TYPE_MUTEX             RECONOS_RESOURCE_TYPE_MUTEX
  49 #define RECONOS_TYPE_COND              RECONOS_RESOURCE_TYPE_COND
  50 #define RECONOS_TYPE_RQ                RECONOS_RESOURCE_TYPE_RQ
  51
  52
  53 /* == Configuration functions =========================================== */
  54
  55 /*
  56  * Structure representing a configuration
  57  *
  58  *   resource         - pointer to the resource array
  59  *   resource_count   - number of resources in the resource array
  60  *   bitstream        - pointer to the bitstream data
  61  *   bitstream_length - length of the bitstream in 32bit-words
  62  *   slot             - slot number the configuration shoul run in
  63  *   name             - human readable name to identify the hardwarethread
  64  */
  65 struct reconos_configuration {
  66         struct reconos_resource *resource;
  67         size_t resource_count;
  68
  69         uint32_t *bitstream;
  70         unsigned int bitstream_length;
  71
  72         int slot;
  73
  74         char *name;
  75 };
  76
  77
  78 /*
  79  * Initializes a new configuration with default values. This function must
  80  * be called for every configuration you want to use.
  81  *
  82  *   cfg  - pointer to the configuration structure
  83  *   name - name to identify the configuration
  84  *   slot - the slot number you want to run the configuration in
  85  *          (the same number as used in reconos_hwt_create)
  86  */
  87 void reconos_configuration_init(struct reconos_configuration *cfg, char *name, int slot);
  88
  89 /*
  90  * Associates a resource array to this configuration. This is the equivalent
  91  * to reconos_set_resources for not reconfigurable hardware threads.
  92  *
  93  *   cfg            - pointer to the configuration structure
  94  *   resource       - pointer to the resource array to use
  95  *   recource_count - number of resources in the resource array
  96  */
  97 void reconos_configuration_setresources(struct reconos_configuration *cfg,
  98                                         struct reconos_resource *resorce,
  99                                         size_t resource_count);
 100
 101 /*
 102  * Associates a bitstream to this configuration to program the FPGA
 103  * on reconfiguration.
 104  *
 105  *   cfg              - pointer to the configuration structure
 106  *   bitstream        - pointer to the bitstream data
 107  *   bitstream_length - length of the bitstream in 32bit-words
 108  */
 109 void reconos_configuration_setbitstream(struct reconos_configuration *cfg,
 110                                         uint32_t *bitstream,
 111                                         unsigned int bitstream_length);
 112 /*
 113  * Loads a bitstram from the filesystem and associates it to the configuration
 114  * by calling reconos_configuration_setbitstream.
 115  *
 116  *   cfg      - pointer to the configuration structure
 117  *   filename - filname of the bitstream-file
 118  */
 119 void reconos_configuration_loadbitstream(struct reconos_configuration *cfg,
 120                                          char *filename);
 121
 122
 123 /* == HWT functions ===================================================== */
 124
 125 /*
 126  * Structure representing a hardware thread
 127  *
 128  *   delegate  - delegate thread associated to the hardware thread
 129  *   osif      - file handle of the OSIF (/dev/osif-<slot>)
 130  *   slot      - slot number the hardware thread is running in
 131  *   is_reconf - boolean attribute indicating whether the hardware thread
 132  *               is reconfigurable or not
 133  *   state     - current state of the hardware thread
 134  *               (IDLE, RUNNING, RECONFIGURING, BLOCKING)
 135  *   cfg       - pointer to the current configuration
 136  *   init_data - pointer to the initialization data
 137  */
 138 struct reconos_hwt {
 139         pthread_t delegate;
 140         int osif;
 141         int slot;
 142
 143         int is_reconf;
 144         int state;
 145
 146         struct reconos_configuration *cfg;
 147         void *init_data;
 148 };
 149
 150 /*
 151  * State definition for the hardware thread
 152  */
 153 #define RECONOS_HWT_STATE_IDLE 0
 154 #define RECONOS_HWT_STATE_RUNNING 1
 155 #define RECONOS_HWT_STATE_RECONFIGURING 2
 156 #define RECONOS_HWT_STATE_BLOCKING 3
 157
 158 /*
 159  * Associates a resource array to this hardware thread.
 160  *
 161  *   hwt            - pointer to the hardware thread
 162  *   resource       - pointer to the resource array to use
 163  *   recource_count - number of resources in the resource array
 164  */
 165 void reconos_hwt_setresources(struct reconos_hwt *hwt,
 166                               struct reconos_resource *resorce,
 167                               size_t resource_count);
 168
 169 /*
 170  * Associated initialization data to this hardware thread.
 171  *
 172  *   hwt       - pointer to the hardware thread
 173  *   init_data - pointer to the iniltialization data
 174  */
 175 void reconos_hwt_setinitdata(struct reconos_hwt *hwt,
 176                              void* init_data);
 177
 178 /*
 179  * Creates a new hardware thread running in the a specific slot. Before
 180  * executed the slot will be resetted.
 181  *
 182  *   hwt  - pointer to the hardware thread
 183  *   slot - slot number to run the hardware thread in
 184  *   arg  - arguments for the delegate thread (passed to pthread_create)
 185  */
 186 void reconos_hwt_create(struct reconos_hwt *hwt,
 187                         int slot, void *arg);
 188
 189 /*
 190  * Creates a new reconfigurable hardwar thread runnin in the specific slot.
 191  * Before ecxecuted the slot is reconfigured with the appropriate bitstream
 192  * and resetted.
 193  *
 194  *   hwt  - pointer to the hardware thread
 195  *   slot - slot number to run the hardware thread in
 196  *          (this number must be the same as used in the configuration)
 197  *   cfg  - pointer to the configuration
 198  *   arg  - arguments for the delegate thread (passed to pthread_create)
 199  */
 200 void reconos_hwt_create_reconf(struct reconos_hwt *hwt,
 201                                int slot,
 202                                struct reconos_configuration *cfg,
 203                                void *arg);
 204
 205
 206 /* == General ReconOS functions ========================================= */
 207
 208 /*
 209  * Cleans up the ReconOS environment and resets the hardware. You should
 210  * call this method before termination to prevent the hardware threads from
 211  * operating and avoid undesirable effects.
 212  * By default this method is registered as a signal handler for SIGINT,
 213  * SIGTERM and SIGABRT. Keep this in mind when overriding these handlers.
 214  */
 215 void reconos_cleanup();
 216
 217 /*
 218  * Initializes the ReconOS environtmen and resets the hardware. You must
 219  * call this method before you can use any ReconOS function.
 220  */
 221 int reconos_init();
 222
 223 /*
 224  * Allows to read out simple statistics of the MMU.
 225  *    tlb_hits    - pointer to store the number of tlb hits in
 226  *    tlb_misses  - pointer to store the number of tlb misses in
 227  *    page_faults - pointer to store the number of page faults in
 228  */
 229 void reconos_mmu_stats(int *tlb_hits, int *tlb_misses,
 230                        int *page_faults);
 231
 232 /*
 233  * Resets a single hardware thread slot.
 234  */
 235 void reconos_slot_reset(int slot, int reset);
 236
 237 /*
 238  * Specifies the scheduler for reconfigurable hardware threads. The
 239  * scheduler will be called when a hardware thread yields. Keep in mind
 240  * that the scheduler can be called concurrently multiple times and must
 241  * be synchronized.
 242  */
 243 void reconos_set_scheduler(struct reconos_configuration* (*scheduler)(struct reconos_hwt *hwt));
 244
 245 /*
 246  * Flushes the cache of the processor. Consider that this method might not
 247  * be implemented on all architectures.
 248  */
 249 void reconos_cache_flush();
 250
 251 #endif /* RECONOS_H */