Confusion about AVStream Properties

I'm confused about the declaration of properties in an AVStream driver.
The samples and the documentation seem to contradict each other, as do the
code I've found through Google.

Let's take an example. We're writing, among others, a TV tuner driver.
Looking in the Europa sample, in the analog tuner properties, we find,
among others:

DEFINE_KSPROPERTY_ITEM
(
KSPROPERTY_TUNER_CAPS,
AnlgTunerCapsGetHandler,
sizeof(KSPROPERTY_TUNER_CAPS_S),
sizeof(KSPROPERTY_TUNER_CAPS_S),
NULL,
NULL,
0,
NULL,
NULL,
0
),
DEFINE_KSPROPERTY_ITEM
(
KSPROPERTY_TUNER_MODE_CAPS,
AnlgTunerCapsGetHandler,
sizeof(KSPROPERTY_TUNER_MODE_CAPS_S),
sizeof(KSPROPERTY_TUNER_MODE_CAPS_S),
NULL,
NULL,
0,
NULL,
NULL,
0
),

Notice the two "sizeof" entries. According to the documentation, the first
one is supposed to have the minimum size needed to identify the request.
The second one is supposed to have the size of the data being read and
written. In both of these entries, BOTH sizes are set to the full
structure, which includes both the KSPROPERTY structure that identifies the
property, and the data to be read/written. I'm conviced the sample is
wrong. Further, if we look at the docuemntation for KSPROPERTY_TUNER_CAPS
and KSPROPERTY_TUNER_MODE_CAPS, in BOTH cases the return value is
documented as a single ULONG.

When we copy the structures above into our own AVStream analog tuner
driver, KSStudio fails to get the properties. Single-stepping through the
code, I see that the upper-level drivers are returning
STATUS_BUFFER_TOO_SMALL.

We know that the analog parts of the Europa sample have never been tested,
so I have no reason to believe the code above is actually correct.
Further, I suspect from other property samples that the first size should
actually be sizeof(KSPROPERTY), and the second size should actually be
sizeof(ULONG).

Does anyone within the sound of my voice have a WORKING AVStream tuner
driver? Can you share with me the definitions of your KSPROPERTY_ITEMS?
--
- Tim Roberts, timr@probo.com
Providenza & Boekelheide, Inc

Max
Mon Nov 08 02:18:48 CST 2004

> DEFINE_KSPROPERTY_ITEM
> (
> KSPROPERTY_TUNER_CAPS,
> AnlgTunerCapsGetHandler,
> sizeof(KSPROPERTY_TUNER_CAPS_S),
> sizeof(KSPROPERTY_TUNER_CAPS_S),
> NULL,
> NULL,
> 0,
> NULL,
> NULL,
> 0
> ),
> DEFINE_KSPROPERTY_ITEM
> (
> KSPROPERTY_TUNER_MODE_CAPS,
> AnlgTunerCapsGetHandler,
> sizeof(KSPROPERTY_TUNER_MODE_CAPS_S),
> sizeof(KSPROPERTY_TUNER_MODE_CAPS_S),
> NULL,
> NULL,
> 0,
> NULL,
> NULL,
> 0
> ),

This is exactly what I have in my working analog driver.
Works fine.


> Notice the two "sizeof" entries. According to the documentation, the
> first
> one is supposed to have the minimum size needed to identify the request.
> The second one is supposed to have the size of the data being read and
> written. In both of these entries, BOTH sizes are set to the full
> structure, which includes both the KSPROPERTY structure that identifies
> the
> property, and the data to be read/written. I'm conviced the sample is
> wrong. Further, if we look at the docuemntation for KSPROPERTY_TUNER_CAPS
> and KSPROPERTY_TUNER_MODE_CAPS, in BOTH cases the return value is
> documented as a single ULONG.

They aren't ULONGs in my DDK docs (Server 2003 DDK). Never been ULONGs.
Always been structures. Both of them, actually all of tuner/xbar properties
take structures.


> When we copy the structures above into our own AVStream analog tuner
> driver, KSStudio fails to get the properties. Single-stepping through the
> code, I see that the upper-level drivers are returning
> STATUS_BUFFER_TOO_SMALL.

I never used KSStudio on these drivers so I can't say whether it works or
not.


> Further, I suspect from other property samples that the first size should
> actually be sizeof(KSPROPERTY), and the second size should actually be
> sizeof(ULONG).

That's what the docs say, but on the same line they say "at least
sizeof(KSPROPERTY)". This is very confusing. First, they say this is the
minimal size of "property identifier", which I assume is KSPROPERTY. So it
should be sizeof(KSPROPERTY), period. At the same time they say "at least
sizeof(KSPROPERTY)". Go figure.

