X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fuser.pod;h=a35ae3fabd5e34eeadce6efbac6dd694fadb86f8;hb=fd9692ddc44d2488c5cf127735be8b851474b65c;hp=373c53604bcafd8fe4eceb6cc38643d53260009d;hpb=27b230c534bdef3411e89011354b8606514f8614;p=platform%2Fupstream%2Fisl.git diff --git a/doc/user.pod b/doc/user.pod index 373c536..a35ae3f 100644 --- a/doc/user.pod +++ b/doc/user.pod @@ -343,7 +343,184 @@ before the C itself is freed. isl_ctx *isl_ctx_alloc(); void isl_ctx_free(isl_ctx *ctx); -=head2 Integers +=head2 Values + +An C represents an integer value, a rational value +or one of three special values, infinity, negative infinity and NaN. +Some predefined values can be created using the following functions. + + #include + __isl_give isl_val *isl_val_zero(isl_ctx *ctx); + __isl_give isl_val *isl_val_one(isl_ctx *ctx); + __isl_give isl_val *isl_val_nan(isl_ctx *ctx); + __isl_give isl_val *isl_val_infty(isl_ctx *ctx); + __isl_give isl_val *isl_val_neginfty(isl_ctx *ctx); + +Specific integer values can be created using the following functions. + + #include + __isl_give isl_val *isl_val_int_from_si(isl_ctx *ctx, + long i); + __isl_give isl_val *isl_val_int_from_ui(isl_ctx *ctx, + unsigned long u); + +They can be copied and freed using the following functions. + + #include + __isl_give isl_val *isl_val_copy(__isl_keep isl_val *v); + void *isl_val_free(__isl_take isl_val *v); + +They can be inspected using the following functions. + + #include + isl_ctx *isl_val_get_ctx(__isl_keep isl_val *val); + long isl_val_get_num_si(__isl_keep isl_val *v); + long isl_val_get_den_si(__isl_keep isl_val *v); + double isl_val_get_d(__isl_keep isl_val *v); + +Note that C, C and +C can only be applied to rational values. + +An C can be modified using the following function. + + #include + __isl_give isl_val *isl_val_set_si(__isl_take isl_val *v, + long i); + +The following unary properties are defined on Cs. + + #include + int isl_val_sgn(__isl_keep isl_val *v); + int isl_val_is_zero(__isl_keep isl_val *v); + int isl_val_is_one(__isl_keep isl_val *v); + int isl_val_is_negone(__isl_keep isl_val *v); + int isl_val_is_nonneg(__isl_keep isl_val *v); + int isl_val_is_nonpos(__isl_keep isl_val *v); + int isl_val_is_pos(__isl_keep isl_val *v); + int isl_val_is_neg(__isl_keep isl_val *v); + int isl_val_is_int(__isl_keep isl_val *v); + int isl_val_is_rat(__isl_keep isl_val *v); + int isl_val_is_nan(__isl_keep isl_val *v); + int isl_val_is_infty(__isl_keep isl_val *v); + int isl_val_is_neginfty(__isl_keep isl_val *v); + +Note that the sign of NaN is undefined. + +The following binary properties are defined on pairs of Cs. + + #include + int isl_val_lt(__isl_keep isl_val *v1, + __isl_keep isl_val *v2); + int isl_val_le(__isl_keep isl_val *v1, + __isl_keep isl_val *v2); + int isl_val_gt(__isl_keep isl_val *v1, + __isl_keep isl_val *v2); + int isl_val_ge(__isl_keep isl_val *v1, + __isl_keep isl_val *v2); + int isl_val_eq(__isl_keep isl_val *v1, + __isl_keep isl_val *v2); + int isl_val_ne(__isl_keep isl_val *v1, + __isl_keep isl_val *v2); + +For integer Cs we additionally have the following binary property. + + #include + int isl_val_is_divisible_by(__isl_keep isl_val *v1, + __isl_keep isl_val *v2); + +An C can also be compared to an integer using the following +function. The result is undefined for NaN. + + #include + int isl_val_cmp_si(__isl_keep isl_val *v, long i); + +The following unary operations are available on Cs. + + #include + __isl_give isl_val *isl_val_abs(__isl_take isl_val *v); + __isl_give isl_val *isl_val_neg(__isl_take isl_val *v); + __isl_give isl_val *isl_val_floor(__isl_take isl_val *v); + __isl_give isl_val *isl_val_ceil(__isl_take isl_val *v); + __isl_give isl_val *isl_val_trunc(__isl_take isl_val *v); + +The following binary operations are available on Cs. + + #include + __isl_give isl_val *isl_val_abs(__isl_take isl_val *v); + __isl_give isl_val *isl_val_neg(__isl_take isl_val *v); + __isl_give isl_val *isl_val_floor(__isl_take isl_val *v); + __isl_give isl_val *isl_val_ceil(__isl_take isl_val *v); + __isl_give isl_val *isl_val_trunc(__isl_take isl_val *v); + __isl_give isl_val *isl_val_2exp(__isl_take isl_val *v); + __isl_give isl_val *isl_val_min(__isl_take isl_val *v1, + __isl_take isl_val *v2); + __isl_give isl_val *isl_val_max(__isl_take isl_val *v1, + __isl_take isl_val *v2); + __isl_give isl_val *isl_val_add(__isl_take isl_val *v1, + __isl_take isl_val *v2); + __isl_give isl_val *isl_val_add_ui(__isl_take isl_val *v1, + unsigned long v2); + __isl_give isl_val *isl_val_sub(__isl_take isl_val *v1, + __isl_take isl_val *v2); + __isl_give isl_val *isl_val_sub_ui(__isl_take isl_val *v1, + unsigned long v2); + __isl_give isl_val *isl_val_mul(__isl_take isl_val *v1, + __isl_take isl_val *v2); + __isl_give isl_val *isl_val_mul_ui(__isl_take isl_val *v1, + unsigned long v2); + __isl_give isl_val *isl_val_div(__isl_take isl_val *v1, + __isl_take isl_val *v2); + +On integer values, we additionally have the following operations. + + #include + __isl_give isl_val *isl_val_2exp(__isl_take isl_val *v); + __isl_give isl_val *isl_val_mod(__isl_take isl_val *v1, + __isl_take isl_val *v2); + __isl_give isl_val *isl_val_gcd(__isl_take isl_val *v1, + __isl_take isl_val *v2); + __isl_give isl_val *isl_val_gcdext(__isl_take isl_val *v1, + __isl_take isl_val *v2, __isl_give isl_val **x, + __isl_give isl_val **y); + +The function C returns the greatest common divisor g +of C and C as well as two integers C<*x> and C<*y> such +that C<*x> * C + C<*y> * C = g. + +A value can be read from input using + + #include + __isl_give isl_val *isl_val_read_from_str(isl_ctx *ctx, + const char *str); + +A value can be printed using + + #include + __isl_give isl_printer *isl_printer_print_val( + __isl_take isl_printer *p, __isl_keep isl_val *v); + +=head3 GMP specific functions + +These functions are only available if C has been compiled with C +support. + +Specific integer and rational values can be created from C values using +the following functions. + + #include + __isl_give isl_val *isl_val_int_from_gmp(isl_ctx *ctx, + mpz_t z); + __isl_give isl_val *isl_val_from_gmp(isl_ctx *ctx, + const mpz_t n, const mpz_t d); + +The numerator and denominator of a rational value can be extracted as +C values using the following functions. + + #include + int isl_val_get_num_gmp(__isl_keep isl_val *v, mpz_t z); + int isl_val_get_den_gmp(__isl_keep isl_val *v, mpz_t z); + +=head2 Integers (obsolescent) All operations on integers, mainly the coefficients of the constraints describing the sets and relations, @@ -734,6 +911,10 @@ of the original object. __isl_give isl_space *isl_union_pw_qpolynomial_fold_get_space( __isl_keep isl_union_pw_qpolynomial_fold *upwf); + #include + __isl_give isl_space *isl_multi_val_get_space( + __isl_keep isl_multi_val *mv); + #include __isl_give isl_space *isl_aff_get_domain_space( __isl_keep isl_aff *aff); @@ -1328,12 +1509,19 @@ using the following functions. __isl_take isl_constraint *constraint, isl_int v); __isl_give isl_constraint *isl_constraint_set_constant_si( __isl_take isl_constraint *constraint, int v); + __isl_give isl_constraint *isl_constraint_set_constant_val( + __isl_take isl_constraint *constraint, + __isl_take isl_val *v); __isl_give isl_constraint *isl_constraint_set_coefficient( __isl_take isl_constraint *constraint, enum isl_dim_type type, int pos, isl_int v); __isl_give isl_constraint *isl_constraint_set_coefficient_si( __isl_take isl_constraint *constraint, enum isl_dim_type type, int pos, int v); + __isl_give isl_constraint * + isl_constraint_set_coefficient_val( + __isl_take isl_constraint *constraint, + enum isl_dim_type type, int pos, isl_val *v); __isl_give isl_basic_map *isl_basic_map_add_constraint( __isl_take isl_basic_map *bmap, __isl_take isl_constraint *constraint); @@ -1605,9 +1793,14 @@ the following functions. enum isl_dim_type type, unsigned pos); void isl_constraint_get_constant( __isl_keep isl_constraint *constraint, isl_int *v); + __isl_give isl_val *isl_constraint_get_constant_val( + __isl_keep isl_constraint *constraint); void isl_constraint_get_coefficient( __isl_keep isl_constraint *constraint, enum isl_dim_type type, int pos, isl_int *v); + __isl_give isl_val *isl_constraint_get_coefficient_val( + __isl_keep isl_constraint *constraint, + enum isl_dim_type type, int pos); int isl_constraint_involves_dims( __isl_keep isl_constraint *constraint, enum isl_dim_type type, unsigned first, unsigned n); @@ -2165,6 +2358,10 @@ dimensions have opposite values. __isl_give isl_map *isl_map_order_lt(__isl_take isl_map *map, enum isl_dim_type type1, int pos1, enum isl_dim_type type2, int pos2); + __isl_give isl_basic_map *isl_basic_map_order_gt( + __isl_take isl_basic_map *bmap, + enum isl_dim_type type1, int pos1, + enum isl_dim_type type2, int pos2); __isl_give isl_map *isl_map_order_gt(__isl_take isl_map *map, enum isl_dim_type type1, int pos1, enum isl_dim_type type2, int pos2); @@ -2817,10 +3014,17 @@ a parametric set as well. __isl_give isl_set *isl_set_preimage_pw_multi_aff( __isl_take isl_set *set, __isl_take isl_pw_multi_aff *pma); + __isl_give isl_map *isl_map_preimage_domain_multi_aff( + __isl_take isl_map *map, + __isl_take isl_multi_aff *ma); + __isl_give isl_union_map * + isl_union_map_preimage_domain_multi_aff( + __isl_take isl_union_map *umap, + __isl_take isl_multi_aff *ma); -These functions compute the preimage of the given set under +These functions compute the preimage of the given set or map domain under the given function. In other words, the expression is plugged -into the set description. +into the set description or into the domain of the map. Objects of types C and C are described in L. @@ -3066,6 +3270,10 @@ returning a basic set or relation. __isl_take isl_basic_map *bmap, __isl_take isl_basic_set *dom, __isl_give isl_set **empty); + __isl_give isl_pw_multi_aff *isl_set_lexmin_pw_multi_aff( + __isl_take isl_set *set); + __isl_give isl_pw_multi_aff *isl_set_lexmax_pw_multi_aff( + __isl_take isl_set *set); __isl_give isl_pw_multi_aff *isl_map_lexmin_pw_multi_aff( __isl_take isl_map *map); __isl_give isl_pw_multi_aff *isl_map_lexmax_pw_multi_aff( @@ -3074,7 +3282,7 @@ returning a basic set or relation. =head2 Lists Lists are defined over several element types, including -C, C, C, C, +C, C, C, C, C, C, C, C and C. Here we take lists of Cs as an example. Lists can be created, copied, modified and freed using the following functions. @@ -3101,6 +3309,11 @@ Lists can be created, copied, modified and freed using the following functions. __isl_give isl_set_list *isl_set_list_concat( __isl_take isl_set_list *list1, __isl_take isl_set_list *list2); + __isl_give isl_set_list *isl_set_list_sort( + __isl_take isl_set_list *list, + int (*cmp)(__isl_keep isl_set *a, + __isl_keep isl_set *b, void *user), + void *user); void *isl_set_list_free(__isl_take isl_set_list *list); C creates an empty list with a capacity for @@ -3117,6 +3330,18 @@ Lists can be inspected using the following functions. int isl_set_list_foreach(__isl_keep isl_set_list *list, int (*fn)(__isl_take isl_set *el, void *user), void *user); + int isl_set_list_foreach_scc(__isl_keep isl_set_list *list, + int (*follows)(__isl_keep isl_set *a, + __isl_keep isl_set *b, void *user), + void *follows_user + int (*fn)(__isl_take isl_set *el, void *user), + void *fn_user); + +The function C calls C on each of the +strongly connected components of the graph with as vertices the elements +of C and a directed edge from vertex C to vertex C +iff C returns C<1>. The callbacks C and C +should return C<-1> on error. Lists can be printed using @@ -3125,6 +3350,94 @@ Lists can be printed using __isl_take isl_printer *p, __isl_keep isl_set_list *list); +=head2 Multiple Values + +An C object represents a sequence of zero or more values, +living in a set space. + +An C can be constructed from an C +using the following function + + #include + __isl_give isl_multi_val *isl_multi_val_from_val_list( + __isl_take isl_space *space, + __isl_take isl_val_list *list); + +The zero multiple value (with value zero for each set dimension) +can be created using the following function. + + #include + __isl_give isl_multi_val *isl_multi_val_zero( + __isl_take isl_space *space); + +Multiple values can be copied and freed using + + #include + __isl_give isl_multi_val *isl_multi_val_copy( + __isl_keep isl_multi_val *mv); + void *isl_multi_val_free(__isl_take isl_multi_val *mv); + +They can be inspected using + + #include + isl_ctx *isl_multi_val_get_ctx( + __isl_keep isl_multi_val *mv); + unsigned isl_multi_val_dim(__isl_keep isl_multi_val *mv, + enum isl_dim_type type); + __isl_give isl_val *isl_multi_val_get_val( + __isl_keep isl_multi_val *mv, int pos); + const char *isl_multi_val_get_tuple_name( + __isl_keep isl_multi_val *mv, + enum isl_dim_type type); + +They can be modified using + + #include + __isl_give isl_multi_val *isl_multi_val_set_val( + __isl_take isl_multi_val *mv, int pos, + __isl_take isl_val *val); + __isl_give isl_multi_val *isl_multi_val_set_dim_name( + __isl_take isl_multi_val *mv, + enum isl_dim_type type, unsigned pos, const char *s); + __isl_give isl_multi_val *isl_multi_val_set_tuple_name( + __isl_take isl_multi_val *mv, + enum isl_dim_type type, const char *s); + __isl_give isl_multi_val *isl_multi_val_set_tuple_id( + __isl_take isl_multi_val *mv, + enum isl_dim_type type, __isl_take isl_id *id); + + __isl_give isl_multi_val *isl_multi_val_insert_dims( + __isl_take isl_multi_val *mv, + enum isl_dim_type type, unsigned first, unsigned n); + __isl_give isl_multi_val *isl_multi_val_add_dims( + __isl_take isl_multi_val *mv, + enum isl_dim_type type, unsigned n); + __isl_give isl_multi_val *isl_multi_val_drop_dims( + __isl_take isl_multi_val *mv, + enum isl_dim_type type, unsigned first, unsigned n); + +Operations include + + #include + __isl_give isl_multi_val *isl_multi_val_align_params( + __isl_take isl_multi_val *mv, + __isl_take isl_space *model); + __isl_give isl_multi_val *isl_multi_val_range_splice( + __isl_take isl_multi_val *mv1, unsigned pos, + __isl_take isl_multi_val *mv2); + __isl_give isl_multi_val *isl_multi_val_range_product( + __isl_take isl_multi_val *mv1, + __isl_take isl_multi_val *mv2); + __isl_give isl_multi_val *isl_multi_val_flat_range_product( + __isl_take isl_multi_val *mv1, + __isl_take isl_multi_aff *mv2); + __isl_give isl_multi_val *isl_multi_val_add_val( + __isl_take isl_multi_val *mv, + __isl_take isl_val *v); + __isl_give isl_multi_val *isl_multi_val_mod_val( + __isl_take isl_multi_val *mv, + __isl_take isl_val *v); + =head2 Vectors Vectors can be created, copied and freed using the following functions. @@ -3142,14 +3455,21 @@ The elements can be changed and inspected using the following functions. int isl_vec_size(__isl_keep isl_vec *vec); int isl_vec_get_element(__isl_keep isl_vec *vec, int pos, isl_int *v); + __isl_give isl_val *isl_vec_get_element_val( + __isl_keep isl_vec *vec, int pos); __isl_give isl_vec *isl_vec_set_element( __isl_take isl_vec *vec, int pos, isl_int v); __isl_give isl_vec *isl_vec_set_element_si( __isl_take isl_vec *vec, int pos, int v); + __isl_give isl_vec *isl_vec_set_element_val( + __isl_take isl_vec *vec, int pos, + __isl_take isl_val *v); __isl_give isl_vec *isl_vec_set(__isl_take isl_vec *vec, isl_int v); __isl_give isl_vec *isl_vec_set_si(__isl_take isl_vec *vec, int v); + __isl_give isl_vec *isl_vec_set_val( + __isl_take isl_vec *vec, __isl_take isl_val *v); __isl_give isl_vec *isl_vec_fdiv_r(__isl_take isl_vec *vec, isl_int m); @@ -3169,7 +3489,7 @@ Matrices can be created, copied and freed using the following functions. __isl_give isl_mat *isl_mat_alloc(isl_ctx *ctx, unsigned n_row, unsigned n_col); __isl_give isl_mat *isl_mat_copy(__isl_keep isl_mat *mat); - void isl_mat_free(__isl_take isl_mat *mat); + void *isl_mat_free(__isl_take isl_mat *mat); Note that the elements of a newly created matrix may have arbitrary values. The elements can be changed and inspected using the following functions. @@ -3179,10 +3499,15 @@ The elements can be changed and inspected using the following functions. int isl_mat_cols(__isl_keep isl_mat *mat); int isl_mat_get_element(__isl_keep isl_mat *mat, int row, int col, isl_int *v); + __isl_give isl_val *isl_mat_get_element_val( + __isl_keep isl_mat *mat, int row, int col); __isl_give isl_mat *isl_mat_set_element(__isl_take isl_mat *mat, int row, int col, isl_int v); __isl_give isl_mat *isl_mat_set_element_si(__isl_take isl_mat *mat, int row, int col, int v); + __isl_give isl_mat *isl_mat_set_element_val( + __isl_take isl_mat *mat, int row, int col, + __isl_take isl_val *v); C will return a negative value if anything went wrong. In that case, the value of C<*v> is undefined. @@ -3344,12 +3669,18 @@ It can be modified using __isl_take isl_aff *aff, isl_int v); __isl_give isl_aff *isl_aff_set_constant_si( __isl_take isl_aff *aff, int v); + __isl_give isl_aff *isl_aff_set_constant_val( + __isl_take isl_aff *aff, __isl_take isl_val *v); __isl_give isl_aff *isl_aff_set_coefficient( __isl_take isl_aff *aff, enum isl_dim_type type, int pos, isl_int v); __isl_give isl_aff *isl_aff_set_coefficient_si( __isl_take isl_aff *aff, enum isl_dim_type type, int pos, int v); + __isl_give isl_aff *isl_aff_set_coefficient_val( + __isl_take isl_aff *aff, + enum isl_dim_type type, int pos, + __isl_take isl_val *v); __isl_give isl_aff *isl_aff_set_denominator( __isl_take isl_aff *aff, isl_int v); @@ -3357,6 +3688,8 @@ It can be modified using __isl_take isl_aff *aff, isl_int v); __isl_give isl_aff *isl_aff_add_constant_si( __isl_take isl_aff *aff, int v); + __isl_give isl_aff *isl_aff_add_constant_val( + __isl_take isl_aff *aff, __isl_take isl_val *v); __isl_give isl_aff *isl_aff_add_constant_num( __isl_take isl_aff *aff, isl_int v); __isl_give isl_aff *isl_aff_add_constant_num_si( @@ -3387,9 +3720,13 @@ It can be modified using __isl_take isl_pw_aff *pwaff, enum isl_dim_type type, unsigned first, unsigned n); -Note that the C and C functions +Note that C, C, +C and C set the I of the constant or coefficient, while -C and C add an integer value to +C and C set +the constant or coefficient as a whole. +The C and C functions add an integer +or rational value to the possibly rational constant or coefficient. The C functions add an integer value to the numerator. @@ -4079,9 +4416,16 @@ using int isl_point_get_coordinate(__isl_keep isl_point *pnt, enum isl_dim_type type, int pos, isl_int *v); + __isl_give isl_val *isl_point_get_coordinate_val( + __isl_keep isl_point *pnt, + enum isl_dim_type type, int pos); __isl_give isl_point *isl_point_set_coordinate( __isl_take isl_point *pnt, enum isl_dim_type type, int pos, isl_int v); + __isl_give isl_point *isl_point_set_coordinate_val( + __isl_take isl_point *pnt, + enum isl_dim_type type, int pos, + __isl_take isl_val *v); __isl_give isl_point *isl_point_add_ui( __isl_take isl_point *pnt,