Author Topic: EDM/2 - The API Project - Undocumented  (Read 3456 times)

Dave Yeo

  • Hero Member
  • *****
  • Posts: 5406
  • Karma: +128/-1
    • View Profile
Re: EDM/2 - The API Project - Undocumented
« Reply #15 on: May 18, 2025, 01:57:57 am »
Seems it is uppercased internally anyways.

Martin Iturbide

  • OS2World NewsMaster
  • Global Moderator
  • Hero Member
  • *****
  • Posts: 5295
  • Karma: +44/-1
  • Your Friend Wil Declares...
    • View Profile
    • Martin's Personal Blog
Re: EDM/2 - The API Project - Undocumented
« Reply #16 on: May 18, 2025, 05:45:29 pm »
Hello

I have a confusion about Device Helper naming.

I don't know if they should be named (for example) "DevHelp_DeRegister" or "DevHlp_DeRegister" (without the 'e')

DevHelp Reference
- https://www.edm2.com/index.php/Physical_Device_Driver_(DevHlp)_Functions
- https://www.edm2.com/index.php/PDDREF:Device_Helper_(DevHlp)_Services

DevHlp Reference
- https://www.edm2.com/index.php/List_of_DevHlp_Functions

I'm searching source source code samples on github/os2world and seems that both are used. Are both fine?

Regards
Martin Iturbide
OS2World NewsMaster
... just share the dream.

Dave Yeo

  • Hero Member
  • *****
  • Posts: 5406
  • Karma: +128/-1
    • View Profile
Re: EDM/2 - The API Project - Undocumented
« Reply #17 on: May 18, 2025, 06:54:06 pm »
Code: [Select]
G:\os2tk45>grep -ir devhelp_ *
h/entry.h:  int    (*DevHelp_OpenEventSem)();
h/entry.h:  int    (*DevHelp_SemHandle)();
h/entry.h:  int    (*DevHelp_PostEventSem)();
h/entry.h:  int    (*DevHelp_CloseEventSem)();
h/pddentry.h:extern void DevHelp_RegisterPDD(char *PDD_Name, void *PDD_Function);
h/pddentry.h:extern void *DevHelp_DynamicAPI(short Parm_Count, void *Worker);

Code: [Select]
G:\os2tk45>grep -ir devhlp_ * > out
grep.exe: book/addendum.inf: binary file matches
grep.exe: book/cp2.inf: binary file matches
grep.exe: book/sg244640.inf: binary file matches
grep.exe: write error: Disk full

Which is weird as "G:\os2tk45>grep -ir devhlp_ * | less" shows a few hundred hits. Actually, 158 hits.


Steven Levine

  • Jr. Member
  • **
  • Posts: 80
  • Karma: +12/-0
    • View Profile
Re: EDM/2 - The API Project - Undocumented
« Reply #18 on: May 19, 2025, 12:49:16 am »
Hi,

The Device Helpers interface naming is inconsistent for historical reason.  There is no one base reference for the Device Helpers interface.  If you are going to pick a reference doc to start with, I recommend pdd.ref from the DDK.  For sources, the the DDK headers are the place to start.

You will find references that match "Device Helpers", DeviceHelp, DevHelp, DevHlp and a few others.

As you found, there are some references in the Toolkit sources, but they are far from complete and, TTBOMK, were never used to write device drivers.

Part of the potential confusion is that the Device Helpers are not API functions per se, but rather a set of request codes and data structures passed to a single function.  The kernel passes a pointer to this function to the driver when it passes control a driver for the first time.

What you are finding with functions like DevHelp_RegisterPDD(char *PDD_Name, void *PDD_Function); are bindings defined in various header files that make it easier to call the DevHlp consistently for a given request.  The bindings are available in various forms for various compilers and assemblers.  From the DDK, there's devhlp.lib and the associated devhlp.h.   There's also devhelp.h with a set of OpenWatcom macros.

Martin Iturbide

  • OS2World NewsMaster
  • Global Moderator
  • Hero Member
  • *****
  • Posts: 5295
  • Karma: +44/-1
  • Your Friend Wil Declares...
    • View Profile
    • Martin's Personal Blog
Re: EDM/2 - The API Project - Undocumented
« Reply #19 on: May 19, 2025, 02:15:12 pm »
Thanks for the feedback Steven.

I will be checking devhlp.lib and devhlp.h to get a better idea. It is good to know this inconsistency is for historical reasons.

Regards
Martin Iturbide
OS2World NewsMaster
... just share the dream.

Martin Iturbide

  • OS2World NewsMaster
  • Global Moderator
  • Hero Member
  • *****
  • Posts: 5295
  • Karma: +44/-1
  • Your Friend Wil Declares...
    • View Profile
    • Martin's Personal Blog
Re: EDM/2 - The API Project - Undocumented
« Reply #20 on: May 19, 2025, 04:56:53 pm »
Hello

I also forgot to clarify my intention or what I want to accomplish.

On the EDM/2 wiki you can link thing to other wiki pages. So when I want to link some specifics "Device Helpers", I get the issue should I standardize the names to "DevHlp_" or "DevHelp_".