This is how I understand it.

Typical property handler takes an identifier (pKsIdentifier) and data
(pData).
NTSTATUS ProcessProperty( PIRP pIrp, PKSIDENTIFIER pKsIdentifier, PVOID
pData )

Frequently for both "get" and "set" handlers identifier is KSIDENTIFIER and
pData is the data value (ULONG, for example). This is usual case in BDA.
Sometimes (mostly for legacy cases) however they pass "the whole thing" as
an identifier (for your case it is KSPROPERTY_TUNER_MODE_CAPS_S) while pData
points to the value being set or where to put returned data (also
KSPROPERTY_TUNER_MODE_CAPS_S). Why? To support receive-modify-return cases.
Some of xbar properties fall under this category. There is no way the
property can be modified in-place so what they usually do is to copy
identifier to pData and then modify pData.

All of this is fairly contrived and less than obvious.

Documentation for particuar property is usually very specific what it passes
around as property descriptor and property value.
MS should've made it more straightforward - every property handler receives
KSIDENTIFIER, input buffer and output buffer. Period. Plain and simple. No
special cases. Nothing in KS is plain and simple unfortunately.

-- Max.

Tim
Mon Nov 08 23:52:30 CST 2004

"Max Paklin" <mpaklin@hotmail.com> wrote:

>> DEFINE_KSPROPERTY_ITEM
>> (
>> KSPROPERTY_TUNER_CAPS,
>> AnlgTunerCapsGetHandler,
>> sizeof(KSPROPERTY_TUNER_CAPS_S),
>> sizeof(KSPROPERTY_TUNER_CAPS_S),
>> NULL,
>> NULL,
>> 0,
>> NULL,
>> NULL,
>> 0
>> ),
>> DEFINE_KSPROPERTY_ITEM
>> (
>> KSPROPERTY_TUNER_MODE_CAPS,
>> AnlgTunerCapsGetHandler,
>> sizeof(KSPROPERTY_TUNER_MODE_CAPS_S),
>> sizeof(KSPROPERTY_TUNER_MODE_CAPS_S),
>> NULL,
>> NULL,
>> 0,
>> NULL,
>> NULL,
>> 0
>> ),
>
>This is exactly what I have in my working analog driver.
>Works fine.

Yes, after a day of experimentation, I now believe the second sizeof is
correct, but the first one can be sizeof(KSPROPERTY) in all cases but
TUNER_MODE_CAPS, where the minimum is sizeof(KSPROPERTY)+size(ULONG).

Indeed, our tuner driver works fine in GraphEdt and AmCap, but Media Center
Edition 2005 will not recognize it. Has your analog driver ever been tried
in MCE?

>> ... In both of these entries, BOTH sizes are set to the full
>> structure, which includes both the KSPROPERTY structure that identifies
>> the property, and the data to be read/written. I'm conviced the sample is
>> wrong. Further, if we look at the docuemntation for KSPROPERTY_TUNER_CAPS
>> and KSPROPERTY_TUNER_MODE_CAPS, in BOTH cases the return value is
>> documented as a single ULONG.
>
>They aren't ULONGs in my DDK docs (Server 2003 DDK). Never been ULONGs.
>Always been structures. Both of them, actually all of tuner/xbar properties
>take structures.

Go look at stream.chm, and look in the index for KSPROPERTY_TUNER_MODE:

--- quote ---
KSPROPERTY_TUNER_MODE
User-mode clients use the KSPROPERTY_TUNER_MODE property to get or set the
tuning mode of a device, such as analog TV, digital TV, FM, AM, or DSS.
This property must be implemented.

Get Set Target Property descriptor type Property value type
Yes Yes Pin KSPROPERTY_TUNER_MODE_S ULONG
--- end quote ---

I now think that the "property value type" in that page is just nuts, but
there are so many ways to interpret the documentation that it's hard to
know exactly what is right. I do know that KSPROPERTY_TUNER_MODE works
properly if:
* the tuner driver has
sizeof(KSPROPERTY),
sizeof(KSPROPERTY_TUNER_MODE_S),
and
* the calling application passes NULL for instance data, and a
KSPROPERTY_TUNER_MODE_S for the property data.

>Documentation for particuar property is usually very specific what it passes
>around as property descriptor and property value.

