git.gag.com Git - debian/gnuradio/blob - gcell/include/gcell/gc_job_desc.h

   1 /* -*- c -*- */
   2 /*
   3  * Copyright 2007,2008 Free Software Foundation, Inc.
   4  *
   5  * This file is part of GNU Radio
   6  *
   7  * GNU Radio is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 3, or (at your option)
  10  * any later version.
  11  *
  12  * GNU Radio is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License along
  18  * with this program; if not, write to the Free Software Foundation, Inc.,
  19  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  20  */
  21
  22 #ifndef INCLUDED_GCELL_GC_JOB_DESC_H
  23 #define INCLUDED_GCELL_GC_JOB_DESC_H
  24
  25 /*!
  26  * This file contains the structures that are used to describe how to
  27  * call "jobs" that execute on the SPEs.  A "job" is a task, or piece of
  28  * work that you want to run on an SPE.
  29  *
  30  * There is code running in the SPE that knows how to interpret
  31  * these job descriptions. Thus, in most cases, the overhead
  32  * of invoking these is very low.
  33  *
  34  * The whole "job idea" is SPE centric.  At first pass,
  35  * the PPE will be constructing jobs and enqueing them.
  36  * However, there is nothing in the implementation that
  37  * prohibits SPEs from creating their own jobs in the
  38  * future.  Also, there is nothing prohibiting SPE-to-SPE
  39  * DMA's.
  40  *
  41  * SPE's dequeue and "pull" jobs to themselves, do the work, then
  42  * notify the entity that submitted the job.
  43  */
  44
  45 #include <gcell/gc_types.h>
  46 #include <gcell/gc_job_desc_private.h>
  47
  48 /*
  49  * This is C, not C++ code...
  50  *
  51  * ...and is used by both PPE and SPE code
  52  */
  53 __GC_BEGIN_DECLS
  54
  55
  56 //! opaque ID that specifies which code to invoke on the SPE
  57 typedef uint32_t gc_proc_id_t;
  58 #define GCP_UNKNOWN_PROC ((gc_proc_id_t) -1)
  59
  60
  61 //! final job status
  62 typedef enum {
  63   JS_OK,
  64   JS_SHUTTING_DOWN,         // job mananger is shutting down
  65   JS_TOO_MANY_CLIENTS,      // too many client threads
  66   JS_UNKNOWN_PROC,          // didn't recognize the procedure ID
  67   JS_BAD_DIRECTION,         // EA arg has invalid direction
  68   JS_BAD_EAH,               // not all EA args have the same high 32 address bits
  69   JS_BAD_N_DIRECT,          // too many direct args
  70   JS_BAD_N_EA,              // too many EA args
  71   JS_ARGS_TOO_LONG,         // total length of EA args exceeds limit
  72   JS_BAD_JUJU,              // misc problem: you're having a bad day
  73   JS_BAD_JOB_DESC,          // gc_job_desc was not allocated using mgr->alloc_job_desc()
  74
  75 } gc_job_status_t;
  76
  77 #define MAX_ARGS_DIRECT  8  // maximum number of args passed using "direct" method
  78 #define MAX_ARGS_EA      8  // maximum number of args passed via EA memory (dma)
  79
  80 /*
  81  * We support two classes of arguments,
  82  *   "direct", which are contained in the gc_job_desc_args and
  83  *   "EA", which are copied in/out according to info in gc_job_desc_args
  84  */
  85
  86 /*!
  87  * \brief Tag type of "direct" argument
  88  */
  89 typedef enum {
  90   GCT_S32,
  91   GCT_U32,
  92   GCT_S64,
  93   GCT_U64,
  94   GCT_FLOAT,
  95   GCT_DOUBLE,
  96   GCT_FLT_CMPLX,
  97   GCT_DBL_CMPLX,
  98   GCT_EADDR,
  99
 100 } gc_tag_t;
 101
 102
 103 /*!
 104  * \brief union for passing "direct" argument
 105  */
 106 typedef union gc_arg_union
 107 {
 108   int32_t        s32;
 109   uint32_t       u32;
 110   int64_t        s64;
 111   uint64_t       u64;
 112   float          f;
 113   double         d;
 114   //float complex  cf;  //  64-bits (C99)
 115   //double complex cd;  // 128-bits (C99)
 116   gc_eaddr_t     ea;    //  64-bits
 117 } _AL8 gc_arg_union_t;
 118
 119
 120 /*!
 121  * \brief "direct" input or output arguments
 122  */
 123 typedef struct gc_job_direct_args
 124 {
 125   uint32_t        nargs;                        // # of "direct" args
 126   gc_tag_t        tag[MAX_ARGS_DIRECT] _AL16;   // type of direct arg[i]
 127   gc_arg_union_t  arg[MAX_ARGS_DIRECT] _AL16;   // direct argument values
 128
 129 } _AL16 gc_job_direct_args_t;
 130
 131
 132 // specifies direction for args passed in EA memory
 133
 134 #define GCJD_DMA_GET            0x01            // in to SPE
 135 #define GCJD_DMA_PUT            0x02            // out from SPE
 136
 137 /*!
 138  * \brief Description of args passed in EA memory.
 139  * These are DMA'd between EA and LS as specified.
 140  */
 141 typedef struct gc_job_ea_arg {
 142   //! EA address of buffer
 143   gc_eaddr_t     ea_addr;
 144
 145   //! GC_JD_DMA_* get arg or put arg
 146   uint32_t       direction;
 147
 148   //! number of bytes to get
 149   uint32_t       get_size;
 150
 151   //! number of bytes to put
 152   uint32_t       put_size;
 153
 154 #if defined(__SPU__)
 155   //! local store address (filled in by SPU runtime)
 156   void          *ls_addr;
 157   uint32_t       _pad[2];
 158 #else
 159   uint32_t       _pad[3];
 160 #endif
 161
 162 } _AL16 gc_job_ea_arg_t;
 163
 164
 165 typedef struct gc_job_ea_args {
 166   uint32_t              nargs;
 167   gc_job_ea_arg_t       arg[MAX_ARGS_EA];
 168
 169 } _AL16 gc_job_ea_args_t;
 170
 171
 172 /*!
 173  * \brief "job description" that is DMA'd to/from the SPE.
 174  * \ingroup gcell
 175  */
 176 typedef struct gc_job_desc
 177 {
 178   gc_job_desc_private_t sys;      // internals
 179   gc_job_status_t       status;   // what happened (output)
 180   gc_proc_id_t          proc_id;  // specifies which procedure to run
 181   gc_job_direct_args_t  input;    // direct args to SPE
 182   gc_job_direct_args_t  output;   // direct args from SPE
 183   gc_job_ea_args_t      eaa;      // args passed via EA memory
 184
 185 } _AL128 gc_job_desc_t;
 186
 187
 188 /*!
 189  * type of procedure invoked on spu
 190  */
 191 typedef void (*gc_spu_proc_t)(const gc_job_direct_args_t *input,
 192                               gc_job_direct_args_t *output,
 193                               const gc_job_ea_args_t *eaa);
 194
 195 #if !defined(__SPU__)
 196
 197 static inline gc_job_desc_t *
 198 ea_to_jdp(gc_eaddr_t ea)
 199 {
 200   return (gc_job_desc_t *) ea_to_ptr(ea);
 201 }
 202
 203 static inline gc_eaddr_t
 204 jdp_to_ea(gc_job_desc_t *item)
 205 {
 206   return ptr_to_ea(item);
 207 }
 208
 209 #endif
 210
 211
 212 __GC_END_DECLS
 213
 214 #endif /* INCLUDED_GCELL_GC_JOB_DESC_H */