[amontoison]

Follow-up to #581: documents and tests the typed and type(c_ptr) forms it introduced.

Docs

docs/how-to/fortran-interfaces.rst gains a section Scalar arguments passed by pointer that explains:

• when to pass the Fortran variable (_typed) and when to pass its address (type(c_ptr)): device address, c_null_ptr for an output that can be skipped, or existing c_loc code;
• the device pointer mode:
  • the routines that mix a pointer-mode scalar with a host output (X_devptr);
  • the array overloads, whose alpha/beta are typed, so the variable itself has to live on the device;
• hipSOLVER devInfo: type(c_ptr) with type(c_ptr) buffers, and an integer(c_int), pointer or a type(c_ptr) with the array overloads;
• how the X_typed/X_devptr names that appear in the reference relate to the generic.

The examples compile against the #581 bindings with gfortran and amdflang. The RST is checked with docutils (beyond the Sphinx :doc: role).

Tests

Until now, alpha/beta only went through the c_loc(alpha) form in CTest. Eight tests now take an existing check through the _typed form, with alpha/beta passed as named constants:

Library	Tests
rocBLAS	dgemm_typed, caxpy_typed
hipBLAS	sgemm_typed, zaxpy_typed
rocSPARSE	rocsparse_dgemvi_typed, rocsparse_dcsrgemm_typed (alpha, beta and buffer_size all typed)
hipSPARSE	hipsparse_dgemvi_typed, hipsparse_zcsrsv2_typed

• Each object references exactly the _typed procedures it targets (checked with nm).
• The two tests that copied an alpha of 1 use 2 and (2,1) instead, so a lost or misread alpha fails the check.
• The _devptr form is already covered by the *_devptr tests (rocSPARSE dcsrgemm/csrgeam...).
• The four f2008 hipsolver_?getrf tests now pass dInfo itself (an integer(c_int), pointer from hipMalloc) instead of c_loc(dInfo), which puts the typed devInfo of the array overloads under CTest and fixes a comment that said "by reference". The other f2008 hipSOLVER tests keep c_loc(dInfo) and cover _rank_N_devptr. hipsolver_dgetrf.f08 is the program the hipSOLVER tutorial shows.

Validation

• gfortran, ROCm 10.1, gfx1101: ctest -R '_typed$' gives 8/8.
• amdflang: all 8 compile.