From e23f70624f26a054d3e2a146688dbc7f61d0de33 Mon Sep 17 00:00:00 2001 From: "Enrico Weigelt, metux IT consult" Date: Mon, 27 Oct 2025 10:27:38 +0100 Subject: [PATCH] dix: privates: update docs on dixRegisterPrivateKey() a) move to doxygen-style docs, inside the header instead of code b) mention that the function can be called many times with the same parameters (already registered keys are silently tolerated) Signed-off-by: Enrico Weigelt, metux IT consult --- dix/privates.c | 8 -------- include/privates.h | 19 ++++++++++++------- 2 files changed, 12 insertions(+), 15 deletions(-) diff --git a/dix/privates.c b/dix/privates.c index 1c08a3803a..ebcb964297 100644 --- a/dix/privates.c +++ b/dix/privates.c @@ -306,14 +306,6 @@ grow_screen_specific_set(DevPrivateType type, unsigned bytes) }); } -/* - * Register a private key. This takes the type of object the key will - * be used with, which may be PRIVATE_ALL indicating that this key - * will be used with all of the private objects. If 'size' is - * non-zero, then the specified amount of space will be allocated in - * the private storage. Otherwise, space for a single pointer will - * be allocated which can be set with dixSetPrivate - */ Bool dixRegisterPrivateKey(DevPrivateKey key, DevPrivateType type, unsigned size) { diff --git a/include/privates.h b/include/privates.h index 2a16c01b39..5e89b664fc 100644 --- a/include/privates.h +++ b/include/privates.h @@ -94,7 +94,7 @@ typedef struct _DevScreenPrivateKeyRec { #define HAS_DIXREGISTERPRIVATEKEY 1 /* - * Register a new private index for the private type. + * @brief Register a new private index for the private type. * * This initializes the specified key and optionally requests pre-allocated * private space for your driver/module. If you request no extra space, you @@ -102,14 +102,19 @@ typedef struct _DevScreenPrivateKeyRec { * you can get the address of the extra space and store whatever data you like * there. * - * You may call dixRegisterPrivateKey more than once on the same key, but the - * size and type must match or the server will abort. + * Maybe called multiple times on the same key, but the size and type must + * match or the server will abort. * - * dixRegisterPrivateKey returns FALSE if it fails to allocate memory - * during its operation. + * Note: this may move around the private storage area to different address, + * thus any pointers taken by GetPrivateAddr() et al have to be considered + * invalid after calling this function. + * + * @param key pointer to key (will be written to) + * @param type the object type the key is used for + * @param size size of the storage reserved for that key (zero => void*) + * @return FALSE if it fails to allocate memory during its operation. */ -extern _X_EXPORT Bool - dixRegisterPrivateKey(DevPrivateKey key, DevPrivateType type, unsigned size); +_X_EXPORT Bool dixRegisterPrivateKey(DevPrivateKey key, DevPrivateType type, unsigned size); /* * Check whether a private key has been registered