codes_mapping.h 8.85 KB
Newer Older
1
/*
Philip Carns's avatar
Philip Carns committed
2
 * Copyright (C) 2013 University of Chicago.
3
 * See COPYRIGHT notice in top-level directory.
Philip Carns's avatar
Philip Carns committed
4
 *
5 6 7 8 9
 */

/* SUMMARY:
 * CODES custom mapping file for ROSS
 */
Jonathan Jenkins's avatar
Jonathan Jenkins committed
10 11 12 13 14 15 16 17

#ifndef CODES_MAPPING_H
#define CODES_MAPPING_H

#ifdef __cplusplus
extern "C" {
#endif

18 19 20 21 22 23 24 25 26 27 28 29
#include "configuration.h"
#include "codes.h"
#include "lp-type-lookup.h"
#define MAX_NAME_LENGTH 256

/* Returns number of LPs on the current PE */
int codes_mapping_get_lps_for_pe(void);

/* Takes the global LP ID and returns the rank (PE id) on which the LP is mapped.*/
tw_peid codes_mapping( tw_lpid gid);

/* loads the configuration file and sets up the number of LPs on each PE. */
30
void codes_mapping_setup(void);
31

32 33 34 35 36 37 38 39
/* set up lps with an RNG offset
 *
 * NOTE: manual seeding is discouraged by the ROSS folks, who instead suggest to
 * set the number of RNGs each LP will "skip". offset here is a multiplier by
 * the global number of LPs
 */
void codes_mapping_setup_with_seed_offset(int offset);

40
/*Takes the group name and returns the number of repetitions in the group */
41
int codes_mapping_get_group_reps(const char* group_name);
42

43 44 45 46 47 48 49 50 51 52 53
/* Calculates the count for LPs of the given type
 *
 * group_name         - name of group. If NULL, count is across all groups.
 * ignore_repetitions - if group_name is given, then don't include repetitions
 *                      in count. This exists at the moment to support some
 *                      uses of the function that haven't been fleshed out in
 *                      other parts of the API (used by the dragonfly/torus
 *                      models)
 * lp_type_name       - name of LP type
 * annotation         - optional annotation. If NULL, entry is considered
 *                      unannotated
54 55 56 57
 * ignore_annos       - If zero, then count in an annotation-specific manner.
 *                      If 1, then count the "first-found" LP in the
 *                          configuration, regardless of annotation.
 *                      Otherwise, count across all annotations.
58 59 60 61 62 63 64 65 66 67
 *
 * returns the number of LPs found (0 in the case of some combination of group,
 * lp_type_name, and annotation not being found)
 */
int codes_mapping_get_lp_count(
        const char * group_name,
        int          ignore_repetitions,
        const char * lp_type_name,
        const char * annotation,
        int          ignore_annos);
68

69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89
/* Calculates the global LP ID given config identifying info. 
 *
 * group_name   - name of group
 * lp_type_name - name of LP type
 * annotation   - optional annotation (NULL -> unannotated)
 * ignore_anno  - ignores annotation and sets gid to the first found LP type
 *                with matching names
 * rep_id       - repetition within the group
 * offset       - lp offset within the repetition
 * gid          - output ID
 *
 * If the LP is unable to be found, a tw_error will occur
 */
void codes_mapping_get_lp_id(
        const char * group_name,
        const char * lp_type_name,
        const char * annotation,
        int          ignore_anno,
        int          rep_id,
        int          offset,
        tw_lpid    * gid);
90

91 92 93 94 95 96 97 98 99 100 101
/* Calculates the LP ID relative to other LPs (0..N-1, where N is the number of
 * LPs sharing the same type)
 *
 * gid             - LP ID
 * group_wise      - whether to compute id relative to the LP's group
 * annotation_wise - whether to compute id relative to the annotation the LP has
 */
int codes_mapping_get_lp_relative_id(
        tw_lpid gid,
        int     group_wise,
        int     annotation_wise);
102

103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124
/* Calculates the ROSS global LP ID of an LP given the relative ID and LP type
 * information
 *
 * relative_id     - LP id relative to set of "like" LPs
 * group_name      - name of LP's group. If non-NULL, ID is considered local
 *                   to that group. If NULL, then ID is considered across all
 *                   groups
 * lp_type_name    - name of the LP to look up. Must be provided
 * annotation      - LP's annotation. If NULL, ID is considered among
 *                   unannotated LPs
 * annotation_wise - whether to consider ID across a specific annotation (using
 *                   the annotation parameter) or all annotations (ignoring the
 *                   annotation parameter)
 */
tw_lpid codes_mapping_get_lpid_from_relative(
        int          relative_id,
        const char * group_name,
        const char * lp_type_name,
        const char * annotation,
        int          annotation_wise);


125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152
/* Returns configuration group information for a given LP-id
 *
 * gid           - LP to look up
 * group_name    - output LP group name
 * group_index   - index in config struct of group (mostly used internally)
 * lp_type_name  - output LP type name
 * lp_type_index - index in config struct of lp type (mostly used internally)
 * annotation    - output annotation (given that the caller is responsible for
 *                 providing the memory, if there's no annotation then the empty
 *                 string is returned)
 * rep_id        - output repetition within the group
 * offset        - output LP offset within the LP (for multiple lps in a rep.)
 *
 * The *_name and annotation parameters can be NULL, in which case the result
 * strings aren't copied to them. This is useful when you just need the
 * repetition ID and/or the offset. Otherwise, the caller is expected to pass in
 * properly-allocated buffers for each (of size MAX_NAME_LENGTH)
 */
void codes_mapping_get_lp_info(
        tw_lpid gid,
        char  * group_name,
        int   * group_index,
        char  * lp_type_name,
        int   * lp_type_index,
        char  * annotation,
        int   * rep_id,
        int   * offset);

153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170
/* same end result as codes_mapping_get_lp_info, except:
 * - uses pointer-to-const instead of copying to output parameters.
 *   much less copying
 * - gets rid of arguments that are largely intended for internal usage
 * - disambiguates annotation representation - empty string no longer copied
 *   into annotation argument to indicate no annotation - instead, annotation
 *   is set to NULL
 *
 * This function is preferred for performance and simplicity reasons
 */
void codes_mapping_get_lp_info2(
        tw_lpid gid,
        char const * * group_name,
        char const * * lp_type_name,
        char const * * annotation,
        int * rep_id,
        int * offset);

171
//void codes_mapping_get_lp_info(tw_lpid gid, char* group_name, int* grp_id, int* lp_type_id, char* lp_type_name, int* grp_rep_id, int* offset);
172

173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198
/* Returns the annotation for the given LP.
 *
 * group_name   - group name of LP
 * lp_type_name - name of the LP
 *
 * NOTE: This function returns the annotation for the first found LP with
 * lp_type_name within the group. In the case of having multiple LP types with
 * different annotations in the same group, use the _by_lpid version.
 *
 * Either the annotation string or NULL (in the case of an unannotated entry) is
 * returned. */
const char* codes_mapping_get_annotation_by_name(
        const char * group_name,
        const char * lp_type_name);

/* Returns the annotation for the given LP. 
 *
 * gid - LP id to look up
 *
 * NOTE: both functions have equivalent results if there is only one LP type in
 * the requested group. The different ways of accessing are for convenience.
 * This function is the one to use if there are multiple group entries of the
 * same LP type (and different annotations)
 *
 * Either the annotation string or NULL (in the case of an unannotated entry) is
 * returned. */
199
const char* codes_mapping_get_annotation_by_lpid(tw_lpid gid);
Philip Carns's avatar
Philip Carns committed
200

201 202 203
/*
 * Returns a mapping of LP name to all annotations used with the type
 *
204
 * lp_name - lp name as used in the configuration
205 206 207 208
 */
const config_anno_map_t * 
codes_mapping_get_lp_anno_map(const char *lp_name);

209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230
/* the following functions are meant to aide in transferring LP mapping
 * information across PEs - basically, a canonical mapping of names (group,
 * LP, annotations) to indexes. This is separate from the indices returned from
 * codes_mapping_get_lp_info, which points directly to configuration entities
 */

/* returns a canonical index (cid) for the group name, or -1 if not found */
int codes_mapping_get_group_cid_by_name(char const * group_name);
int codes_mapping_get_group_cid_by_lpid(tw_lpid id);
char const * codes_mapping_get_group_name_by_cid(int cid);

/* returns a canonical index (cid) for the LP name, or -1 if not found */
int codes_mapping_get_lp_cid_by_name(char const * lp_type_name);
int codes_mapping_get_lp_cid_by_lpid(tw_lpid id);
char const * codes_mapping_get_lp_name_by_cid(int cid);

/* returns a canonical index (cid) for an annotation, or -1 if not found.
 * NOTE: a NULL or "\0" annotation corresponds to the lack of an annotation */
int codes_mapping_get_anno_cid_by_name(char const * annotation);
int codes_mapping_get_anno_cid_by_lpid(tw_lpid id);
char const * codes_mapping_get_anno_name_by_cid(int cid);

Jonathan Jenkins's avatar
Jonathan Jenkins committed
231 232 233 234 235 236
#ifdef __cplusplus
}
#endif

#endif

Philip Carns's avatar
Philip Carns committed
237 238 239 240 241 242 243 244
/*
 * Local variables:
 *  c-indent-level: 4
 *  c-basic-offset: 4
 * End:
 *
 * vim: ts=8 sts=4 sw=4 expandtab
 */