docs: introduce OSLinkTxQueueUsed (ROM call 0x4F4)

[n8pjl]

OSLinkTxQueueUsed is the inverse of OsLinkTxQueueInquire: rather than returning the amount of free space in the tx buffer, it returns the space used.

The routine is only used by AMS as a boolean in OSLinkOpen to determine if link flushing is needed. I cannot find any other use of it in AMS, nor think of any other possible use not covered by OSLinkTxQueueInquire.

[n8pjl]

I went through special effort to keep the CRLF line endings to minimise the diff, but git appears to have changed at least link.h to just a LF when I pushed to github.

[debrouxl]

Thanks for your contribution :)
FTR, the correct name for this function is very likely to be OSLinkTxQueuePending. However, over two decades after the fact, you'd have a very hard time knowing that, unless you somehow got hold of the right version of Julien Muchembled (JM)'s modified VTI, whose accompanying rc68k.h file features 31 ROM_CALL names which have never been second-sourced.
For most of these previously unnamed ROM_CALLs, it can be easily shown that the function / variable does what its name suggests. As a result, a bit more than half of them were documented in the community toolchain, either under the verbatim name (e.g. the 4C6 push_to_dd & 4C7 push_to_dms pair) or under a modified name (e.g. the 49B push_cylin_vector, 4B1 push_polar_vector & 4C2 push_spher_vector trio, or 484 cmd_lu_fact & 485 cmd_qr_fact pair, as I dubbed them).
455, 45B, 468, 46F, 479 + 47A (collision with a library function, anyway), 47F, 480, 487, 494 + 495, 4DC, 4E6 and this 4F4 were never integrated.

If you're finding it weird that TI left out this function, and in fact more than half of these 31 functions, from the public header files (the old ROM_CALL name file, later tiams.h in TIFS), or why a number of internal functions hard to use externally were exported in the ROM_CALL table - you're not alone :)

Usually, git mangles files less than svn does, so isn't it a bit odd that some EOLs got changed ?
Also, watch out for diff noise caused by string comparison order differences between Windows and Wine, e.g. index_rmng_fctrs_start_base vs. index_rmng_fctrs_start_base_tag. I forgot that I had to squelch that, it's been so long since I last used UpdateInclude.

[n8pjl]

I'll be honest, I just made up the name OSLinkTxQueueUsed, and OSLinkTxQueuePending is a better name anyway.

I'm also not too familiar with the history of the rom call documentation process, so your background is very interesting to me. Is there any real reason that these 14 rom calls with existing background never got documented in tigcclib?

I have no clue about the EOL mangling. I was able to keep the diffs as small as possible on my machine, so the conversion is happening between my machine and github. I did notice the reordering in unknown.h (and now I'm realizing that I had at one point deliberately excluded unknown.h from the changelog, but must have added it later.)

After a brief search, I can't find any versions of VTI by Julien Muchembled. Do you happen to have/know where to find the header file included in the emulator?

Cheers,
Peter

[debrouxl]

4F4 may indeed have been a miss of mine, but I think that on average, the 14 ROM_CALLs which were never integrated in GCC4TI:

• either are less useful than the 7 aforementioned ones, 3ED BitmapSizeExt (verbatim), 42F WinToScr (verbatim), 49C push_dense_poly_eval (verbatim because the TIFS documentation gives the implementation of a function with such a name as a usage example for another one), 4CC push_no_solution_found_string (name changed), 4D1 push_subscripted_element (verbatim), 4D2 push_transpose (verbatim), 4F9 push_polar_to_rect_x (name changed), 4FA push_polar_to_rect_y (name changed), 5EE secondary_tag_list (verbatim);
• or have a correct name much harder to guess or work around. That goes especially for 468, 47A and 4E6; 4DC is arguably trivial but there's no other ROM_CALL with a similar name, and if one really needs it, it's trivially open-coded.

Nope, besides my computers / backups, I don't know for sure where to find a copy of JM's modified versions of VTI, either the slightly older one which does not support rc68k.h, or the one which does but has a bug with breakpoints and savestates.