The big problem is that none of the documentation pages use the same
terminology. It's almost like a conspiracy. The pages for the individual
properties use the terms "property descriptor type" and "property value
type". If you look at the description of KSPROPERTY_ITEM, we're supposed
to define the minimum size for the "property identifier", and the minimum
size for the "data". Where did the term "property identifier" come from?
Is that the same as "property descriptor"? Is the "data" supposed to
include the KSPROPERTY? Some do, some don't.

Even worse, go look at IKsPropertySet::Get. The user-mode app is supposed
to pass in InstanceData and PropertyData. Where did the term
"InstanceData" come from? How does it relate to "property descriptor type"
and "property identifier"? Why should it be so hard?

After disassembling, I now know a little bit more about it. The user-mode
app's InstanceData is all of the INPUT fields beyond the KSPROPERTY.
Unfortunately, the documentation does not tell us what those fields are.
For all of the tuner properties except TUNER_MODE_CAPS, the driver's
"property identifier" is a KSPROPERTY, and the user-mode app can specify
NULL for the InstanceData. For TUNER_MODE_CAPS, the minimum "property
identifoer" in the driver is a KSPROPERTY plus a ULONG, so the user-mode
app can specif just a ULONG.

It's boneheaded that it has to be this complicated. There are a certain
number of common and well-defined use cases. Those use cases should be
deterministic and well documented.
--
- Tim Roberts, timr@probo.com
Providenza & Boekelheide, Inc

Max
Tue Nov 09 13:38:50 CST 2004

> Yes, after a day of experimentation, I now believe the second sizeof is
> correct, but the first one can be sizeof(KSPROPERTY) in all cases but
> TUNER_MODE_CAPS, where the minimum is sizeof(KSPROPERTY)+size(ULONG).
>
> Indeed, our tuner driver works fine in GraphEdt and AmCap, but Media
> Center
> Edition 2005 will not recognize it. Has your analog driver ever been
> tried
> in MCE?

No, this is test driver, which we never shipped to anyone.
Your analog driver supports MPEG2 encoding, doesn't it? Aside from the right
property sets support there is a number of things that you have to implement
to keep MCE happy. And no, I don't have the list in my head as I've never
done analog receiver driver for MCE.


> Go look at stream.chm, and look in the index for KSPROPERTY_TUNER_MODE:

I just did. Wow!
Astonishing.
I may be mistaken, but I think the docs are plain wrong. I've always been
passing structures around for the input and mode and it always worked that
way. Maybe I've been lucky all the time?


> Even worse, go look at IKsPropertySet::Get. The user-mode app is supposed
> to pass in InstanceData and PropertyData. Where did the term
> "InstanceData" come from? How does it relate to "property descriptor
> type"
> and "property identifier"? Why should it be so hard?

It shouldn't.
Different pieces were written by completely different people at different
point. This is bad.


> It's boneheaded that it has to be this complicated. There are a certain
> number of common and well-defined use cases. Those use cases should be
> deterministic and well documented.

I agree.
For myself I learned the hard way (or through friends on site) what needs to
be done when, wrote the code that works and never touched the subject ever
again. I just do a copy-paste when needed without giving it much thought.
Every time I start thinking about it I get a headache.

-- Max.

huengpei
Sat Jan 29 09:23:02 CST 2005

Dear All:

I have met a same situation for another property
KSPROPERTY_VIDEOCONTROL_FRAME_RATES in the AVStream driver.
I need support mulitple different framerates for one video stream.
In a traditional Streaming Minidriver, we can set the
NumberOfBytesToTransfer member of the SRB structure to the size of returned
buffer.
However, in the AVStream, I can not access SRB.
I don't know how to return the size information to user-mode application.

Who can give me some suggetions?
Can I get the SRB of the KSPROPERTY_VIDEOCONTROL_FRAME_RATES property?

"Tim Roberts" wrote:

