From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from ma1-aaemail-dr-lapp02.apple.com (ma1-aaemail-dr-lapp02.apple.com [17.171.2.68]) by mx.groups.io with SMTP id smtpd.web08.4440.1618544943796089302 for ; Thu, 15 Apr 2021 20:49:04 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@apple.com header.s=20180706 header.b=BCLs4Am2; spf=pass (domain: apple.com, ip: 17.171.2.68, mailfrom: afish@apple.com) Received: from pps.filterd (ma1-aaemail-dr-lapp02.apple.com [127.0.0.1]) by ma1-aaemail-dr-lapp02.apple.com (8.16.0.42/8.16.0.42) with SMTP id 13G3XNbp015349; Thu, 15 Apr 2021 20:49:03 -0700 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=apple.com; h=from : message-id : content-type : mime-version : subject : date : in-reply-to : cc : to : references; s=20180706; bh=f7RcrhIn1zETbDfEu3pPgISsn0gJXfooHgs1pjKRrfU=; b=BCLs4Am2RrCFAVpNullKNge29S1pn+KvL4L07X52RA9q7zG/6F3tyUbN1w5gB7wlvknX mx+k9uGJ02kGZyCF89tIIOxxVREi6lBG7GRxGOwIR2IwAyhL6VPFvnYKCW9sVeO0WcaG 1ngtanuxPujjIKGfVUxSN/DmCIKMeBRJ1X8ghWknp7j89xGx4xU4rD8crIMJabx64fC/ gtCp7h2MLPUYieeyyvqGHQf7nHX9gKU22dcnIaIgw4QuqSUHELERgx9HXdNGnW5oOI6p z6luuycW0onsGLCMPPgRZxkFWgYClrfiYDPLdcbOu3drlhFChLrERs4wraPDfCdUGfPp CA== Received: from rn-mailsvcp-mta-lapp02.rno.apple.com (rn-mailsvcp-mta-lapp02.rno.apple.com [10.225.203.150]) by ma1-aaemail-dr-lapp02.apple.com with ESMTP id 37u8ptvgkk-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128 verify=NO); Thu, 15 Apr 2021 20:49:02 -0700 Received: from rn-mailsvcp-mmp-lapp01.rno.apple.com (rn-mailsvcp-mmp-lapp01.rno.apple.com [17.179.253.14]) by rn-mailsvcp-mta-lapp02.rno.apple.com (Oracle Communications Messaging Server 8.1.0.7.20201203 64bit (built Dec 3 2020)) with ESMTPS id <0QRN00DAB19Q40D0@rn-mailsvcp-mta-lapp02.rno.apple.com>; Thu, 15 Apr 2021 20:49:02 -0700 (PDT) Received: from process_milters-daemon.rn-mailsvcp-mmp-lapp01.rno.apple.com by rn-mailsvcp-mmp-lapp01.rno.apple.com (Oracle Communications Messaging Server 8.1.0.7.20201203 64bit (built Dec 3 2020)) id <0QRN00B00120YB00@rn-mailsvcp-mmp-lapp01.rno.apple.com>; Thu, 15 Apr 2021 20:49:02 -0700 (PDT) X-Va-A: X-Va-T-CD: d92f7c5769af4c05fe8bf567cb7b8f6c X-Va-E-CD: 4730c80ee67030d4f2c83e40b4ab0357 X-Va-R-CD: 6f0325faf294bd23a6d751c620be9d51 X-Va-CD: 0 X-Va-ID: 3085c51c-c426-43ee-a9f9-78bd3ed86966 X-V-A: X-V-T-CD: d92f7c5769af4c05fe8bf567cb7b8f6c X-V-E-CD: 4730c80ee67030d4f2c83e40b4ab0357 X-V-R-CD: 6f0325faf294bd23a6d751c620be9d51 X-V-CD: 0 X-V-ID: 2abc827d-0ead-4efb-b74e-cd366d58575e X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:6.0.391,18.0.761 definitions=2021-04-15_11:2021-04-15,2021-04-15 signatures=0 Received: from [17.235.19.21] (unknown [17.235.19.21]) by rn-mailsvcp-mmp-lapp01.rno.apple.com (Oracle Communications Messaging Server 8.1.0.7.20201203 64bit (built Dec 3 2020)) with ESMTPSA id <0QRN00L1J19O9B00@rn-mailsvcp-mmp-lapp01.rno.apple.com>; Thu, 15 Apr 2021 20:49:01 -0700 (PDT) From: "Andrew Fish" Message-id: <1CCF2090-5CBF-4038-B36D-88D9910B598F@apple.com> MIME-version: 1.0 (Mac OS X Mail 14.0 \(3654.20.0.2.1\)) Subject: Re: [edk2-devel] VirtIO Sound Driver (GSoC 2021) Date: Thu, 15 Apr 2021 20:48:59 -0700 In-reply-to: <4f029f76-0f11-f229-af04-2407ac80308b@ipxe.org> Cc: edk2-devel-groups-io , Mike Kinney , Leif Lindholm , Laszlo Ersek , "Desimone, Nathaniel L" , Rafael Rodrigues Machado , Gerd Hoffmann To: Ethin Probst , Michael Brown References: <16758FB6436B1195.32393@groups.io> <4AEC1784-99AF-47EF-B7DD-77F91EA3D7E9@apple.com> <309cc5ca-2ecd-79dd-b183-eec0572ea982@ipxe.org> <16762C957671127A.12361@groups.io> <4f029f76-0f11-f229-af04-2407ac80308b@ipxe.org> X-Mailer: Apple Mail (2.3654.20.0.2.1) X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:6.0.391,18.0.761 definitions=2021-04-15_11:2021-04-15,2021-04-15 signatures=0 Content-type: multipart/alternative; boundary="Apple-Mail=_82D493E5-A30E-4C2A-A417-4EB44E4F375B" --Apple-Mail=_82D493E5-A30E-4C2A-A417-4EB44E4F375B Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=us-ascii > On Apr 15, 2021, at 6:03 PM, Michael Brown wrote: >=20 > On 16/04/2021 01:59, Ethin Probst wrote: >> Also, I'm a bit confused. I've looked at several VirtIO devices now >> and have seen things like this: >> #define VIRTIO_PCI_DEVICE_SIGNATURE SIGNATURE_32 ('V', 'P', 'C', = 'I') >> // ... >> UINT32 Signature; >> I'm quite confused because I can't seem to find this anywhere in the >> VirtIO specification. The spec says nothing about signature values >> anywhere, just the magic value of 0x74726976. So where does this come >> from? >=20 > =46rom a quick look at the code, it seems to be a private signature = value applied to a software-only data structure used by the UEFI driver, = and is used solely for sanity checking that a pointer is pointing to the = right kind of object. >=20 Ethin, This is a common edk2 code pattern. We have something called a = Containment Record (CR) macro [1] and the DEBUG version of the CR macro = [2] checks the signature. What happens is the public API is a Field in = the private data structure, thus you can convert the This pointer to the = private context of the driver for that protocol instances. The driver = publishes the protocol from the Start() function so that is why the This = pointer is always going to be a member of the larger private context = structure.=20 This pattern is also used for double linked lists as the data structure = to represent the link list is generic and the data is attached to it via = the Containment Record scheme by making that linked list data structure = part of the larger data structure.=20 [1] #define BASE_CR(Record, TYPE, Field) ((TYPE *) ((CHAR8 *) (Record) = - OFFSET_OF (TYPE, Field))) [2]=20 #define CR(Record, TYPE, Field, TestSignature) = \ (DebugAssertEnabled () && (BASE_CR (Record, TYPE, Field)->Signature = !=3D TestSignature)) ? \ (TYPE *) (_ASSERT (CR has Bad Signature), Record) : = \ BASE_CR (Record, TYPE, Field) Thanks, Andrew Fish --Apple-Mail=_82D493E5-A30E-4C2A-A417-4EB44E4F375B Content-Transfer-Encoding: quoted-printable Content-Type: text/html; charset=us-ascii

