1 DRAFT FOR REVIEW 2 The X Resource Extension 3 Version 1.2 4 Rami Ylimäki 5 rami.ylimaki@vincit.fi 6 7 ❧❧❧❧❧❧❧❧❧❧❧ 8 91. Introduction 10 11The protocol description of X Resource Extension version 1.1 has been 12either lost or has never been written. This specification documents 13version 1.0 based on reverse engineered library and server 14code. Version 1.1 has been accidentally released from the version 15control and while it doesn't have differences to version 1.0, this 16version is labeled 1.2 in order to remove the risk of confusion. In 17addition to the 1.0 description, this document introduces a new 1.2 18version of the extension. 19 20Version 1.2 is a minor release and therefore the changes are 21compatible with the previous version. Main enhancements over version 221.0 are: 23 24- Client identification is now possible. For example, servers 25 supporting version 1.2 may report PID of local clients. 26 27- Size of any resource can be queried from the server. Servers may not 28 necessarily support size calculation for every resource. However, 29 clients have now at least the chance to let the server do resource 30 size estimation for them. 31 32 ❧❧❧❧❧❧❧❧❧❧❧ 33 342. Notations used in this document 35 36Notation for data types and requests follows the guidelines set in 37sections 2-4 of X Window System Protocol standard. 38 39 ❧❧❧❧❧❧❧❧❧❧❧ 40 413. Interoperability between version 1.1 and 1.2 42 43Version 1.2 only introduces two new requests. However, these requests 44could be seen as generalized versions of existing requests. Even 45though we aren't deprecating any old requests, libraries could 46implement some old requests using the new ones. 47 48The new XResQueryClientIds request could be used instead of 49XResQueryClients. 50 51The new XResQueryResourceBytes request could be used instead of 52XResQueryClientPixmapBytes. 53 54Using the old requests is still acceptable because we don't want to 55change the semantics of existing requests between version 1.1 and 1.2. 56 57 ❧❧❧❧❧❧❧❧❧❧❧ 58 594. Data types 60 614.1 Types in version 1.0 62 63CLIENTXIDRANGE [ resource_base: CARD32 64 resource_mask: CARD32 ] 65 66This type is used for reply of XResQueryClients in version 1.1. It 67represents the range of resource allocated for a client and can be 68also used for client identification. 69 70resource_base 71 First resource ID reserved for a client. Used also to identify the 72 clients themselves. 73resource_mask 74 Mask that can be used to identify a client from some resource 75 ID. Just zero the bits indicated by this mask from any resource ID 76 to identify the client that owns the resource. 77 78CLIENTXID [ client: XID ] 79 80This type identifies a single client by a resource owned by that 81client or by the first resource ID allocated for the client 82(resource_base of CLIENTXIDRANGE). Whenever a resource ID is used, it 83is masked by resource_mask of CLIENTXIDRANGE to find out the client 84that owns the resource. 85 86CLIENTRESOURCETYPECOUNT [ resource_type: ATOM 87 count: CARD32 ] 88 89This type is used for reply of XResQueryClientResources in version 901.1. It represents the number of certain type of resources that are 91owned by some client. 92 93resource_type 94 Atom specifying the type of a resource. 95count 96 Number of resources of the given type owned by a client. 97 984.2 Types in version 1.2 99 1004.2.1 Types used by XResQueryClientIds 101 102CLIENTIDMASK { ClientXid = 0x1, LocalClientPid = 0x2 } 103 104A bitmask specifying a client identification method. Currently only 105the PID of local clients is supported in the form of 106LocalClientPid. ClientXid is provided for backward compatibility with 107version 1.0 so that the new 1.2 requests (XResQueryClientIds) can be 108used in place of the older ones (XResQueryClients). 109 110CLIENTIDSPEC [ client: CLIENTXID or None 111 mask: SETofCLIENTIDMASK or None ] 112 113A data structure for selecting client IDs. 114 115client 116 ID of a resource allocated for some client. Only the part 117 identifying a client is actually used. The resource_base of 118 CLIENTXIDRANGE can be used if the client doesn't own any 119 resources. However, any resource ID is accepted because that makes 120 identifying the owners of existing resources easy. The null 121 resource None can be used to select all clients. 122mask 123 Collection of identification methods that should be applied on the 124 client. The special value None can be used to apply all supported 125 identification methods. 126 127CLIENTIDVALUE [ spec: CLIENTIDSPEC 128 length: CARD32 129 value: LISTofCARD32 ] 130 131A data structure specifying a single client ID. 132 133spec 134 A unique identifier for a specific ID of some client. Wildcards 135 such as None and bitmask unions aren't allowed. The data structure 136 must always identify a single client and single ID type. However, 137 the client doesn't have to be specified as the resource_base of 138 CLIENTXIDRANGE and can be any resource owned by the client. 139length 140 Specifies the length of an ID in units of CARD32. The length 141 depends on the ID type. In version 1.2 the lengths are 0 for 142 ClientXid and 4 for LocalClientPid. The length of ClientXid is 0 143 because that is already stored in the spec field. 144value 145 Actual ID data. In version 1.2 this is missing for ClientXid and 146 consists of a single CARD32 for LocalClientPid. 147 1484.2.2 Types used by XResQueryResourceBytes 149 150To better understand how resources are related to each other, it's 151useful to introduce the concepts of main resource and cross 152reference. By main resource we just mean a normal resource that has a 153valid XID. By cross reference we mean a resource that is used by some 154other resource. 155 156The same resource may have both of these roles depending on the 157context. For example, there could be an ordinary pixmap resource. When 158we talk about this resource in isolation the term main resource is 159used. We call the exact same resource a cross reference when we are 160concentrating on some higher level resource, such as window or 161graphics context, that is using the lower level resource. Cross 162references may also be internal server resources that don't have a 163valid XID. 164 165RESOURCEIDSPEC [ resource: XID or None 166 type: ATOM or None/AnyPropertyType ] 167 168A data structure for selecting or identifying resources. The 169interpretation of fields changes depending on the context. The 170differences in interpretation are described below. 171 172resource 173 An XID of a resource. The null resource None can be used to select 174 all resources matching some type if the data structure is used in 175 XResQueryResourceBytes request. The null resource None can be used 176 to mark private server resources if the data structure is used in 177 a cross reference of XResQueryResourceBytes reply. 178type 179 An atom identifying the resource type. The null atom 180 None/AnyPropertyType can be used to select all resource types 181 matching some resource ID if the data structure is used in 182 XResQueryResourceBytes request. 183 184RESOURCESIZESPEC [ spec: RESOURCEIDSPEC 185 bytes: CARD32 186 ref_count: CARD32 187 use_count: CARD32 ] 188 189A data structure specifying the size of a single resource. 190 191spec 192 Uniquely identifies a single resource. Wildcards such as None and 193 AnyPropertyType aren't allowed for main resources. In cross 194 references, None is used to mark internal server resources. 195bytes 196 Number of bytes allocated for the resource. The size of a resource 197 is never divided by a reference count. This is the number of bytes 198 released in server when there are no more references left to the 199 resource. 200ref_count 201 Number of total users of the resource. Typically the reference 202 count is 1 but for pixmaps and other resources used from different 203 contexts the count may be larger. 204use_count 205 Number of times the resource is used by some other resource. For 206 main resources this is typically 1, because a resource doesn't 207 usually use itself recursively. For cross references this is the 208 number of times the resource is used and is also 1 usually. 209 210RESOURCESIZEVALUE [ size: RESOURCESIZESPEC 211 num_cross_references: CARD32 212 cross_references: LISTofRESOURCESIZESPEC ] 213 214A data structure specifying sizes of cross references to other 215resources in addition to the main resource size. 216 217size 218 Size of a main resource. 219num_cross_references 220 Number of cross references to other resources from the main 221 resource. Currently resources can only have pixmaps as cross 222 references but this can be extended to other types in the 223 future. For simple resources this field is therefore 0 and the 224 cross_references list is missing. 225cross_references: 226 Size specifications for cross references. Note that cross 227 references may contain resources that don't have a valid XID. For 228 example, a DRI2 drawable might have a cross reference to a private 229 pixmap that is used internally in the server only. These private 230 cross references are contained in this list also. This makes it 231 possible to emulate XResGetClientPixmapBytes with 232 XResGetResourceBytes. 233 234 ❧❧❧❧❧❧❧❧❧❧❧ 235 2365. Requests 237 2385.1 Requests in version 1.0 239 240┌─── 241 XResQueryVersion 242 client_major: CARD8 243 client_minor: CARD8 244 ▶ 245 server_major: CARD16 246 server_minor: CARD16 247└─── 248 249The client sends the highest supported version to the server and the 250server sends the highest version it supports, but no higher than the 251requested version. Major version changes can introduce 252incompatibilities in existing functionality, minor version changes 253introduce only backward compatible changes. It is the client's 254responsibility to ensure that the server supports a version which is 255compatible with its expectations. 256 257client_major 258 Major X Resource Extension version supported by client. 259client_minor 260 Minor X Resource Extension version supported by client. 261server_major 262 Highest version supported by server that is compatible with 263 client. 264server_minor 265 Highest version supported by server that is compatible with 266 client. 267 268┌─── 269 XResQueryClients 270 ▶ 271 num_clients: CARD32 272 clients: LISTofCLIENTXIDRANGE 273└─── 274 275The request asks X server to return the list of all currently 276connected clients. 277 278num_clients 279 Number of currently connected clients. 280clients 281 List of XID ranges allocated for the connected clients. 282 283┌─── 284 XResQueryClientResources 285 client: CLIENTXID 286 ▶ 287 num_types: CARD32 288 types: LISTofCLIENTRESOURCETYPECOUNT 289 290 Errors: Value 291└─── 292 293This request can be used to ask the number of resources owned by a 294client. The server will return the counts of each type of resource. 295 296client 297 An XID in the resource range of a client. This identifies the 298 client and not some specific resource. 299num_types 300 Number of different resource types owned by the client. 301types 302 A list of counts for each resource type. 303 304A value error is generated if invalid resource or client XID is given 305in the request. 306 307┌─── 308 XResQueryClientPixmapBytes 309 client: CLIENTXID 310 ▶ 311 bytes: CARD32 312 bytes_overflow: CARD32 313 314 Errors: Value 315└─── 316 317This request is used to get the pixmap usage of some client. The 318returned number is a sum of memory usage of each pixmap that can be 319attributed to the given client. Ideally the server goes through all 320pixmaps and divides each pixmap size by the pixmap reference count to 321get a pixmap reference size. The reference size is then added to the 322returned sum if the client happens to be referencing that pixmap. In 323practice some pixmap references may be missed, because it would be too 324difficult to keep track of all pixmap references. However, the server 325will check the most important client resources that are using pixmaps 326and tries to estimate the pixmap usage as well as is possible. In 327other words, the server need only make a best-effort attempt to 328calculate resource source, so actual resource size may differ from 329that reported in practice. 330 331client 332 Identifies a client by an ID in its resource ID range. 333bytes: 334 Number of bytes attributed to pixmap references from the client 335 resources. 336bytes_overflow: 337 Higher order word for the bytes field in case the sum of pixmap 338 reference sizes doesn't fit in CARD32. 339 340A value error is generated if invalid resource or client XID is given 341in the request. 342 3435.2 Requests in version 1.2 344 345┌─── 346 XResQueryClientIds 347 num_specs: CARD32 348 client_specs: LISTofCLIENTIDSPEC 349 ▶ 350 num_ids: CARD32 351 client_ids: LISTofCLIENTIDVALUE 352 353 Errors: Value 354└─── 355 356XResQueryClientIds can be used to identify a given set of clients with 357some identification method. The request sends a list of specifiers 358that select clients and identification methods to server. The server 359then tries to identify the chosen clients using the identification 360methods specified for each client. The server returns IDs for those 361clients that were successfully identified. It's not an error condition 362if some identification method couldn't be applied to a client. If the 363server is unable to identify some clients, they simply aren't included 364in the returned list. 365 366The request supports wildcards in the client specifications so that in 367the most general case all IDs of all clients can be queried with a 368single CLIENTIDSPEC. 369 370The CLIENTIDSPEC of request and CLIENTIDSPEC of CLIENTIDVALUE in reply 371usually match each other. For example, if a request selected a client 372by a resource ID owned by the client, then the client is identified by 373the same resource ID in the reply. This has been done so that it would 374be easy to identify an owner of some resource. 375 376However, the CLIENTIDSPEC of returned CLIENTIDVALUE never contains any 377wildcards. If the request used a wildcard to specify all clients in a 378single CLIENTIDSPEC, then the reply has expanded the wildcard and 379returns separate CLIENTIDVALUE records for each client. In this case 380wildcarded clients are identified by resource_base of CLIENTXIDRANGE. 381 382The LocalClientPid type of IDs are included in the reply list only if 383the client executing the request asked for it and was also a local 384client itself. It doesn't make sense for remote clients to ask PIDs of 385local clients. 386 387num_specs 388 Number of client ID specifications. 389client_specs 390 A list specifying identification methods for clients. Supports 391 multiple identification methods and clients in a single 392 specification. See CLIENTIDSPEC for details. 393num_ids 394 Number of IDs that were successfully determined. Can be different 395 from num_specs or even zero if the server didn't support any 396 identification methods for the given clients. 397client_ids 398 A list specifying ID information for successfully identified 399 clients. If wildcards were used in a single CLIENTIDSPEC of 400 client_specs, then multiple CLIENTIDVALUE records may be returned 401 for that CLIENTIDSPEC. See CLIENTIDVALUE for details. 402 403A Value error is returned if the request specifies an invalid client 404XID or invalid identification method type. 405 406┌─── 407 XResQueryResourceBytes 408 client: CLIENTXID or None 409 num_specs: CARD32 410 resource_specs: LISTofRESOURCEIDSPEC 411 ▶ 412 num_sizes: CARD32 413 sizes: LISTofRESOURCESIZEVALUE 414 415 Errors: Atom, Value 416└─── 417 418XResQueryResourceBytes can be used to ask the sizes of resources from 419X server. The request sends a list of specifiers that selects 420resources for size calculation. The server tries to calculate the 421sizes of chosen resources and returns an estimate for a resource only 422if the size could be determined. It's not an error condition if a size 423couldn't be calculated. In that case the resources simply aren't 424included in the returned list. 425 426The request supports wildcards so that in the most general case sizes 427of all resources of all clients can be queried with a single 428RESOURCEIDSPEC. However, the reply has all wildcards expanded and 429reports a size of a single resource in each RESOURCESIZEVALUE. 430 431client 432 An ID of a client can be given to limit the query to resources of 433 that client. Just like in CLIENTIDSPEC, any resource ID can be 434 given to identify a client and None can be used if the query 435 shouldn't be limited to a specific client. Note that in some cases 436 this field is redundant because resource_specs already fully 437 determines which resources are selected. If the client ID doesn't 438 match the owner of any resource in resource_specs, no sizes are 439 returned and no error is generated. 440num_specs 441 Number of resource specifications. 442resource_specs 443 A list of resource specifications. Each specification can either 444 uniquely identify a single resource or multiple resources if 445 wildcarding is used. See RESOURCEIDSPEC for details. 446num_sizes 447 Number of resources whose size could be determined. Can be 448 different from num_specs or even zero if the server didn't support 449 size calculation for the given resources. 450sizes 451 A list of resource sizes. Each resource size is linked to a unique 452 resource. Wildcards are never used in the returned size 453 records. For example, it's not possible to receive a single 454 RESOURCESIZEVALUE that would specify the size of all pixmaps if 455 the sizes of pixmap type resources were asked. Instead, a single 456 RESOURCESIZEVALUE would be returned for each pixmap in that case. 457 458An Atom error is returned if the request specifies an invalid resource 459type. A Value error is returned if the request specifies an invalid 460XID for a client or a resource. 461 462 ❧❧❧❧❧❧❧❧❧❧❧ 463