Document ConDrv headers (condrv.h and conmsgl*.h)

[lhecker]

As the ConDrv headers and \Device\ConDrv\Server are undocumented, it:

• Prevents the community from building their own, alternative conhost
• is a hindrance for MS employees to quickly understand how ConDrv works

In the name of #10462 (comment) I'd like to thus ask for ConDrv to be documented.

[malxau]

Can I ask what the expected gain is here?

~Six months ago I went through the exercise of figuring out how this works. The conhost side is straightforward because all of the code pulling from condrv is in the tree, and I'm sure with this any competent dev could write/rewrite/replace the conhost side. The client side was a bit more interesting, because that code would normally be in kernel32.dll but with a usermode debugger and the headers here it wasn't hard to figure out.

What I was trying to do with this exercise was investigate the feasibility of a Win32++ that exposes newer capabilities via a familiar API, and the natural way to do that is with condrv messages. As luck would have it, condrv doesn't do much sanity checking of messages so adding new ones is trivial. I didn't speak to anyone here about it because I thought this isn't something you'd be interested in (with all those deprecation notices on MSDN and all), and eventually lost interest in pursuing it. There is a nice bonus of having a functional/RPC interface, which is the client can detect when the server can't implement something and gracefully fall back.

Ultimately though it ended in a pile of "learnings":

• The condrv API is intrinsically synchronous and the context switches here are killer. Trying to display RGB color squares with my extended Win32 API was painful because it takes two process context switches per cell (set color, write text), and of course has to switch back again. Given a 30usec context switch cost, a 64x64 2D grid of colored cells with 2x2 switches per cell means ~500ms of switches - rendering is extra. Note that the basic console model predates condrv/conhost, so the cost of this interface became more expensive later in its life.
• Following on from the above, there's an "opportunity" to generate and buffer VT sequences on the client so that simple requests can be batched.
• There's very limited opportunities for "mix and match" because conhost is hardcoded to a condrv version, and individual clients will talk whatever version kernel32 implements. Even though it wouldn't be hard to build a functional condrv for Windows XP and run the conhost from this tree on it, no command line programs on XP would talk to it without going full Detours on kernel32.
• Following on from the above, if it becomes a goal to run WT or the conhost from this tree across a broad range of versions of Windows, more condrv version negotiation would be helpful. Because historically all of the components were shipped in a single release, this looks to be quite absent.
• Although open sourcing the existing condrv, or even writing a new one implementing its interface, wouldn't be overly hard, it's not (that) helpful for open source developers given kernel driver signing requirements.

So even as someone who generally finishes anything he starts, this is one thing I walked away from.