From: Daniel Mack Date: Tue, 27 Jan 2015 18:16:00 +0000 (+0100) Subject: doc: kdbus.pool.xml cleanups X-Git-Tag: upstream/0.20150129.081441utc~8 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=15a3a531bdf8985c04513fc5a12920533dfe9316;p=platform%2Fcore%2Fsystem%2Fkdbus-bus.git doc: kdbus.pool.xml cleanups Signed-off-by: Daniel Mack --- diff --git a/doc/kdbus.pool.xml b/doc/kdbus.pool.xml index 7395720..5d34dff 100644 --- a/doc/kdbus.pool.xml +++ b/doc/kdbus.pool.xml @@ -26,7 +26,9 @@ connection of the bus, and is sized according to the information stored in the KDBUS_ITEM_BLOOM_PARAMETER item that is returned by - KDBUS_CMD_HELLO. + KDBUS_CMD_HELLO. Internally, the pool is segmented + into slices, each referenced by its + offset in the pool. @@ -62,13 +64,21 @@ - The offsets returned by either one of the aforementioned ioctls describe offsets - inside the pool. In order to make the slice available for subsequent calls, - KDBUS_CMD_FREE has to be called on the offset (see below). - - To access the memory, the caller is expected to + The offset fields returned by either one of the + aforementioned ioctls describe offsets inside the pool. In order to make + the slice available for subsequent calls, + KDBUS_CMD_FREE has to be called on that offset + (see below). Otherwise, the pool will fill up, and the connection won't + be able to receive any more information through its pool. + + + + Accessing the pool memory + + Memory is the pool is read-only for userspace and may only be written + to by the kernel. To read from the pool memory, the caller is expected to mmap2 - it, like this: + the buffer into its task, like this: /* @@ -81,16 +91,42 @@ buf = mmap(NULL, POOL_SIZE, PROT_READ, MAP_SHARED, conn_fd, 0); - Alternatively, instead of mapping the entire pool buffer, only parts of it can - be mapped. The length of the response is returned by the kernel along with the - offset for each of the ioctls listed above. + The file descriptor used to map the memory must be + the one that was used to create the connection + In other words, the one that was used to call + KDBUS_CMD_HELLO. See + kdbus.connection7 + for more details. + + + + Alternatively, instead of mapping the entire pool buffer, only parts + of it can be mapped. Every kdbus command that returns an + offset (see above) also reports a + size along with it, so userspace can be written + in a way that it only maps portions of the part to access a specific + slice. + + + + When access to the pool memory is no longer needed, userspace should + call + munmap2 + on the pointer returned by + mmap2. - Description + Pool slice allocation - TODO: some words about how slices are alllocated ... + Pool slices are allocated by the kernel in order to report information + back to a userspace task, such as messages, returned name list etc. + Allocation of pool slices cannot be initiated by userspace. See + kdbus.connection7 and + kdbus.names7 + for examples of commands that use the pool to + return data. @@ -98,8 +134,9 @@ buf = mmap(NULL, POOL_SIZE, PROT_READ, MAP_SHARED, conn_fd, 0); Freeing pool slices The KDBUS_CMD_FREE ioctl is used to free a slice - inside the pool, described an offset that was returned in an 'offset' - field of another ioctl struct. The command takes a + inside the pool, describing an offset that was returned in an + offset field of another ioctl struct. + The KDBUS_CMD_FREE command takes a struct kdbus_cmd_free as argument: @@ -200,11 +237,9 @@ struct kdbus_cmd_free { kdbus.bus7 kdbus.connection7 kdbus.endpoint7 - kdbus.fs7 - kdbus.items7 - kdbus.message7 kdbus.names7 - kdbus.pool7 + mmap2 + munmap2