On Apr 15, 2021, at 6:03 PM, Michael Brown <mcb30@ipxe.org> = wrote:

On 16/04/2021 01:59, Ethin Probst wrote:
Also, I'm a bit = confused. I've looked at several VirtIO devices now
and = have seen things like this:
#define = VIRTIO_PCI_DEVICE_SIGNATURE   SIGNATURE_32 ('V', 'P', 'C', = 'I')
// ...
  UINT32 =             &n= bsp;   Signature;
I'm quite confused = because I can't seem to find this anywhere in the
VirtIO = specification. The spec says nothing about signature values
anywhere, just the magic value of 0x74726976. So where does = this come
from?

=46rom a quick look at the code, it seems to be a private = signature value applied to a software-only data structure used by the = UEFI driver, and is used solely for sanity checking that a pointer is = pointing to the right kind of object.


Ethin,

This is = a common edk2 code pattern. We have something called a Containment = Record (CR) macro [1] and the DEBUG version of the CR macro [2] checks = the signature. What happens is the public API is a Field in the private = data structure, thus you can convert the This pointer to the private = context of the driver for that protocol instances. The driver publishes = the protocol from the Start() function so that is why the This pointer = is always going to be a member of the larger private context = structure. 

This pattern is = also used for double linked lists as the data structure to represent the = link list is generic and the data is attached to it via the Containment = Record scheme by making that linked list data structure part of the = larger data structure. 

[1] #define BASE_CR(Record, TYPE, Field) ((TYPE *) ((CHAR8 = *) (Record) - OFFSET_OF (TYPE, Field)))

[2] 
#define CR(Record, TYPE, Field, = TestSignature) = \
(DebugAssertEnabled () = && (BASE_CR = (Record, TYPE, Field)->Signature !=3D TestSignature)) ? \
(TYPE *) (_ASSERT (CR has Bad = Signature), Record) : = \
BASE_CR (Record, = TYPE, Field)

Thanks,
Andrew Fish

= --Apple-Mail=_82D493E5-A30E-4C2A-A417-4EB44E4F375B--