I haven't decided yet.

Regards
Martin Iturbide
OS2World NewsMaster
... just share the dream.

Martin Iturbide

  • OS2World NewsMaster
  • Global Moderator
  • Hero Member
  • *****
  • Posts: 5295
  • Karma: +44/-1
  • Your Friend Wil Declares...
    • View Profile
    • Martin's Personal Blog
Re: EDM/2 - The API Project - Undocumented
« Reply #21 on: May 19, 2025, 05:14:12 pm »
Hello

On this page: https://www.os2.kr/komh/os2books/smpadd-19970312/046_L2_HighMemorySupportFun.html

There is listed "DosQueryState", and I can not find any reference to that function. I don't think it exists.

Do you think it may be a typo ? Maybe it is "DosQueryMemState"  because it is after "DosQueryMem"???

Regards
« Last Edit: May 19, 2025, 05:22:34 pm by Martin Iturbide »
Martin Iturbide
OS2World NewsMaster
... just share the dream.

Steven Levine

  • Jr. Member
  • **
  • Posts: 80
  • Karma: +12/-0
    • View Profile
Re: EDM/2 - The API Project - Undocumented
« Reply #22 on: May 20, 2025, 09:14:00 am »
I agree that it appears to be a typo.  I was thinking it might have been DosQuerySysState, but since the list is somewhat ordered DosQueryMemState is probably more likely.

Martin Iturbide

  • OS2World NewsMaster
  • Global Moderator
  • Hero Member
  • *****
  • Posts: 5295
  • Karma: +44/-1
  • Your Friend Wil Declares...
    • View Profile
    • Martin's Personal Blog
Re: EDM/2 - The API Project - Undocumented
« Reply #23 on: May 22, 2025, 03:09:56 am »
Hello again.

It still spins on my head if I should do something with the DevHelp_ stuff on the EDM/2.
1) Maybe it is more comfortable to standardize it as DevHelp_ since most of the items listed are that way.
or
2) Just leave it that way, and redirect the different names between DevHelp_ and DevHlp_

And:
3) My other issue is that republishing the SMP Addendum there is the STRACE page when it lists the DevHelp and are some that I do not have. You can check it out here with red color on this page.

Regards
Martin Iturbide
OS2World NewsMaster
... just share the dream.

Steven Levine

  • Jr. Member
  • **
  • Posts: 80
  • Karma: +12/-0
    • View Profile
Re: EDM/2 - The API Project - Undocumented
« Reply #24 on: May 22, 2025, 08:49:11 am »
It really depends on what your goals are.  In general, you will find that the DevHelp prefix is used for C language bindings and DevHlp is used for Assembler bindings.

You can see this pattern if you look at your:

  https://www.edm2.com/index.php/DevHelp_ProcBlock

which looks to me as if it came from pdd.ref.

Notice also that the Assembler bindings are listed before the C bindings implying that they are more likely of more interest.  This is part of history. The kernel and device drivers were originally written in assembler.  It was only later that C became more widely used for device driver development and kernel development.  It would not surprise me if an early version of pdd.ref only documented the Assembler bindings.

This evolution shows up in early books such as Ed Iacobucci's "OS/2 Programmer's Guide" which discusses writing applications in C and Pascal, but all the examples are in Assembler.

The items in red are another case of inconsistent naming.  DevHlp_SortReqPacket is really DevHlp_SortRequest or DevHelp_SortRequest which is in the wiki.  FWIW, DevHlp_SortReqPacket is a better name for the request, but it appears IBM never got around to updating all the references DevHelp_SortRequest, assuming that was the plan.

Martin Iturbide

  • OS2World NewsMaster
  • Global Moderator
  • Hero Member
  • *****
  • Posts: 5295
  • Karma: +44/-1
  • Your Friend Wil Declares...
    • View Profile
    • Martin's Personal Blog
Re: EDM/2 - The API Project - Undocumented
« Reply #25 on: May 22, 2025, 10:09:32 pm »
Thanks for the feedback

My goal right now it to link the DevHelp services related pages on the EDM/2 wiki, so the user can jump from an article to the DevHelp service. 

I'm thinking that I will standarize the article/page names (just the name) to DevHlp_ since it is most used way in IBM documentation, but I will do it little by little.

Thanks for the help with the names that had changed, here it what I had found for the moment, corrections are welcome.

SMPProgAdd - STRACE     || PDDREF:Device Helper (DevHlp)
DevHlp_PushReqPacket    -  DevHlp_PushRequest
DevHlp_PullReqPacket    -  DevHlp_PullRequest
DevHlp_SortReqPacket    -  DevHelp_SortRequest
DevHlp_MonCreate       -  DevHlp_MonitorCreate
DevHlp_AddTraceEvent    -  = DevHlp_SysTrace = DevHlp_RAS
DevHlp_ABIOSGetParms    -  Not found in pddref.inf
DevHlp_Profiling Kernel       - Not found in pddref.inf
DevHlp_RegStackUsage    -  DevHlp_RegisterStackUsage
DevHlp_LogEntry        -  Not found in pddref.inf
DevHlp_SaveMessage    -  DevHlp_Save_Message
DevHlp_ReallocSeg       -  DevHlp_SegRealloc
DevHlp_PutWaitingQueue    - Not found in pddref.inf
DevHlp_GetWaitingQueue    - Not found in pddref.inf


