kitten/include/rca/rca_l0.h

   1 /*
   2  * Copyright (c) 2003 Cray Inc.
   3  *
   4  * The contents of this file is proprietary information of Cray Inc.
   5  * and may not be disclosed without prior written consent.
   6  *
   7  */
   8 /*
   9  * This code is licensed under the GNU General Public License,
  10  * Version 2.  See the file COPYING for more details.
  11  */
  12
  13 #ifndef __RCA_L0_H__
  14 #define __RCA_L0_H__
  15
  16 #include <rca/l0rca_config.h>
  17
  18
  19 /*
  20  * Macros to read/write Seastar Scratch RAM for everyone else.
  21  */
  22 #define SSMEMPUT(dest,src,nb)   memcpy((void *)dest,(void *)src,nb)
  23 #define SSMEMGET(dest,src,nb)   memcpy((void *)dest,(void *)src,nb)
  24
  25 #define SSPUT64(to_ptr,value) (*(to_ptr) = (value))
  26 #define SSPUT32(to_ptr,value) (*(to_ptr) = (value))
  27
  28 #define SSGET64(from_ptr,to_var) ((to_var) = *(from_ptr))
  29 #define SSGET32(from_ptr,to_var) ((to_var) = *(from_ptr))
  30
  31 /* TODO - Revisit these later */
  32 #define LOCK_CHANNEL(chn_num)
  33 #define UNLOCK_CHANNEL(chn_num)
  34
  35 typedef int (*l0rca_down_handle_t)(int chn_num, rs_event_t* buf, int32_t num);
  36 typedef int (*l0rca_up_handle_t)(int chn_num);
  37
  38 typedef struct l0rca_ch_status {
  39         uint32_t        num_obj;                /* number of objects    */
  40         uint32_t        ridx;                   /* read index           */
  41         uint32_t        widx;                   /* write index */
  42         uint32_t        reg_count;
  43         rs_event_t*     ch_buf_ptr;
  44 } l0rca_ch_status_t;
  45
  46 /*
  47  * API defines
  48  * TODO - All API calls defined here may not be implemented in l0rca.c.
  49  * These are to be implemented as needed.
  50  */
  51
  52 /* NOTE
  53  * download means data transfer from the L0 to the Opteron
  54  * upload means data transfer from the Opteron to the LO;
  55  */
  56
  57 #ifdef STANDALONE_DIAGS
  58 /*
  59  * Checks if the channel is ready or not (full).
  60  * Argument:    int     channel
  61  * Returns:
  62  *   1 if ready (not_full)
  63  *   0 if not ready
  64  */
  65 int l0rca_ch_send_ready(int ch_num);
  66
  67 /*
  68  * Clears l0rca_early_cfg.initialized.
  69  * This function is required for memtest. Memtest has to move the location
  70  * of the storage area for the config in order to move on to the next
  71  * region to do the memory test.
  72  */
  73 void l0rca_clear_initialized(void);
  74 #endif
  75
  76 /*
  77  * Function:    l0rca_init_config
  78  *
  79  * Description: Read L0 - RCA communication config structure and populate
  80  *              our personal copy. If there is any error, the OS panics
  81  *              as not being able to communicate with L0 is a total disaster.
  82  *              If already initialized then returns siliently.
  83  *
  84  * Arguments: None.
  85  *
  86  * Returns: None
  87  */
  88 void l0rca_init_config(void);
  89
  90 /*
  91  * Function:    register_ch_down
  92  *
  93  * Description: Register function for the download channel. It is expected that
  94  * there be at most one registered user for a download channel. This user
  95  * provides a callback to be invoked when data from L0 arrives on the channel.
  96  *
  97  * Arguments: int ch_num IN: channel number to register on
  98  *            l0rca_down_handle_t handler IN: callback routine
  99  *            int poll IN: if > zero - duration in ms to check for event
 100  *                         if = zero - event arrival is interrupt driven.
 101  *                         if < zero - do nothing. It is assumed that the user
 102  *                         has her own means to check for event arrival.
 103  *
 104  * Returns: EBUSY - If another user is already registered.
 105  *          zero (SUCCESS) otherwise.
 106  */
 107 int register_ch_down(int ch_num, l0rca_down_handle_t handler, int poll);
 108
 109 /*
 110  * Function:    unregister_ch_down
 111  *
 112  * Description: Unregister function for the download channel. Use to indicate
 113  * that the channel is no longer to be used.
 114  *
 115  * Arguments: int ch_num IN: channel number to unregister
 116  *
 117  * Returns: zero (SUCCESS)
 118  */
 119 int unregister_ch_down(int ch_num);
 120
 121 /*
 122  * Function:    register_ch_up
 123  *
 124  * Description: Register function for the upload channel. It is expected that
 125  * there be at most one registered user for an upload channel. This user
 126  * provides a callback to be invoked when the buffer drains below tshhld
 127  * (only if the buffer became full last time the tshhld was crossed)
 128  *
 129  * Arguments: int ch_num IN: channel number to register on
 130  *            l0rca_up_handle_t handler IN: callback routine
 131  *            int tshhld IN: buffer to drain before invoking callback; ignored
 132  *                           if poll is negative.
 133  *            int poll IN: if > zero - duration in ms to check for buffer drain
 134  *                         if = zero - tx done interrupt invokes callback
 135  *                         if < zero - do nothing. It is assumed that the user
 136  *                         has her own means to check for buffer drain
 137  *
 138  * Returns: -EBUSY - If another user is already registered.
 139  *          -EINVAL - if ch_num is not in range.
 140  *          zero (SUCCESS) otherwise.
 141  */
 142 int register_ch_up(int ch_num, l0rca_up_handle_t handler, int tshhld, int poll);
 143
 144 /*
 145  * Function:    unregister_ch_up
 146  *
 147  * Description: Unregister function for the download channel. Use to indicate
 148  * that the channel is no longer to be used.
 149  *
 150  * Arguments: int ch_num IN: channel number to unregister
 151  *
 152  * Returns: zero (SUCCESS)
 153  */
 154 int unregister_ch_up(int ch_num);
 155
 156 /*
 157  * Function:    ch_send_data
 158  *
 159  * Description: Sends data towards the L0.
 160  * The data that buf points to is sent as the payload in an rs_event structure.
 161  * The header is a separate parameter and the send routine directly copies
 162  * the header and the data into the circular buffer, thus avoiding a copy.
 163  *
 164  * Arguments: int ch_num IN: channel number on which to send data
 165  *            rs_event_t *ev_hdr  IN: Header without len & timestamp
 166  *            void* buf  IN: Buffer with data
 167  *            unsigned int len IN: length of data to transfer
 168  *
 169  * Returns: EBUSY - If the circular channel buffer is full.
 170  *          EINVAL - if no user registered on the channel (Debug only)
 171  *          EFAULT - if buf or ev_hdr is NULL (Debug only)
 172  *          E2BIG -  if len exceeds max event payload (RS_MSG_LEN) (Debug only)
 173  *          zero (SUCCESS) otherwise.
 174  *
 175  * Notes: data in buf will be copied to the channel buffer, therfore, upon
 176  *        return, user can free the buf.
 177  */
 178 int ch_send_data(int ch_num, const rs_event_t *ev_hdr,
 179                  void* buf, unsigned int len);
 180
 181 /*
 182  * Function:    ch_send_event
 183  *
 184  * Description: Sends an event to L0.
 185  *
 186  * Arguments: int ch_num IN: channel number on which to send the event
 187  *            const rs_event_t *evp  IN: EVent to send
 188  *
 189  * Returns: -EINVAL - if no user registered on the channel (Debug only)
 190  *          -EFAULT - if ev_hdr is NULL (Debug only)
 191  *          zero -    SUCCESS, event sent.
 192  *          +EBUSY -  Event not sent. Sender should retry.
 193  *
 194  * Notes: The event will be copied to the channel buffer, therfore, upon
 195  *        return, user may free the space associated with the event
 196  */
 197 int ch_send_event(int ch_num, const rs_event_t *evp);
 198
 199 /*
 200  * Function:    ch_status
 201  *
 202  * Description: Obtain status on the channel
 203  *
 204  * Arguments: int ch_num IN: channel number for which to obtain status
 205  * Arguments: l0rca_ch_status_t *st OUT: status of the channel.
 206  *
 207  * Returns: zero (SUCCESS).
 208  *
 209  * Notes: The status represents the snapshot at the time of invocation.
 210  */
 211 int ch_status(int ch_num, l0rca_ch_status_t *st);
 212
 213 /*
 214  * Function:    l0rca_ch_get_event
 215  *
 216  * Description: Read the next available event (if any). This allows the caller
 217  *              to check for incoming events. It is usefult for those callers
 218  *              that do not have a receive callback.
 219  *
 220  * Arguments: int ch_num IN: channel number from which to return event
 221  * Arguments:  rs_event_t *evp: Pointer where the event may be placed
 222  *
 223  * Returns: 0 or 1 - No of events returned (0 ==> No event otherwise always 1)
 224  *          < 0   - errors such as channel not registered etc.
 225  *
 226  * Note: The receive callback is the preferred way to handle incoming events.
 227  *       This API call should only be used in cases where a receive callback
 228  *       mechanism is not feasible. For example, when interupts are disabled and
 229  *       incoming events need to be serviced. An example user is a kernel
 230  *       debugger.
 231  */
 232 int l0rca_ch_get_event(int ch_num, rs_event_t *evp);
 233
 234 /*
 235  * Function:    l0rca_poll_callback
 236  *
 237  * Description: Scan the incoming channels and call the receive callback
 238  *              (if any) in case an event is pending to be processed.
 239  *              Update the read pointer. Next scan the outgoing channels
 240  *              and if the channel was full, call the transmit done callback
 241  *              so that events may be sent.
 242  *
 243  * Arguments: None
 244  *
 245  * Returns: 0 if no events were processed, else 1.
 246  *
 247  * Note: It is possible that this routine is called from interrupt
 248  *       context. The callbacks invoked *must* not block.
 249  */
 250 int l0rca_poll_callback(void);
 251
 252 /*
 253  * Function:    l0rca_get_proc_id
 254  *
 255  * Description: Return the node/processor id.
 256  *
 257  * Arguments: None
 258  *
 259  * Returns: The proc id.
 260  */
 261 rs_node_t l0rca_get_proc_id(void);
 262
 263 /*
 264  * Function:    l0rca_get_max_xyz
 265  *
 266  * Description: Returns the current system dimensions. This information
 267  *              can be used find the coordinates of the node in the system.
 268  *
 269  * Arguments: int32_t *mx OUT: The x value is stored here after return
 270  *            int32_t *my OUT: The y value is stored here after return
 271  *            int32_t *mz OUT: The z value is stored here after return
 272  *
 273  * Returns: No return value.
 274  */
 275 void l0rca_get_max_xyz(int32_t *mx, int32_t *my, int32_t *mz);
 276
 277 /*
 278  * Function:    l0rca_event_data
 279  *
 280  * Description: Return a pointer to the data portion and length of the
 281  *              data portion of the event.
 282  *
 283  * Arguments: rs_event_t *evp IN: Event whose data is of interest
 284  *            void **data OUT: Upon return will point to data portion of event
 285  *            int32_t *len OUT: Upon return will have the length of the data
 286  *                              portion of the event
 287  *
 288  * Returns: No Return Value.
 289  */
 290 void l0rca_event_data(rs_event_t *evp, void **data, int32_t *len);
 291
 292
 293 #ifdef __KERNEL__
 294 extern int l0_gdb_init(void);
 295 extern int l0rca_kgdb_down_getc(void);
 296 extern int gdb_hook(void);
 297 extern int gdb_getc(int wait);
 298 extern int gdb_putc(char chr);
 299 extern int putDebugPacket(char *buf, int n);
 300 #endif
 301
 302 #endif  /* __RCA_L0_H__ */