> I'm confused about the declaration of properties in an AVStream driver.
> The samples and the documentation seem to contradict each other, as do the
> code I've found through Google.
>
> Let's take an example. We're writing, among others, a TV tuner driver.
> Looking in the Europa sample, in the analog tuner properties, we find,
> among others:
>
> DEFINE_KSPROPERTY_ITEM
> (
> KSPROPERTY_TUNER_CAPS,
> AnlgTunerCapsGetHandler,
> sizeof(KSPROPERTY_TUNER_CAPS_S),
> sizeof(KSPROPERTY_TUNER_CAPS_S),
> NULL,
> NULL,
> 0,
> NULL,
> NULL,
> 0
> ),
> DEFINE_KSPROPERTY_ITEM
> (
> KSPROPERTY_TUNER_MODE_CAPS,
> AnlgTunerCapsGetHandler,
> sizeof(KSPROPERTY_TUNER_MODE_CAPS_S),
> sizeof(KSPROPERTY_TUNER_MODE_CAPS_S),
> NULL,
> NULL,
> 0,
> NULL,
> NULL,
> 0
> ),
>
> Notice the two "sizeof" entries. According to the documentation, the first
> one is supposed to have the minimum size needed to identify the request.
> The second one is supposed to have the size of the data being read and
> written. In both of these entries, BOTH sizes are set to the full
> structure, which includes both the KSPROPERTY structure that identifies the
> property, and the data to be read/written. I'm conviced the sample is
> wrong. Further, if we look at the docuemntation for KSPROPERTY_TUNER_CAPS
> and KSPROPERTY_TUNER_MODE_CAPS, in BOTH cases the return value is
> documented as a single ULONG.
>
> When we copy the structures above into our own AVStream analog tuner
> driver, KSStudio fails to get the properties. Single-stepping through the
> code, I see that the upper-level drivers are returning
> STATUS_BUFFER_TOO_SMALL.
>
> We know that the analog parts of the Europa sample have never been tested,
> so I have no reason to believe the code above is actually correct.
> Further, I suspect from other property samples that the first size should
> actually be sizeof(KSPROPERTY), and the second size should actually be
> sizeof(ULONG).
>
> Does anyone within the sound of my voice have a WORKING AVStream tuner
> driver? Can you share with me the definitions of your KSPROPERTY_ITEMS?
> --
> - Tim Roberts, timr@probo.com
> Providenza & Boekelheide, Inc
>

huengpei
Sat Jan 29 09:23:02 CST 2005

Dear All:

I have met a same situation for another property
KSPROPERTY_VIDEOCONTROL_FRAME_RATES in the AVStream driver.
I need support mulitple different framerates for one video stream.
In a traditional Streaming Minidriver, we can set the
NumberOfBytesToTransfer member of the SRB structure to the size of returned
buffer.
However, in the AVStream, I can not access SRB.
I don't know how to return the size information to user-mode application.

Who can give me some suggetions?
Can I get the SRB of the KSPROPERTY_VIDEOCONTROL_FRAME_RATES property?


"Tim Roberts" wrote:

> I'm confused about the declaration of properties in an AVStream driver.
> The samples and the documentation seem to contradict each other, as do the
> code I've found through Google.
>
> Let's take an example. We're writing, among others, a TV tuner driver.
> Looking in the Europa sample, in the analog tuner properties, we find,
> among others:
>
> DEFINE_KSPROPERTY_ITEM
> (
> KSPROPERTY_TUNER_CAPS,
> AnlgTunerCapsGetHandler,
> sizeof(KSPROPERTY_TUNER_CAPS_S),
> sizeof(KSPROPERTY_TUNER_CAPS_S),
> NULL,
> NULL,
> 0,
> NULL,
> NULL,
> 0
> ),
> DEFINE_KSPROPERTY_ITEM
> (
> KSPROPERTY_TUNER_MODE_CAPS,
> AnlgTunerCapsGetHandler,
> sizeof(KSPROPERTY_TUNER_MODE_CAPS_S),
> sizeof(KSPROPERTY_TUNER_MODE_CAPS_S),
> NULL,
> NULL,
> 0,
> NULL,
> NULL,
> 0
> ),
>
> Notice the two "sizeof" entries. According to the documentation, the first
> one is supposed to have the minimum size needed to identify the request.
> The second one is supposed to have the size of the data being read and
> written. In both of these entries, BOTH sizes are set to the full
> structure, which includes both the KSPROPERTY structure that identifies the
> property, and the data to be read/written. I'm conviced the sample is
> wrong. Further, if we look at the docuemntation for KSPROPERTY_TUNER_CAPS
> and KSPROPERTY_TUNER_MODE_CAPS, in BOTH cases the return value is
> documented as a single ULONG.
>
> When we copy the structures above into our own AVStream analog tuner
> driver, KSStudio fails to get the properties. Single-stepping through the
> code, I see that the upper-level drivers are returning
> STATUS_BUFFER_TOO_SMALL.
>
> We know that the analog parts of the Europa sample have never been tested,
> so I have no reason to believe the code above is actually correct.
> Further, I suspect from other property samples that the first size should
> actually be sizeof(KSPROPERTY), and the second size should actually be
> sizeof(ULONG).
>
> Does anyone within the sound of my voice have a WORKING AVStream tuner
> driver? Can you share with me the definitions of your KSPROPERTY_ITEMS?
> --
> - Tim Roberts, timr@probo.com
> Providenza & Boekelheide, Inc
>