Compare sources:
- https://www.edm2.com/index.php/PDDREF:Device_Helper_(DevHlp)_Services    From pddref.inf
- https://www.edm2.com/index.php/SMPProgAdd_-_STRACE_-_DevHlp_Functions

EDM/2 Lists:
- https://www.edm2.com/index.php/Category:DevHlps
- https://www.edm2.com/index.php/List_of_DevHlp_Functions

Regards

« Last Edit: May 27, 2025, 03:21:25 pm by Martin Iturbide »
Martin Iturbide
OS2World NewsMaster
... just share the dream.

Lars

  • Hero Member
  • *****
  • Posts: 1436
  • Karma: +72/-0
    • View Profile
Re: EDM/2 - The API Project - Undocumented
« Reply #26 on: May 27, 2025, 01:47:34 pm »
DevHlp_AddTraceEvent    -  Not found in pddref.inf

DevHlp_AddTraceEvent = DevHlp_SysTrace = DevHlp_RAS
« Last Edit: May 27, 2025, 02:00:42 pm by Lars »

Martin Iturbide

  • OS2World NewsMaster
  • Global Moderator
  • Hero Member
  • *****
  • Posts: 5295
  • Karma: +44/-1
  • Your Friend Wil Declares...
    • View Profile
    • Martin's Personal Blog
Re: EDM/2 - The API Project - Undocumented
« Reply #27 on: May 27, 2025, 02:38:53 pm »
DevHlp_AddTraceEvent    -  Not found in pddref.inf

DevHlp_AddTraceEvent = DevHlp_SysTrace = DevHlp_RAS

Thanks Lars. I think that it makes sense on the wiki to unify the pages for DevHlp_AddTraceEvent , DevHlp_SysTrace, DevHlp_RAS, and clearly specify that the three are the same one.

But which one should be the final name? (There is not an straight right answer, its more like a suggestions)  :D

DevHlp_AddTraceEvent was the last name used by IBM on the SMP Addedum (I guess), but I don't know if it is the right choice.

Regards


« Last Edit: May 27, 2025, 03:34:02 pm by Martin Iturbide »
Martin Iturbide
OS2World NewsMaster
... just share the dream.

Steven Levine

  • Jr. Member
  • **
  • Posts: 80
  • Karma: +12/-0
    • View Profile
Re: EDM/2 - The API Project - Undocumented
« Reply #28 on: May 27, 2025, 08:42:25 pm »
My choice would be DevHlp_RAS for assembler usage and for DevHelp_RAS for C usage because these are what you will find in pdd.ref and the DDK sources.

FWIW, the references you found to DevHlp_AddTraceEvent and DevHlp_SysTrace in the SMP Addendum are not Device Help definitions.

DevHlp_AddTraceEvent is the description the writer chose for Hook ID 61/34 which represents a location in the kernel code.  I've yet to find any actual Device Helper related code that actually uses this symbol.

DevHlp_SysTrace is part of a comment in the assembly language example for dh_PerfSysTrace.  Again, I've yet to find any actual Device Helper related code that actually uses this symbol.

It probably cannot hunt to mention these alternative references to DevHlp_RAS and DevHelp_RAS, although I'm not sure how I would describe why they exist.

Martin Iturbide

  • OS2World NewsMaster
  • Global Moderator
  • Hero Member
  • *****
  • Posts: 5295
  • Karma: +44/-1
  • Your Friend Wil Declares...
    • View Profile
    • Martin's Personal Blog
Re: EDM/2 - The API Project - Undocumented
« Reply #29 on: May 27, 2025, 09:12:06 pm »
Hello Steven.

You know more than me on this area.
My references are:
1) DevHlp_AddTraceEvent
-- "SMP Programming Addendum" on the "STRACE - DevHlp Functions"

-- sg244640: "Trace Events for DEVHELP Major Code: 0X0006, Sorted by Tracepoint"
--- OS) DevHlp_AddTraceEvent Post-Invocation 00132 (0X0084)
--- OS) DevHlp_AddTraceEvent Pre-Invocation 00004 (0X0004)


2) DevHlp_SysTrace
-- "Programming Guide and Reference Addendum"  on the "Device Helper (DevHlp) Services and Function Codes" at "DevHlp_SysTrace".

There it says "DevHlp_SysTrace is synonymous with DevHlp_RAS."

On "devhlp.inc" from the DDK it has:
Quote
DevHlp_RAS              EQU     40      ; 28    Put info in RAS trace buffer
DevHlp_SysTrace         EQU     40      ; 28    Synonym for DevHlp_RAS   f180062

This is why I guess that DevHlp_RAS and DevHlp_SysTrace  are the same. No idea about "DevHlp_AddTraceEvent".

Regards

« Last Edit: May 27, 2025, 09:36:28 pm by Martin Iturbide »
Martin Iturbide
OS2World NewsMaster
... just share the dream.