Sandra rightly complained that the those lang hooks – both the stub and
the real implementation - have a rather suboptimal comment.
This patch improves at least the documentation of the hooks.
Comments, remarks, suggestions?
Tobias
OpenMP: Improve interface comment for the omp_deep_mapping lang hooks
gcc/fortran/ChangeLog:
* trans-openmp.cc (gfc_omp_deep_mapping_p, gfc_omp_deep_mapping_cnt,
gfc_omp_deep_mapping): Improve interface comment.
gcc/ChangeLog:
* langhooks.cc (lhd_omp_deep_mapping_p, lhd_omp_deep_mapping_cnt,
(lhd_omp_deep_mapping): Improve interface comment.
* langhooks.h (lhd_omp_deep_mapping_p, lhd_omp_deep_mapping_cnt,
(lhd_omp_deep_mapping): Likewise
gcc/fortran/trans-openmp.cc | 28 +++++++++++++++++++++++-----
gcc/langhooks.cc | 9 ++++++---
gcc/langhooks.h | 19 ++++++++++++++-----
3 files changed, 43 insertions(+), 13 deletions(-)
diff --git a/gcc/fortran/trans-openmp.cc b/gcc/fortran/trans-openmp.cc
index b9c09d114b7..680e43c1cc0 100644
--- a/gcc/fortran/trans-openmp.cc
+++ b/gcc/fortran/trans-openmp.cc
@@ -2475,8 +2475,11 @@ gfc_omp_deep_mapping_int_p (const gimple *ctx, tree clause)
return decl;
}
-/* Return true if there is deep mapping, even if the number of mapping is known
- at compile time. */
+/* Return true if there is any deep mapping required, even if the number of
+ mappings is known at compile time. Deep mapping is required if the passed
+ CLAUSE is a map clause and its OMP_CLAUSE_DECL refers to a derived-type with
+ allocatable components. CTX is the statement that contains the CLAUSE. */
+
bool
gfc_omp_deep_mapping_p (const gimple *ctx, tree clause)
{
@@ -2622,8 +2625,14 @@ gfc_omp_deep_mapping_do (bool is_cnt, const gimple *ctx, tree clause,
return num;
}
-/* Return tree with a variable which contains the count of deep-mappyings
- (value depends, e.g., on allocation status) */
+/* Returns NULL_TREE if known that no deep mapping is required for the passed
+ 'map' CLAUSE, otherwise returns a size_type expression with the number of
+ required data-mapping operations, which may be zero. Deep mapping is
+ required for allocatable components of derived types; the number of mapping
+ operations depends on the allocation status, array sizes and the dynamic
+ type. CTX is the gimple statement that contains the map CLAUSE; the
+ gimple code used for counting is added to SEQ. */
+
tree
gfc_omp_deep_mapping_cnt (const gimple *ctx, tree clause, gimple_seq *seq)
{
@@ -2631,7 +2640,16 @@ gfc_omp_deep_mapping_cnt (const gimple *ctx, tree clause, gimple_seq *seq)
NULL_TREE, NULL_TREE, NULL_TREE, seq);
}
-/* Does the actual deep mapping. */
+/* Handle the deep mapping for the passed map CLAUSE that is part of
+ the gimple statement CTX by walking all allocated allocatable components
+ and its allocatable components to add additional data-mapping operations.
+ TKIND is the map-type/kind to be used. The generated code is added to
+ SEQ – and the actual struct-field address used for mapping, the map size,
+ and kind value to the arrays DATA, SIZES, and KINDS, respectively.
+ OFFSET_DATA and OFFSET are size-type variables; the map operatations are
+ added at array index OFFSET_DATA for DATA and at array index OFFSET for
+ SIZES/KINDS, incrementing the offsets after each assignment. */
+
void
gfc_omp_deep_mapping (const gimple *ctx, tree clause,
unsigned HOST_WIDE_INT tkind, tree data,
diff --git a/gcc/langhooks.cc b/gcc/langhooks.cc
index e2c7735596e..d55e2ca7856 100644
--- a/gcc/langhooks.cc
+++ b/gcc/langhooks.cc
@@ -646,7 +646,8 @@ lhd_omp_array_size (tree, gimple_seq *)
return NULL_TREE;
}
-/* Returns true when additional mappings for a decl are needed. */
+/* Return false, implying that no additional data-mapping operations
+ are required for the tree containing a map clause. */
bool
lhd_omp_deep_mapping_p (const gimple *, tree)
@@ -654,7 +655,8 @@ lhd_omp_deep_mapping_p (const gimple *, tree)
return false;
}
-/* Returns number of additional mappings for a decl. */
+/* Return NULL_TREE, implying that no additional data-mapping operations
+ are required for the tree containing a map clause. */
tree
lhd_omp_deep_mapping_cnt (const gimple *, tree, gimple_seq *)
@@ -662,7 +664,8 @@ lhd_omp_deep_mapping_cnt (const gimple *, tree, gimple_seq *)
return NULL_TREE;
}
-/* Do the additional mappings. */
+/* Do nothing as no additional data-mapping operations
+ are required for the second argument that contains a map clause. */
void
lhd_omp_deep_mapping (const gimple *, tree, unsigned HOST_WIDE_INT, tree, tree,
diff --git a/gcc/langhooks.h b/gcc/langhooks.h
index 6eb5c1602f8..cfcb38092d5 100644
--- a/gcc/langhooks.h
+++ b/gcc/langhooks.h
@@ -313,16 +313,25 @@ struct lang_hooks_for_decls
/* Do language specific checking on an implicitly determined clause. */
void (*omp_finish_clause) (tree clause, gimple_seq *pre_p, bool);
- /* Additional language-specific mappings for a decl; returns true
- if those may occur. */
+ /* Return true if for the passed OpenMP 'map' CLAUSE, additional data-mapping
+ is required; CTX_STMT is the gimple statement containing the clause.
+ Otherwise, false is returned. */
bool (*omp_deep_mapping_p) (const gimple *ctx_stmt, tree clause);
- /* Additional language-specific mappings for a decl; returns the
- number of additional mappings needed. */
+ /* Return the number of additional data-mappings required for the passed
+ 'map' CLAUSE; CTX_STMT is the gimple statement containing the clause.
+ It is NULL_TREE if known that no such mapping are required and otherwise
+ of type size_type_node and usually non-constant. */
tree (*omp_deep_mapping_cnt) (const gimple *ctx_stmt, tree clause,
gimple_seq *seq);
- /* Do the actual additional language-specific mappings for a decl. */
+ /* If no additional data-mapping is required for the passed 'map' CLAUSE that
+ is part of the CTX_SMT gimple statement, the function has no effect.
+ Otherwise, DATA refers to a void-pointer array containing the address values
+ of the mapping while SIZE and KINDS are arrays for the to-be mapped size and
+ the map kind; OFFSET_DATA and OFFSET are size_type_node variable that refer
+ to the array index of DATA and SIZE/KIND, respectively and are incremented
+ whenever an element is added. New gimple code is added to SEQ. */
void (*omp_deep_mapping) (const gimple *stmt, tree clause,
unsigned HOST_WIDE_INT tkind,
tree data, tree sizes, tree kinds,
